Configuring Server Access for J2EE

This section provides the following information for how to configure Server Access for J2EE:

Each of the steps is described in more detail in the following sections.

Making Server Access for J2EE ITLM Agent enabled

WebSphere InterChange Server Access for J2EE provides enablement for IBM Tivoli License Management (ITLM) inventory functions. In order to make the Server Access for J2EE ITLM agent enabled you must ensure that the inventory file which is installed with ICS is copied to the machine where the CWResourceAdapter.jar file resides. The inventory file is called

CC001351J040300.sys

and is found in the ProductDir/bin directory of the ICS installation.

Setting configuration properties

After the CwManagedConnectionFactory instance exists, invocations of the appropriate get and set methods set the connection configuration properties for the resource adapter. Table 8. lists these configuration properties.


Table 8.

Server Access for J2EE configuration properties
Property name Description Default value
IorFilename
Name of the Interoperable Object Reference File (.ior) for the instance of WebSphere InterChange Server (ICS) with which the Access Resource Adapter connects
For more information, see Synchronizing the .ior file.
crossworlds.ior
MaxConnections
Maximum number of simultaneous connections allowed to the ICS instance. 100
Username
Account name to use when connecting to the ICS instance. admin
UserPassword
Password for the account specified in the Username property.
Note:
Rather than leaving the password as readable text in the deployment descriptor, you can specify it when requesting the connector within the application component.
For more information, see Establishing a connection.
null
ORBClassName Name of the Java class that implements the IBM Java Object Request Broker (ORB) com.ibm.CORBA.iiop.ORB
ORBSingletonClassName A Java class com.ibm.rmi.corba.ORBSingleton

The way to set these configuration properties depends on the type of environment in which Server Access for J2EE runs, as follows:

Handling the .ior file

At run time, Server Access for J2EE does not need to reside on a machine that contains InterChange Server, nor does it need to reside on the same machine as the development environment. However, for a WebSphere Access Resource Adapter to be able to locate the ICS instance it needs at run time, it must be able to locate the Object Request Broker (ORB) server, which keeps track of the locations of different CORBA objects (including InterChange Server instances) and communicates this information with ORB clients (such as a WebSphere Access Resource Adapter). To obtain the location of the ORB server, an Access Resource Adapter can use the Interoperable Object Reference File that its ICS instance generates. When ICS starts or reboots, it generates an Interoperable Object Reference file, which has the .ior extension. In this file, the ICS instance puts the port number on which the ORB Server listens for requests from ORB clients. The Access Resource Adapter can then use this file to locate the ORB server and, in turn, to communicate with its ICS instance.

Therefore, for an Access Resource Adapter to locate its ICS instance, you must take the following steps:

  1. Request that InterChange Server generate a persistent .ior file.
  2. Ensure that the machine on which Server Access for J2EE resides is able to locate the .ior file for its InterChange Server instance.
  3. Synchronize the .ior file between the WebSphere Access Resource Adapter and InterChange Server.

Generating a persistent .ior file

When InterChange Server version 3.1.0 or later is booted up, it generates a new .ior file. However, by default, InterChange Server dynamically assigns a port number for the ORB server. If the port number changes each time the server boots, the WebSphere Access Resource Adapter cannot depend on the .ior file to locate the ORB server. Therefore, an Access Resource Adapter needs ICS to generate a persistent .ior file.

To have InterChange Server generate a persistent ior file, you must edit the ICS configuration file (InterchangeSystem.cfg) in an XML editor and add a subsection for CORBA, if one does not already exist. Figure 8 shows the XML code that defines an empty CORBA subsection (one with no configuration parameter defined).

Figure 8. XML definition of CORBA subsection

<tns:property>
   <tns:name>CORBA</tns:name>
   <tns:isEncrypted>false</tns:isEncrypted>
   <tns:updateMethod>system restart</tns:updateMethod>
   <tns:location>
      <tns:reposController>false</tns:reposController>
      <tns:reposAgent>false</tns:reposAgent>
      <tns:localConfig>true</tns:localConfig>
   </tns:location>
   XML definitions of CORBA properties go here
</tns:property>

The CORBA subsection specifies the static port number with the OAport configuration parameter, which has the following syntax:

OAport=portNumber

For example, if the static port number is to be 15000, assign a value of 15000 to its OAport parameter in the CORBA subsection. The following XML fragment would appear within the <tns:property> tag for the CORBA subsection, in the place indicated in Figure 8 with the string "XML definitions of CORBA properties go here":

   <tns:property>
     <tns:name>OAport</tns:name>
     <tns:value xml:space="preserve">15000</tns:value>
     <tns:isEncrypted>false</tns:isEncrypted>
     <tns:updateMethod>system restart</tns:updateMethod>
     <tns:location>
        <tns:reposController>false</tns:reposController>
        <tns:reposAgent>false</tns:reposAgent>
        <tns:localConfig>true</tns:localConfig>
     </tns:location>
   </tns:property>
Important:
The ICS configuration file is an XML file. To add the CORBA subsection and its configuration parameter, you must use an XML editor or must correctly format the appropriate XML tags.

For more information on the CORBA subsection in the configuration file, see the IBM WebSphere System Installation Guide for UNIX or for Windows.

Locating the .ior file

For a WebSphere Access Resource Adapter to locate the ORB server at run time, it must be able to locate the .ior file for its InterChange Server instance. Locating this file is not a problem if Server Access for J2EE and InterChange Server are on the same machine. However, if these two components are not on the same machine, you must take one of the following actions to ensure that the Access-Resource-Adapter machine can access the .ior file:

Synchronizing the .ior file

The WebSphere Access Resource Adapter obtains the name of the InterChange Server instance with which it communicates from the ICS-specific Interoperable Object Reference (.ior) file. The resource adapter obtains the name of this .ior file from the IorFilename configuration property. Therefore, to synchronize the Access Resource Adapter and InterChange Server, you must set this IorFilename configuration property to contain the absolute path name for the ICS-specific .ior file for the machine on which Server Access for J2EE resides.

For example, to have an Access Resource Adapter connect to an InterChange Server instance named dexter, set the iorFilename environment entry to the absolute path name for this dexterinterchangeserver.ior file on the machine that contains Server Access for J2EE.

Suppose that the Server Access for J2EE deployment directory is:

ProductDir\DevelopmentKits\J2EE\ResourceAdapter

The iorFilename environment entry would contain the following string to indicate the location for the .ior file:

ProductDir\DevelopmentKits\J2EE\ResourceAdapter\dexterinterchangeServer.ior

In a managed environment, an application server can sometimes fail to recognize the absolute path name in IorFilename. If this occurs, move the .ior file to a folder within the application server's directory structure.

Configuring the application server

This section provides a summary of how to configure WebSphere Application Server (the application server that is certified for use with Server Access for J2EE) in a managed environment. For more information, refer to the following sources of information:

The configuration of WebSphere Application Server for use with Server Access for J2EE involves the following steps:

Each of these steps is described in more detail in the following sections.

Modifying configuration properties

To update configuration properties, you change their values in the deployment descriptor for the WebSphere Access Resource Adapter, ra.xml. This deployment descriptor is part of the CWResourceAdapterWL.rar file. It is recommended that you use the administration console of your application server once the Access Resource Adapter is deployed. You should modify the actual deployment-descriptor file only if you are very familiar with XML syntax.

Note:
For more information on connection configuration properties, see Configuring Server Access for J2EE.

Deploying the resource adapter

To deploy the WebSphere Access Resource Adapter for use with WebSphere Application Server, perform the following steps:

  1. Download and install the Connector Architecture (technology preview) from the IBM web site, www.ibm.com.
  2. Before you actually deploy the Access Resource Adapter, it is recommended that you shut down the application server on which you intend to deploy the resource adapter.
  3. Open the WebSphere administrative console.
  4. From the drop-down menus, select:
    Console--> Wizards--> Create J2C Connection Factory
    
  5. In the Wizard dialog box that opens, give a name for the connector factory (for example, CWConnectionFactory) and click Next.
  6. Choose:
    Create a new J2C resource adapter
    

    and click Next.

  7. Give a name to the Access Resource Adapter (for example, CWResourceAdapter), browse for and install the CWResourceAdapter.rar file. Click Next.
  8. In the final dialog box, review the information presented and click Finish.

    The WebSphere Application Server now deploys the resource adapter (This might take a few minutes.). If this operation completes without errors, the resource adapter has been deployed successfully.

  9. In the left-hand column of the WebSphere administrative console, expand the branch:
    Resources--> J2C Resources--> CWResourceAdapter--> J2C Connection Factory
    

    Verify that the JNDI binding path for the connection factory is:

    eis/CWConnectionFactory
    
  10. After you have completed the installations, restart the WebSphere Application Server so that all changes properly take effect

Making ORB libraries available

At run time, a WebSphere Access Resource Adapter requires access to the library for the IBM Java ORB. You must ensure that the Java Virtual Machine (JVM) of the application server has access to the ORB .jar file at run time. For WebSphere Application Server, the IBM Java ORB is contained in the application-server run time. Therefore, you do not need to take special steps to provide the application server with the appropriate ORB .jar file. However, if you are using any other application server and the ORB classes are not included in the default libraries of its JVM, you might need to copy the ORB libraries or reference them in your system class path.

Copyright IBM Corp. 1997, 2004