Configuring Server Access for EJB

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

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

Making the Server Access for EJB ITLM agent enabled

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

CC000976J040300.sys

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

Setting environment entries

When your WebSphere Access EJB is deployed within an application server, the EJB container sets the environment for the bean. The environment of an enterprise bean provides the mechanism to customize the business logic of the bean during deployment or assembly. This environment comprises environment entries, each of which specifies of piece of environment information.

The deployment descriptor provides <env-entry> elements to specify each environment entry. By reading the deployment descriptor, the EJB container is able to initialize the enterprise bean's environment. Table 8 shows the information that each <env-entry> element provides.

Table 8. Environment entry information

Subelement of <env-entry> Description
<description>
An optional description of the environment entry
<env-entry-name>
The name of the environment entry
<env-entry-type>
The Java type of the environment entry; this type is what is expected to be returned from the JNDI lookup() method
<env-entry-value>
The value to assign the environment entry

To configure the environment of your Access EJB, you specify environment entries in its deployment descriptor. Table 9 shows the environment entries that Server Access for EJB supports.

Table 9.

Server Access for EJB environment entries
Property name Description


ICServers
A comma-separated list of the names of the ICS instances that this enterprise bean can access.


traceLevel
The trace level that determines whether debugging information is generated for the WebSphere Access EJB. For more information, see Tracing.


logFile
Name of the log file for the WebSphere Access EJB. This name must be the file's absolute path name. For more information, see Logging.


<ICSName>/userName
Account name to use when connecting to the ICSName instance of ICS. The only user name currently supported is admin.


<ICSName>/passWord
Password for the admin user.


<ICSName>/iorLocation
Name of the Interoperable Object Reference (.ior) file for the ICSName instance of ICS. This name must be the file's absolute path name.


<ICSName>/numAccessSessions
Maximum number of simultaneous connections allowed to the ICSName instance of ICS. The default value is one (1).

Note:
Setting the environment entries in Table 9 is the only way to configure a WebSphere Access EJB. You cannot configure it through System Manager.

For each ICS instance that your enterprise bean accesses, you must take the following steps in the deployment descriptor:

  1. List the name of the ICS instance in the ICServers environment entry; if an ICS name already exists in this entry, separate ICS names with a comma (,).

    If this environment entry is missing or if it does not contain ICS instances that are described in step 2, WebSphere Access EJB throws a CreateException exception.

  2. Provide the ICS-specific information for the ICS instance:

    Each of the above entries has the string "ICSName/" prepended, where ICSName is the name of the ICS instance. If any of this information is missing, the bean does not create any connections to that ICS instance.

The environment entries are specified only once in the deployment descriptor. However, all instances of the enterprise bean in the same home share the same environment.

Handling the .ior file

At run time, Server Access for EJB 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 EJB 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 EJB). To obtain the location of the ORB server, an Access EJB 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 EJB can then use this file to locate the ORB server and, in turn, to communicate with its ICS instance.

Therefore, for an Access EJB 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 EJB resides is able to locate the .ior file for its InterChange Server instance.
  3. Synchronize the .ior file between the WebSphere Access EJB and InterChange Server.

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

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 EJB cannot depend on the .ior file to locate the ORB server. Therefore, an Access EJB 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 12 shows the XML code that defines an empty CORBA subsection (one with no configuration parameter defined).

Figure 12. 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 12 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 EJB 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 EJB 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-EJB machine can access the .ior file:

Synchronizing the .ior file

The WebSphere Access EJB obtains the name of the InterChange Server instance with which it communicates from the ICS-specific Interoperable Object Reference (.ior) file. The enterprise bean obtains the name of this .ior file from the iorLocation environment entry. Therefore, to synchronize the Access EJB and InterChange Server, you must set this iorLocation environment entry to contain the absolute path name for the ICS-specific .ior file for the machine on which Server Access for EJB resides.

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

Suppose that the Server Access for EJB deployment directory is:

ProductDir\DevelopmentKits\J2EE\EJB

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

ProductDir\DevelopmentKits\J2EE\EJB\dexterinterchangeServer.ior

Configuring the application server

This section provides a summary of how to configure the WebSphere Application Server 4.0 Advanced Edition, which is the application server that is certified for use with Server Access for EJB. For more information, refer to the Readme.txt file in the subdirectory of the Server Access for EJB samples for the WebSphere Application Server Advanced Edition 4.0:

ProductDir\DevelopmentKits\J2EE\EJB\samples

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

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

Modifying environment entries

To update configuration properties, you change their values in the deployment descriptor for Server Access for EJB, ejb-jar.xml. This deployment descriptor is part of the cwsession_ejb-jar.xml file. It is recommended that you use the administration console of your application server after the enterprise bean 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 environment entries, see Configuring Server Access for EJB.

Deploying the enterprise bean

To deploy an enterprise bean for use with WebSphere Application Server, you must install the external .jar file and deploy an enterprise bean. For more information on these steps, see the documentation for WebSphere Application Server.

Making ORB libraries available

At run time, Server Access for EJB 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 runtime. 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