Java sample program

for specific business needs, such as correlating data with other JavaBeans or XML data sources. The sample Java program can be distributed as a

stand-alone Java application or to a Web server as a downloadable Java applet.

4.6.1 Architecture overview

Java applets, servlets and stand-alone applications can easily access your database and host Integration Objects by using the generated RIO proxy. Figure 58 on page 75 illustrates this scenario. The RIO proxy is actually a JavaBean and therefore the Java client program uses a standard interface based on setter (for input properties) and getter (for output properties) methods to communicate with the Integration Object. The RIO proxy interface is explained in 4.6.3, “RIO proxy interface” on page 76.

As shown in Figure 58 on page 75, the RIO proxy communicates with the XML requester, which is also provided by the Host Publisher server RIO support in the file RIO.jar. The unsecure HTTP or the secure HTTPS protocol can be used with the Web server when communicating with the RIOServlet. Note: In this scenario, the input request carries the property values in XML format in the URL. For details about this format, see “Input properties in XML format in URL” on page 65.

4.6.2 Security issues

If you are planning to secure the connection with the Web server using Secure Sockets Layer (SSL), you must be aware of the following considerations:

1. Use the HTTPS protocol in the URL.

2. The Web server must also be enabled for SSL and certificates must be available.

3. If you are invoking the RIOServlet from a Java applet, the SSL support is provided by the browser.

4. If you are running a Java stand-alone application, the XML requester supports SSL (on the default SSL port 443). In this scenario, you can use the IBM sslight.jar package or the SSL support in Java applications from

http://java.sun.com/products/jsse/.

5. If you want to run the provided Java sample program running as a stand alone application with a secure session using SSL, you will need to edit the CustomApp<IOname>.java program and replace the protocol HTTP with HTTPS. Then you will need to recompile this program. See 4.6.4, “Java sample program” on page 82 for details about this sample program.

4.6.3 RIO proxy interface

Host Publisher provides two components to enable Java client applications to invoke your database and host Integration Objects via the RIOServlet: 1. A client side RIO proxy, a JavaBean.

2. A client side XML requester (RIO.jar)

In this scenario, the execution flow looks like this (see Figure 58 on page 75): 1. The client Java applet, servlet or application interfaces with the Host

Publisher generated RIO proxy for specific Integration Object (IO). The Java client program sees the Integration Object as running locally.

2. The Java program instantiates the RIO proxy, issues the setter methods to pass the input properties, and executes synchronously or asynchronously the RIO proxy.

3. The RIO proxy uses the XML client requester to convey the request to the server (XML servlet - RIOServlet) component via XML over HTTP.

4. The server component RIOServlet runs on the Host Publisher Server, invokes the database or host Integration Object, and returns the extracted data in XML format to the XML client requester.

5. The XML client requester passes the data to the RIO proxy, which returns it synchronously or asynchronously to the client Java application.

4.6.3.1 Semantics for using the RIO Proxy in Java programs

These are the recommended steps for using the automatically generated RIO proxy within your own Java programs:

1. Create a URL object that points to the RIOServlet on the remote Host Publisher server.

2. Create an instance of the RIO proxy by calling upon its constructor and passing in the above URL object.

3. Use the setter methods of the RIO proxy to set the input properties for the request.

4. Use the RIO proxy processRequest() method to execute the request synchronously. Alternatively set up your Java program to execute the RIO request asynchronously (non-blocking) as shown in 4.6.3.3, “RIO proxy asynchronous callback” on page 79.

5. If using Integration Object chaining:

a. For the first Integration Object, use the getSessionID() method to request and store the session ID.

b. For subsequent Integration Object invocations, use the session ID retrieved in the above step to set the session ID for each RIO proxy call.

6. Finally, use the getter methods of the RIO proxy to retrieve the data response from the database or host Integration Object.

4.6.3.2 RIO proxy synchronous call

The most common way to access Integration Objects from Java programs via the RIOServlet and using the RIO proxy is by executing the processRequest method.

The processRequest method blocks the Java application and no other process can take place for the duration of the database or host transaction. This could be fine in some cases but not acceptable in others. If your Java application needs to have control during the RIOServlet call you would need to implement the asynchronous RIO proxy invocation as explained in 4.6.3.3, “RIO proxy asynchronous callback” on page 79.

Sample program - synchronous call

Figure 59 shows a sample Java application using the RIO proxy interface to process RIOServlet request synchronously. The program instantiates the generated RIO proxy, issues the setter methods, invokes the RIO proxy to process the request, waits for a response and issues the getter methods to obtain the response fields.

Notice that the name of the generated RIO proxy is RemoteHobj01, where Remote is the configured default prefix and Hobj01 is the Integration Object name.

4.6.3.3 RIO proxy asynchronous callback

The RIO proxy allows for asynchronous callback communications for Java applications. In this scenario, the Java application is not blocked when a request is sent to the RIOServlet. The main benefit is that the Java client application can now honor any other request or events, for example from the GUI. A similar situation is when a Web browser supports a stop function to terminate an HTTP request. Since a Java application does not use a browser, it has to implement this support if it is required.

The asynchronous (non-blocking) call is used instead of the synchronous processRequest method (see Figure 60). The following are the suggested steps to implement this interface:

1. Code an event listener with name hPubReqComplete. It will receive the response from the RIO proxy when the operation completes.

2. The listener must be enabled.

3. The response event HPubReqCompleteEvent is received by the listener. 4. The getSource method is issued to get the response object.

Sample program - asynchronous callback

In this section we provide a sample Java application program (see Figure 61) that instantiates the RIO proxy JavaBean, issues the setter method for the input property, enables the listener method to process the CICS request and starts the request.

The sample class implements the RIO HPubReqCompleteListener for the asynchronous callback event listener.

After the request is initiated and the operation goes asynchronous the program gets control back to do any local process. In a more sophisticated application, you probably would like to honor GUI requests (keyboard, mouse, etc). In this sample program, it just goes to sleep for 15 seconds waiting for the CICS response.

Figure 61. Sample Java application using RIO proxy asynchronously (1 of 3)

Figure 62 on page 81 shows the event listener for the asynchronous callback. It will get control when the RIO proxy obtains the CICS response and throws the event. The listener copies the event object to the RIO proxy bean object and issues the getter methods to obtain the response fields from the CICS transaction and the results are written to the console.

In this scenario, the Integration Object returns the following output property values initially sent by CICS:

• accountVar. The inquiry account number. • surnameOut. The last name.

• firstname. First name in the CICS database. • addressOut. Address for this person.

• sessionID. The session ID. This is used when you are using Integration Object chaining. See 4.8, “RIO chaining support” on page 92 for details.

Figure 62. Sample Java application using RIO proxy asynchronously (2 of 3) - event listener

The main method gets control when you start the program. It looks at the passed arguments. The first argument should contain the CICS transaction account number and the second argument specifies the Web server IP address (if not present it defaults to 127.0.0.1, the same machine).

The main program instantiates the sample class passing the account number and the Web server IP address.

Figure 63. Sample Java application using RIO proxy asynchronously (3 of 3) - main method and interface

4.6.4 Java sample program

A Java sample program is generated by the Host Publisher Studio when you save the Integration Object with the RIO option. The Java program runs as an applet (requires a Web browser) or as a stand-alone application. It uses the Swing class for the GUI to get inputs and display the results. The program uses the asynchronous callback scheme in the RIO proxy to invoke the execution of the RIO request/response.

The name of the generated sample Java applet/application is

CustomApp<IOname>.java and you will find it in the following subdirectory: d:\Hostpub\Studio\IntegrationObjects\RemoteIO\<IOname>\

where IOname is the Integration Object name.

Figure 64 on page 83 illustrates the Swing GUI when the generated sample program is executed. It takes input values for the input properties and displays the output in the bottom part of the window.

The Submit button is used to send the request and the Session for chaining box is used to set the session ID when Integration Object chaining is used. For details about chaining see 4.8, “RIO chaining support” on page 92.

Figure 64. Java applet and application using RIO proxy

In addition, the following generated files can also be used with this sample program:

• AppLoader<IOname>.html. A sample HTML page to execute the sample program as a Java applet.

• CompileCustomApp<IOname>.bat. A batch file you can use to compile the sample program if needed.

• RunCustomApp<IOname>.bat. A batch file you can use to run the sample program as a Java application.

• CreateRIOBeanJar.bat. A batch file to create a package RIO<IOname>.jar that can be imported as a JavaBean.

Note: The JAR files RIO.jar, HPubCommon.jar, and the nano.zip must also be included when importing this JavaBean.

• CreateRIOJavaDoc.bat. A batch file to create JavaDoc for the generated RIO.

• PkgRIO<IOname>.bat. A batch file to package (zip) the sample Java applet/application and dependent files for transfer to a client or Web server.

• Remote<IOname>.java. The generated RIO proxy for the Integration Object. The compile class file is also generated.