Develop > Controller layer > Integrate with back-end systems and external applications > Outbound services


Sample adapter

To use a transport that is not provided with WebSphere Commerce, such as an SMS adapter, a sample adapter is provided that you can use as a base for developing a JCA resource adapter.

The WebSphere Commerce sample adapter consists of the following elements:

Creating a new adapter class requires you to have a reasonable understanding of how a JCA resource adapter works. For information about how a JCA resource adapter works refer to the document: J2EE Connection Architecture.


Sample adapter Java classes

The sample Java classes are...

Class Implements
com.ibm.commerce.messaging.adapters.jcasample.SampleConnection.class javax.resource.cci.Connection
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionEventListener.class javax.resource.spi.ConnectionEventListener
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionFactory.class javax.resource.cci.ConnectionFactory
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionManager.class javax.resource.spi.ConnectionManager
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionMetaDataImpl.class javax.resource.cci.ConnectionMetaDataImpl
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionRequestInfo.class javax.resource.spi.ConnectionRequestInfo
com.ibm.commerce.messaging.adapters.jcasample.SampleConnectionSpec.class javax.resource.cci.ConnectionSpec * java.io.Serializable
com.ibm.commerce.messaging.adapters.jcasample.SampleInteraction.class javax.resouce.cci.Interaction
com.ibm.commerce.messaging.adapters.jcasample.SampleInteractionSpec.class javax.resouce.cci.InteractionSpec * java.io.Serializable
com.ibm.commerce.messaging.adapters.jcasample.SampleManagedConnection.class javax.resoource.spi.ManagedConnection
com.ibm.commerce.messaging.adapters.jcasample.SampleManagedConnectionFactory.class javax.resource.spi.ManagedConnectionFactory
com.ibm.commerce.messaging.adapters.jcasample.SampleManagedConnectionMetaDataImpl.class javax.resource.spi.ManagedConnectionMetaData

* 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. For an example of the ra.xml file, see Example: ra.xml deployment descriptor file.


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:

  1. The WebSphere Commerce messaging system finds the J2C connection factory of the adapter through the 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.

  2. The SampleConnectionFactory object is constructed and passed to the javax.resource.spi.ConnectionManager implementation class and the javax.resource.spi.ManagedConnectionFactory implementation class.

  3. 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.

  4. 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). ConnectionRequestInfo is usually required to create the ManagedConnection, so ConnectionRequestInfo contains the ConnectionSpec fields. Therefore, the sample adapter SampleConnectionRequestInfo object contains the userName and password fields.

  5. (Used in conjunction with connection pooling) To use connection pooling running under WebSphere Application Server, the ConnectionRequestInfo.equals(java.lang.Object) and hashCode() methods must be implemented. The SampleConnectionRequestInfo.hashCode() returns the hash code of the concatenated strings: userName and password. These methods are used by WebSphere Application Server to determine the possible connections and to pass the reusable connections to ManagedConnectionFactory.matchManagedConnection(java.util.Set, javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo). The matchManagedConnection method searches for a suitable ManagedConnection object from the set of re-usable connections passed from WebSphere Application Server.

  6. 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

    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.

  7. SampleConnection.close() calls SampleManagedConnection.sendEvent(javax.resource.spi.ConnectionEvent.CONNECTION_CLOSED, java.lang.Exception, Object) to fire the CONNECTION_CLOSED event.

  8. The WebSphere Application Server calls SampleManagedConnection.cleanup() and destroy().

    Iif 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.

Related reference

Example: ra.xml deployment descriptor file