SOA for Forms and 4GL Developers: Calling a Web service from Oracle Forms 10.1.2

Purpose

In this tutorial, you are introduced to Web services. Using a simple example, you will see how you call a Web service from Oracle Forms. You will use JDeveloper and Oracle ADF to build the interface to the Web service with minimum of coding.

Time to Complete

Approximately 30 minutes

Topics

This tutorial covers the following topics:

 Overview
 Scenario

Identifying the Web service

Creating a Web service proxy

 Calling a Web service from Oracle Forms
 Summary

Viewing Screenshots

 Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously, so, depending on your Internet connection, may result in a slow response time.)

Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.

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 9.0.4 and JDeveloper 10.1.3.1.

Back to Topic List

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.

Back to Topic List

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 provide a number if 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)

Back to Topic List

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, right-click the Applications node and select New Application... from the context menu.

Place the cursor over this icon to see the image

 

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 No Template [All technologies] from the Application Template dropdown list.

Place the cursor over this icon to see the image

Click OK.

 

3.

In the Create Project dialog, enter the Project Name WebServiceProxy.

Place the cursor over this icon to see the image

Click OK.

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.

Place the cursor over this icon to see the image

 

5.

Select the Compiler node and set the Source and Target dropdown lists to 1.4.

Place the cursor over this icon to see the image

Click OK.

Depending on the version of the JRE you are using with Forms, you will probably have to do this step to ensure that the compiled classes from JDeveloper can be read by the JRE used by Form. Otherwise you would get a "Unsupported major.minor version" error when importing the Java class.

 

6.

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

 

Back to Topic

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.

Place the cursor over this icon to see the image

 

2.

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

Place the cursor over this icon to see the image

Click OK.

 

Back to Topic

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. 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.

Place the cursor over this icon to see the image

click Next then Finish.

 

3.

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

 

4.

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

 

Back to Topic

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 own code here. Add the following:

// Add your own code here
MessengerHeader header = new MessengerHeader();
header.setAccount("<your account number>");
header.setUsername("<your username>");
header.setPassword("<your password> ");
myPort.sendMessage("<your phonenumber>","Message from Stub", MessageType.Text,header);

 

 

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", "yourproxy.uk.oracle.com");
System.setProperty("http.proxyPort", "port number");
System.setProperty("http.nonProxyHosts","|<your machinename>");
}

Place the cursor over this icon to see the image

Note, 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 Save All button or select File | Save All to save your work. Then compile all.

 

4. Right -click on the Java client and select Run from the context menu. This will run the client which will call the Web Service and send the SMS to the phone.
5.

Now that you have tested the main method, you need to update the SendMessage method, since this is the method that will actually be called by Forms.

MessengerHeader header = new MessengerHeader();
header.setAccount("<your account number>");
header.setUsername("<your username>");
header.setPassword("<your password ");
return _port.sendMessage(recipient, body, MessageType.Text, header);

 

6.

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

Back to Topic

 

Deploy the Web service

You have built and tested the Web service proxy from within JDeveloper. In order to call the Web service proxy from Forms, the proxy must be deployed to the file system as a JAR file.

1.

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

In the New Gallery select Deployment Profiles under the General node and then JAR file.

Click OK

 

2.

You can accept the default name and directory (take a note of them).

Place the cursor over this icon to see the image

Click OK

 

3.

The JAR Deployment Profile Properties appears.

Place the cursor over this icon to see the image

Click OK

 

4.

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

 

5.

Right -click on the archive file under the Resources node and select Deploy to JAR file. This will deploy the JAR file to the file system

Place the cursor over this icon to see the image

Back to Topic

Back to Topic List

 

Calling a Web service from Oracle Forms

Now that the Web service proxy has been built, tested and deployed, the next step is to call from Forms

 Setting up the CLASSPATH
 Importing the Java Code
 Calling the imported Java class

Setting up the CLASSPATH

Oracle Forms needs to be able to see the relevant Java files. These files are exposed to Forms by adding to the CLASSPATH environment variable.

1.

On Windows, click Start, Settings then Control Panel from the context menu.

Place the cursor over this icon to see the image

 

2.

Double-click on System. Under Advanced click on Enironment Variables. Select CLASSPATH and then Edit or New.

Add the location of the JAR file created above (including the JAR file name)

Place the cursor over this icon to see the image

Click OK.

 

3.

Download http://download.oracle.com/otn/java/oc4j/101320/wsclient_extended_101320.zip and extract the contained JAR file. Add the location of the JAR file (including the JAR file name) to the CLASSPATH

Click OK on the open dialogs.

 

4.

The JAR file locations also need to be added to your Forms runtime environment so they can be accessed at runtime. To do this, add both JAR file locations to the CLASSPATH of your default.env (this is the default name) file.

If already running, restart OC4J.

 

Back to Topic

 

Importing the Java code

The final step is to show that this Web service can now be easily consumed from your own application code.

1.

Start the Oracle Forms Builder (note that the Builder must be restarted in order to pick up the new CLASSPATH)

 

2.

For the chosen Form, from the menu select Program then Import Java Classes...

Place the cursor over this icon to see the image

Note: for the Java Importer Options, you need to uncheck, Generate persistent names check box. Otherwise, the PL/SQL block will throw compilation errors.

 

3.

Expand the list of Java classes to find the SendServiceSoapClient Java class.

Place the cursor over this icon to see the image

Click Import.

 

4.

In the Import Classes field enter java.lang.String then click Options and check Include inherited mehtods/fields, click OK then click Import.

 

5.

Repeat for java.lang.Exception

Back to Topic

 

 

Calling the imported Java class

The final step is to write the PL/SQL at the appropriate trigger point in the Form.

1.

At the appropriate trigger point add the following code.

DECLARE
jo ora_java.jobject;
xo ora_java.jobject;
rv varchar2(100);
ex ora_java.jobject;
BEGIN
JO := SendServiceSoapClient.new;
RV := SendServiceSoapClient.sendMessage(JO,'you number', 'TXT Message from Forms', 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;

Place the cursor over this icon to see the image

 

2.

Compile and run the Form.

 

Back to Topic

Back to Topic List

 

Summary

You have used this simple example to identify a Web service, create a stub, and call it from Oracle Forms

Back to Topic List

 Place the cursor over this icon to hide all screenshots.