Calling a Web service from Oracle Forms 11g

This tutorial contains the following sections:

Purpose
Time to Complete
Overview
Scenario
Prerequisites
Identifying the Web service
Creating a Web service proxy
Setting up Forms to call the web service
Summary

Purpose
This tutorial covers calling a Web service from Oracle Forms 11g.Using a simple example, you will see how you call a Web service from Oracle
Forms. You will use JDeveloper to build the interface to the Web service with minimum of coding.

Time to Complete
Approximately 30 minutes.

Overview
While this example uses very simple coding examples, it shows how to create a stub for calling an external Web service and then call that stub
from Oracle Forms. This example assumes you are using Oracle Forms 11.1.1.2.0 and JDeveloper 11.1.1.2.0.

Scenario
The scenario for this application will be kept as simple as possible in order to focus on the elements of the technology; however once you have an
understanding of the simple case it can be easily applied to more "real world" examples. The scenario is that from the Oracle Forms "Summit"
order/entry application, you can call a Web service that sends an SMS message to a phone with details about the order.

Prerequisites
Before starting this tutorial, you should:

1. Have access to or have Installed Oracle JDeveloper 11g.

2. Have access to or have installed Forms 11g (Forms Services and Forms Builder).

Identifying the Web service

The first step of this tutorial will be to identify the Web service that provides the SMS messaging capability. There are various registries that
provide this behavior. In this example, Esendex provides a number of different Web services. In particular, the following SMS service provides
various options for sending SMS message. This example will use the SendMessage service. You can register for a free account to test this
service at the following link. (Note that, additional steps MAY be required for an HTTPS web services but this is beyond the scope of this how to).

Creating a Web service proxy

The first step is to create a Java proxy/client that will provide the interface for calling the external Web service.
Create the Application
Set up the Browser Proxy
Create the Web service proxy
Test the web Service
Deploy the Web service proxy

Create the Application

You will now create the application in which your business logic code will be placed.

1. In the Applications Navigator, click New Application or choose File->New and select Applications node.
2. In the Create Application dialog, enter the Application Name WebServicesApp. Notice that as you enter the application name, the
directory name changes automatically.

Select the Application Template Generic Application from the Application Template list.

Click Next

3. In the Step 2 enter the Project Name WebServiceProxy.

 Click Finish.

The Applications Navigator shows the WebServiceApp application and the new project

4. In the Applications Navigator, right-click the WebServiceProxy node and select Project Properties... from the context menu.

5. Select the Compiler node and check the Source Files and Generated Class Files dropdown lists.
 You may change these versions depending on the version of the JRE you are using with Forms to ensure that the compiled classes
from JDeveloper can be read by the JRE used by Form.

It is ok to use 1.6 if you intend to use only Forms 11g.

If you wish to create a Web service proxy for use with Oracle Forms 10g then you would have to choose 1.4 since that is the version
of the JRE used by Forms 10g (Otherwise you may see an "Unsupported major.minor version"). The JAX-WX proxy is only
supported in JRE 1.5. Steps for calling a Web service for Forms 10g can be found here.

6.
Click Save All or select File | Save All to save your work.

Set up the Browser Proxy

If your network uses a proxy for accessing the Internet you will need to tell JDeveloper the name of the proxy. If not, you may omit these steps.

1. From the main menu, choose Tools then Preferences.

2. Click Web Browser and Proxy and then select the Use HTTP Proxy Server. Set the Host Name, Port Number and Exceptions
as required.

Click OK.

Create the Web service proxy

In this section you will create a Web service proxy to call the external Web service.

1. Right-click the new project and select New from the context menu.

In the New Gallery select Web Services under the Business Tier node and then Web Service Proxy.
 Click OK.

2. In the Create Web Service Proxy dialog click Next if the Welcome screen is displayed and accept the default Client Style: JAX-WS
Style.

Click Next.

3. When prompted for the WSDL Document URL paste the URL of the WSDL file for the SendMessage service. At the time of writing,
that URL is currently http://www.esendex.com/secure/messenger/soap/SendService.asmx?wsdl
 Click Next then Finish

4. JDeveloper will now display a Java client file in the code editor. This is the stub that will call the external web service.

5.
Click Save All or select File | Save All to save your work. Then compile all.

Test the web Service

JDeveloper will automatically create a main method in the Web service proxy meaning you can run and test the web service. This proxy (simply a
Java class), should be open in the code editor. Alternatively you can select the class from the Application or System Navigator.

1. In the SendServiceSoapClient you will see a main method with the comment // Add your code to call the desired methods. Add the followings:

// Add your code to call the desired methods.

MessengerHeader header = new MessengerHeader();
header.setAccount("<your account number>");
header.setUsername("<your username>");
header.setPassword("<your password>");
sendServiceSoap.sendMessage("<your phonenumber>","Message from Stub", MessageType.TEXT,header);

Note: Replace the values between < > with your own values
2. You also need to add code to this class so it knows the correct proxy to use if being run outside of the confines of JDeveloper (which it will be when
being called from Forms).

static
{
System.setProperty("http.proxyHost", "<your proxy>");
System.setProperty("http.proxyPort", "<port>");
System.setProperty("http.nonProxyHosts","localhost|<your machine name>");
}

Note: Replace the values between < > with your own values.
The final class should look similar with the following:

Note that, depending on the proxy, assuming you have one, you may also be required to supply a username and password for the proxy. This
would be set in a similar manner to above.

3.
Click Save All or select File | Save All to save your work. Then compile all.

4. Run the class. If everything went fine, the process should exit with 0 and a text message should be received on the phone number specified in the
code.

5. Now, that the web service is accessible, we should implement the sendMessage method by adding the following code:

public String sendMessage (String recipient, String body, MessageType type, MessengerHeader header)
{
sendService = new SendService();
SendServiceSoap sendServiceSoap = sendService.getSendServiceSoap();
header = new MessengerHeader();
header.setAccount("<your account number>");
header.setUsername("<your username>");
header.setPassword("<your password>");
return sendServiceSoap.sendMessage(recipient, body, type, header);
}

This will be the actual method that will be called from Forms.
Deploy the Web service proxy
1. Select File | New in JDeveloper's (11gR1) menu. The New Gallery dialog appears.

Select Deployment Profiles option on the left, then on the right, pick JAR File. Click OK.

2. Accept the defaults in the next dialog and click OK.

3. Take a note of where the jar file is going to be saved then click OK.

4. Accept the defaults and click OK.

5.
Click Save All or select File | Save All to save your work.

6. Right -click on the Project and select Deploy -> archive1. This will deploy the JAR file to the file system.
Setting up Forms to call the web service
The next step is configuring Forms to access the web service client created earlier.

Setting up the CLASSPATH

Importing the Java Code
Calling the imported Java class

Setting up the CLASSPATH

1. Copy the jar file containing the web service client in ORACLE_HOME/forms/java then add the path to this jar in
CLASSPATH.

2 . You may also want to check that the JAR file location is available on the CLASSPATH of your default.env (this is the
default name) file.

Importing the Java Code

1. Open Forms Builder and select Program | Import Java Classes to import the Java code. Expand the tree until you
get to the respective class.
 Select Options in java importer dialog, uncheck Generate persistent names then check Include inherited
methods/fields. Click Close and then click Import in the Import Java Classes screen.

2. Repeat for java.lang.Exception.

Hint: also reference in the CLASSPATH the path to ORACLE_HOME/<jdk_home>/jre/lib/rt.jar and just fill in the
Import Classes field wih java.lang.Exception.

Calling the imported Java class

1. Add the follwing PL/SQL code in a trigger:

DECLARE
jo ora_java.jobject;
xo ora_java.jobject;
rv varchar2(100);
ex ora_java.jobject;
BEGIN
JO := SendServiceSoapClient.new;
RV := SendServiceSoapClient.sendMessage(JO,:BLOCK3.PHONE_NUMBER, :BLOCK3.MESSAGE_BODY, xo, xo);
EXCEPTION
WHEN ORA_JAVA.JAVA_ERROR then
message('Unable to call out to Java, ' ||ORA_JAVA.LAST_ERROR);
WHEN ORA_JAVA.EXCEPTION_THROWN then
ex := ORA_JAVA.LAST_EXCEPTION;
message(Exception_.toString(ex));
END;
2. Compile and run the Form.

Summary
You have used this simple example to identify a Web service, create a stub using JDeveloper 11gR1, and call it from Oracle Forms 11gR1.

Credits

Lead Curriculum Developer: Grant RONALD

Other Contributors:Mircea SIMION, Bogdan CONSTANTIN