WebSphere Commerce provides a sample adapter that you can use as a base for developing a JCA resource adapter that works with WebSphere Commerce. For information about how a JCA resource adapter works refer to the document: J2EE Connection Architecture.
The WebSphere Commerce sample adapter consists of the following elements:
- Classes
- Meta data files
- Deployment descriptor file
Classes
The classes are in the following directory:
- WCServer_enterprise_archive/Enablement-JCASampleConnector/connectorModule
* Note: To avoid problems when connecting to a remote database, implement the required methods and ensure that these implementation classes implement java.io.Serializable.
Meta data file
The sample adapter contains the following meta data files:
- META-INF/MANIFEST.MF
- Lists the JAR files and classes needed by the sample adapter's implementation classes at runtime. This sample resource adapter references the Enablement-BaseComponentsLogic.jar file and the Enablement-IntegrationLogic.jar file.
Deployment descriptor file
The sample adapter contains the following deployment descriptor file:
- META-INF/ra.xml
- The ra.xml file lists the implementation classes for the JCA methods.
How a message is sent using the sample transport adapter
This describes the message flow when a message is sent through the sample adapter under a managed environment such as WebSphere Application server. A message sent through the sample transport adapter follows these steps:
- The WebSphere Commerce messaging system finds the J2C connection factory of the adapter though JNDI name associated with the sample adapter, eis/JCASample. The implementation class of the J2C connection factory method is specified by the value of the connectionfactory-impl-class element in the ra.xml deployment descriptor file.
- The SampleConnectionFactory object is constructed and passed to the javax.resource.spi.ConnectionManager implementation class and the javax.resource.spi.ManagedConnectionFactory implementation class.
- The messaging system calls the SampleConnectionFactory.getConnection(javax.resource.cci.ConnectionSpec) method to get a javax.resource.cci.Connection object by constructing a SampleConnectionRequestInfo object. The SampleConnectionRequestInfo and the SampleManagedConnectionFactory objects are passed to the SampleConnectionManager.allocate(ManagedConnectionFactory,ConnectionRequestInfo) method. This creates the javax.resource.cci.Connection object.
- The SampleConnectionManager.allocate(ManagedConnectionFactory,ConnectionRequestInfo) method calls one of the following methods:
- SampleManagedConnectionFactory.createManagedConnection(javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo), which constructs and returns SampleManagedConnection().
- (Used in conjunction with connection pooling) SampleManagedConnectionFactory.matchManagedConnection(java.util.Set, javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo), which gets a matching connection. The SampleManagedConnectionFactory.matchManagedConnection returns null. It calls createManagedConnection to create a new SampleConnection object.
The SampleConnectionSpec object consists of two fields: userName and password. The SampleInteractionSpec object contains one field: input (type java.lang.String). Usually, ConnectionRequestInfo is required to create the ManagedConnection, so ConnectionRequestInfo is comprised of the ConnectionSpec fields. Therefore, the sample adapter SampleConnectionRequestInfo object consists of the userName and password fields.
- (Used in conjunction with connection pooling) To use connection pooling running under WebSphere Application Server, interfaces of ConnectionRequestInfo.equals(java.lang.Object) and hashCode() methods must be implemented.
The SampleConnectionRequestInfo.hashCode() returns the hashcode of the concatenated strings: userName and password. These methods are used by WebSphere Application Server to determine the possible connections and to pass the re-usable connections to ManagedConnectionFactory.matchManagedConnection(java.util.Set, javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo). The matchManagedConnection method search for a suitable ManagedConnection object from the set of re-usable connections passed from WebSphere Application Server. - The SampleConnection is returned to the messaging system. The interfaces Connection.createInteraction() and javax.resource.cci.Interaction.execute(javax.resource.cci.InteractionSpec, com.ibm.commerce.messaging.outboundservice.WCMSRecord, com.ibm.commerce.messaging.outboundservice.WCMSRecord) and javax.resource.cci.Interaction.close() are called to send the message.
The SampleInteraction.execute(javax.resource.cci.InteractionSpec, javax.resource.cci.Record, javax.resource.cci.Record) writes the following to SystemOut.log:
************************************************** a test message**************************************************
where:
test message is the outbound message content, if the input field of the SampleInteractionSpec is test messages. If the input field value, is not test messages an exception will be thrown.
- SampleConnection.close() calls SampleManagedConnection.sendEvent(javax.resource.spi.ConnectionEvent.CONNECTION_CLOSED, java.lang.Exception, Object) to fire the CONNECTION_CLOSED event.
- WebSphere Application Server calls SampleManagedConnection.cleanup() and destroy(). Note that if connection pooling is used, the destroy() method, which destroys the physical connection to the enterprise resource, is called after the unused timeout of the connection pool settings.