Java RMI client application development

The Transaction Server provides several services that are accessible from a Java™ client application by using a unicast remote method invocation (RMI) interface. To access the services, include the txsvrtk.jar and util.jar files from the SDK in the Java class path.

The files for the software development kit (SDK) are provided in the FTM artifacts pod and must be downloaded from the pod. For more information about getting files from the artifacts container for your offering, see Getting the files from the artifacts container for your FTM offering.

The Transaction Server is built on the Java Platform, Standard Edition specification, which should be used when the client application is compiled. To access the RMI services, first build a client API session. The constructors available for building this API session are contained in the Java package com.ibm.icpcs.transactionserver.client.rmiservices. The following list shows the constructors and their parameters:

public ClientApi (String applicationName, String hostUrl) throws ClientApiException
public ClientApi (String applicationName, String hostUrl, String clientInterfaceToken) throws ClientApiException
public ClientApi (String applicationName, String hostUrl, int rmiPortNumber, String clientInterfaceToken) throws ClientApiException
public ClientApi (String applicationName, String itsHostName, int rmiPortNumber) throws ClientApiException

The following table shows the parameters for the constructors.

Table 1. Java RMI parameters
Parameter	Required	Default value	Description
applicationName	Yes		A unique text string that identifies the application. This name helps when you are using the Transaction Server logs to debug failures in the client application.
hostUrl	Yes		The URL of the target Transaction Server in either DNS form (www.example.com, for example) or dotted IP form (127.0.0.1, for example). The value of hostUrl needs to match the value of java.rmi.server.hostname when you start the Transaction Server.
rmiPortNumber	No	1099	The RMI port number configured for the target Transaction Server. If the default value is not used, the port number must match the `rmiPort` setting in the config.properties file of the target Transaction Server.
clientInterfaceToken	No	ClientRmiGateway	The client interface token configured for the target Transaction Server. If the default value is not used, this string must match the `rmiClientInterfaceToken` setting in the config.properties file of the target Transaction Server.

After the client application is compiled, it can be run. Before you run the code, include the txsvrcli.jar and util.jar files in the Java class path.

To communicate to the Transaction Server by using RMI, the following ports must be open.

The port that the rmiregistry uses, which is defined in the rmiPort property.
The port that is specified in the rmiInvocationPort property in the config.properties file.

The client code needs to know the rmiPort and the value for the java.rmi.server.hostname Java parameter only.

To view a complete set of Java RMI client API specifications, refer to the Transaction Server Javadoc information. Open the index.html root document in a browser to find a complete set of links to all published Transaction Server RMI client API services.

The files that you need are provided in the FTM artifacts pod and must be downloaded from the pod. For more information about getting files from the artifacts container for your offering, see Getting the files from the artifacts container for your FTM offering.

Use ItemInterface and RmiClientApiInterface as a starting point for showing how Services Framework can be started directly on the RMI client session. The RmiClientApiSessionInterface shows the session management calls that are used in the startup example in Example code. Call these functions only one time each session.

For more information about security for an external RMI client that connects to Transaction Server inside a cluster, see Connect an RMI client to the /share/artifacts/config/check/transaction-server from outside the cluster.

Example code

The following code is a sample of a basic call sequence for a Transaction Server client application in Java.

private  void  execute()
{
  inRmiClientApi api = null;
  boolean rollback = false;

  try
  {
     //  Initialize  the  RMI  API
     ClientApi clientApi = new ClientApi("MY CLIENT", hostUrl);
     api = clientApi.getRmiApi();
     api.start();

     //  do  your  work  here

     //  process  a  request
     api.writeMessage("Show this on the Transaction Server user interface");

     //  process  any  responses

  } // end try block

  //  process  any  exceptions that are thrown 
  catch (ClientApiException xcp)
  {
     System.err.println(xcp.getMessage());
     xcp.printStackTrace(System.err);
     rollback = true;
  } // end catch API startup failures

  catch (RmiClientApiException xcp)
  {
     System.err.println(xcp.getMessage());
     xcp.printStackTrace(System.err);
     rollback = true;
  } // end catch client API RMI processing failures

  finally
  {
     //  terminate  or  close  the  RMI  session 
     if (clientApi != null)
     {
        //  if  a  failure  occurred,  rollback  any  database  changes 
        if (rollback)
           clientApi.abort();

        //  otherwise,  commit  the  changes
        else 
          clientApi.term();
     }  //  end  if  API  session  established
  }  //  end  finally  block
}  //  end  execute()