Calling a Web service from Oracle9 i Forms.

Oracle9 i AS Forms Services provides a comprehensive application framework to deploy enterprise-class applications to the Internet with a rich Java interface. A key feature of Oracle Forms is that it provides a number of integration points to allow Forms to communicate with other technologies.

One of the most popular technologies now emerging is Web Services. A Web Service can be used to encapsulate any kind of business information from a whole application to providing a simple service. Oracle Forms allows you to easily integrate Web services with an existing Forms application through the use of the Java Importer.

Calling a Web Service from Forms

In order to call a Web Service from a Forms application, you must complete two main steps. The first is the creation of the Web Service stub, which will be performed through Oracle9i JDeveloper, and the second is to call the stub from the Forms application.

Create a Web Service Stub

The first step will be to create the Web Service stub. In this example, we are going to use a simple Web Service available on the Internet which provide currency conversion. The Web Service is defined by its WSDL. We will use Oracle9i JDeveloper to create the Web Service stub. This stub is a Java class which provides the interface to the Web Service and this is the interface that will be called by Forms

1.

From within a new project in Oracle9i JDeveloper select File> New> General> Web Services>Web Service Stub/Skeleton and then press OK

 

2.

If the Welcome screen appears press Next> to go to screen 1 of 2. On this screen, in the WSDL Document URL enter the name of the URL which points to the WSDL of the Web Service. In this example we will use:

http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl .

Press Next>

[Update on 2008-Mar-03] Note that this wsdl appears to have been removed from this server. Please find a similar one somewhere else.

3.

Screen 2 of 2 shows the facilities available to be called on this Web Service. These should be selected by default, press Finish

 

4.

JDeveloper automatically creates the code required to call the Web Service. Save and Rebuild the project.

 

5.

(Optional Step).When you run a Web Service stub from within JDeveloper, the proxy settings are read from the IDE ( Tools > Preferences > Web Browser/Proxy). Since you will be calling the Web Service stub from Forms, you may have to define the proxy settings in the code. If you are using a proxy then you have to replace the following line the in CurrencyExchangeServiceStub constructor.

Replace

m_httpConnection = new OracleSOAPHTTPConnection();

with

Properties prop = new Properties();
prop.setProperty(OracleSOAPHTTPConnection.PROXY_HOST, "myproxy"); prop.setProperty(OracleSOAPHTTPConnection.PROXY_PORT,"80"); m_httpConnection = new OracleSOAPHTTPConnection(prop);

 

6.

While you have only created one class, that class relies on a number of other Java classes. The next step will be to "package" all the relevant files into a single Jar file.

Select File > New > General > Deployment Profiles > JAR File - Simple Archive and press OK.

A dialog will appear showing the name and location of the deployment descriptor. Accept the defaults and press Save.

 

7.

The JAR Deployment Profile Settings Dialog will now appear. Select Dependency Analyzer and check the check box for Oracle SOAP. Press OK.

 

8.

This will create a deployment node on in the system navigator. Select the node, right mouse click and select Deploy to JAR File. This will save the JAR file out to disk. Note the full directory path and name of this JAR file.

 

   

 

Create a Form

It is assumed that for this part of the exercise, you have a working installation of Oracle9i Forms.

Once you have created the Web Service stub the next step is to create a simple form to call the Web Service. For the sake of making this test case as simple as possible, we will simply add a button which will call the Web Service and return (and message out) the rate of exchange. This can of course be elaborated to fit the needs of your application.

 

1.

Select Start > Settings > Control Panel. Double-click on System, then click the Advanced tab then click the Environment Variables button. From the System Variables, select CLASSPATH and then press Edit. Add the full directory name to the JAR file created in step 7 above. Press the OK buttons to dismiss the dialog.

 

 

2.

The next step is to update the Forms environment file to indicate the location of the Jar file (this file is called default.env in a default installation.)

Prepend the full directory path and Jar filename to the CLASSPATH entry.

E.g.

CLASSPATH=
D:\9.0.4.11.71\jdev\mywork\Webservice\Project1\deploy\archive1.jar;D:\...

 

3.

Start up Oracle9i Forms and create a new Form. Create a block and canvas.

 

4.

Select Program > Import Java Classes and select the Java class created in JDeveloper. Press Import. This will create a PL/SQL package for the CurrencyExchangeServiceStub Java class.

 

5.

Change the Import Classes field to java.lang.Float and press Import. This will create a PL/SQL package for the Float Java class. This is required because the CurrencyExchangeServiceStub returns an object of type Float. This is not native to Forms and so we also need to import the Float object.

 

6.

Change the Import Classes field to java.lang.Exception and press Import. This will create a PL/SQL package for the Exception Java class. While this is not essential, it does make error reporting easier. Now press Close to dismiss the dialog.

 

 

7.

Add a button to the canvas and add a When-Button-Pressed trigged and add the following code

DECLARE
 jo ora_java.jobject;
 rv ora_java.jobject;
 ex ora_java.jobject;
BEGIN
 jo := CurrencyExchangeServiceStub. new;
--
--This will get the exchange rate from US Dollars to UK Sterling.
--
 rv := CurrencyExchangeServiceStub.getRate (jo,' USA',' UK' );
 message (float_.floatValue (rv ));
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;

This will call out to the Java class with two parameters and will return the exchange rate to be displayed as a message.

 

 

8.

Run the form and press the button. This will now display the exchange rate from US to UK currency.

 

   

 

Sample code and more information

The following links point to more sources of information related to this topic.

Oracle9iAS Forms Services
Demo of calling a Web Service from Forms
Learn more about Web Services at the Web Services Center on OTN
Using a WSDL to create a stub
Learn more about the Forms Java Importer