Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 Using the OIG JCA Adapter : Working with the Deployment Descriptor

Working with the Deployment Descriptor
Changing Deployment Descriptor Settings
You only need to change the <config-property> and the <transaction-support> settings, under normal circumstances.
The following is a brief description of each of these settings:
Config-Property Settings
 
The size of the datain buffer to allocate for adapter sessions. This can be from 500 to 32 KB bytes.
The size of the dataout buffer to allocate for adapter sessions. This can be from 500 to 32 KB bytes.
Set to TRUE or FALSE. Indicates whether debugging messages should be produced by the server. If the application server specifies an adapter log file, the debug messages are sent there; otherwise they go to the server’s System.out stream. Because this writer is serialized, running in debug mode can impact server performance, particularly in an SMP environment.
The host name of the Object Integration Gateway where the adapter connects.
The library (if any) to use for the session.
The password that the adapter uses to log in.
The port number of the osMon task on the HOST machine.
The search path for the adapter sessions.
If the DEBUG parameter is set to TRUE and a filename is specified here, the contents of the datain and dataout buffers are written to this log file. There is a significant performance penalty for doing this.
The user ID that the adapter uses to log in.
org.apache.xerces.parsers.SAXParser
The parser to use for operations involving XML. The Xerces SAX parser is the default.
Transaction-Support Settings
 
Use to deploy the adapter to support the JCA 1.0 LocalTransaction contracts. The Gateway starts and stops LocalTransactions as per the deployment settings for the EJB's that access the JCA adapter.
Use to deploy the adapter without supporting transaction contracts. You are responsible for starting and stopping all transactions.
Many of these settings are particular to the application and the Gateway where the adapter is deployed. Some Gateways have facilities for modifying such settings as needed via an admin console, and others do not.
To modify these settings prior to deployment, you must extract the ra.xml file from the archive, modify it, and return it to the archive.
The following explains how you can modify these settings prior to deployment:
1.
2.
jar xf oigadapter.rar META-INF/ra.xml.
3.
4.
jar uf oigadapter.rar META-INF/ra.xml.
Some of these settings are not appropriate for use by all application sessions. You can override any or all of the parameter settings when you instantiate a connection in your application code. Applications have connections to multiple Object Integration Gateways, or to the same Gateway in a variety of modes.
When an instantiated connection has unique properties, it creates a new session. Creating multiple connections with unique properties that create new sessions defeats the session pooling mechanism and quickly exhausts the available session resources on the Gateway.
Installation and Deployment
The procedure for installing the adapter varies from server to server. Most servers can deploy the adapter as is, and some require a server-specific deployment descriptor to be included in the META-INF directory. Use the Gateway-specific deployment descriptors to specify values that are outside the scope of the JCA specification, such as pool size, idle timeout, and so on. The specification explicitly states a number of areas that server vendors implement in any way they choose, so long as the specification contracts are fulfilled. Refer to your application server documentation for information about these settings and for information about how to deploy JCA adapters.
As of J2EE 1.3, the definition of an application is expanded to include JCA adapters. Several examples are provided with Object Integration Gateway that demonstrate this. To make a JCA adapter part of an application, simply add a new <module> section to the application.xml file, and include the oigadapter.rar file in the application’s .ear file.
This is an example of what such an application.xml would look like:
<application>
 <display-name>
  Object Integration Gateway 5.0 Sample Application
 </display-name>
 <module>
  <web>
<web-uri>oigdemo.war</web-uri>
<context-root>/oigdemo</context-root>
  </web>
 </module>
 <module>
  <ejb>oigdemo-ejb.jar</ejb>
 </module>
 <module>
  <connector>oigadapter.rar</connector>
 </module>
</application>
This is the easiest way to install an adapter and usually circumvents server-specific installation procedures.
Using the Adapter
One of the main advantages of using a JCA adapter in your application is that it provides a standard programming interface. Developers have a very short learning curve before they are able to use the adapter. In the case of the Object Integration Gateway adapter, the interface employed is the CCI interface described in the J2EE documentation for the javax.resource.cci package.
The following code sample shows one method of an EJB instantiating a JCA connection in its setSessionContext method:
public void setSessionContext(SessionContext sc) throws EJBException
{
this.sc = sc;
String adapterJndiName = null;
try
{
ic = new InitialContext();
// ADAPTER is a deployment parameter for this ejb
adapterJndiName = (String)ic.lookup("java:comp/env/ADAPTER");
// lookup the connection factory for this adapter
cf = (CciConnectionFactory)ic.lookup(adapterJndiName);
   }
catch(NamingException ex)
   {
debugPrint(ex.getMessage());
ex.printStackTrace();
throw new EJBException(ex.getMessage());
   }
}
The EJB now has a reference to the connection factory that it can to create a connection, like this:
private Connection getCCIConnection() throws ResourceException
{
ConnectionSpec spec = new CciConnectionSpec(connectionParms);
return cf.getConnection(spec);
}
The connection object represents a session that a method uses to perform some processing:
private void runInteraction(int interactionType,
String interactionName)
throws ResourceException
{
try
{
con = this.getCCIConnection();
Interaction ix = con.createInteraction();
iSpec.setFunctionName(interactionName);
iSpec.setFunctionType(interactionType);
((CciInteraction)ix).execute(iSpec);
closeCciConnection();
   }
catch(ResourceException ex)
   {
printException(ex);
if (con != null)
closeCciConnection();
iSpec.reset();
throw ex;
   }
}
In this code sample, iSpec is a reference to the InteractionSpec object, which would normally be allocated in the EJB's create or init method, as follows:
iSpec = new CciInteractionSpec();
With CCI, all the EIS-specific information is contained in the InteractionSpec object. This enables a developer who is already familiar with CCI to use any JCA adapter simply by learning how to use the InteractionSpec object.
See Also
The Javadoc file, which is installed as a downloadable zip file with your OIG installation, for information on OIG JCA Adapter APIs.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved