Developing a Service Adapter

Service adapters receive an XML request document from a client and invoke the associated function in the underlying EIS. They are consumers of messages and may or may not provide a response. Service adapters perform the following four functions:

This section contains information on the following subjects:

J2EE-Compliant Adapters Not Specific to WebLogic Integration

Service Adapters in the Run-Time Environment

Figure 6-1 An Asynchronous Service Adapter in the Run-Time Environment

The Flow of Events

Figure 6-3 Service Adapter Flow of Events

Step 1: Development Considerations

Step 2: Configuring the Development Environment

This step describes the processes you must complete to prepare your computer for adapter development.

Step 2a: Set Up the File Structure

Modifying the Directory Structure

When you clone a development tree by using GenerateAdapterTemplate, the file paths and files under adapters/sample are automatically cloned and updated to reflect the new development environment. The changes are reflected in the file WLI_HOME/adapters/ADAPTER/docs/api/index.html (where ADAPTER is the name of the new development directory). This file also contains code that you can copy and paste into the config.xml file for the new adapter that will set up WebLogic Integration to host the adapter.

Step 2b: Assign the Adapter Logical Name

Next, you need to assign the adapter's logical name. By convention, this name is comprised of the vendor name, the type of EIS connected to the adapter, and the version number of the EIS and is expressed as vendor_EIS-type_EIS version. For example:

BEA_WLS_SAMPLE_ADK

Step 2c: Setting Up the Build Process

The Manifest File

Among the files created by GenerateAdapterTemplate is MANIFEST.MF, the manifest file. This file contains classloading instructions for each component that uses the file. A manifest file is created for each /META-INF directory except ear/META-INF.

Listing 6-1 Manifest File Example

Manifest-Version: 1.0

Created-By: BEA Systems, Inc.

Class-Path: BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar logtoolkit.jar xmltoolkit.jar wlai-common.jar wlai-ejb-client.jar xcci.jar

Note: When the filename MANIFEST.MF appears in a .war file, it must appear in uppercase letters. If it does not, Unix will not recognize it and an error will occur.

build.xml Components

If you open build.xml and review its components, you will better understand how this file works. This section describes the prominent elements of build.xml.

Note: The following examples are taken from the sample adapter, not a cloned version thereof.

Step 2d: Create the Message Bundle

Any message destined for the end-user should be placed in a message bundle. The message bundle is simply a .properties text file that contains key=value pairs that allow you to internationalize messages. When a locale and national language are specified at run time, the contents of the message is interpreted, based upon the key=value pair, and the message is presented to the user in the correct language for his or her locale.

For instructions on creating a message bundle, please refer to the JavaSoft tutorial on internationalization at:

Step 3: Implementing the SPI

The Service Provider Interface (SPI) contains the objects that provide and manage connectivity to the EIS, establish transaction demarcation, and provide a framework for service invocation. All J2EE-compliant adapters must provide an implementation for these interfaces in the javax.resource.spi package.

How to Use this Section

Following the three required interfaces, the additional interfaces are described in detail, including information regarding why you might use them and how they benefit an adapter.

Basic SPI Implementation

To implement the SPI for your adapter, you need to extend at least these three interfaces:

Ideally, you will implement these interfaces in the order specified above.

In addition to these three interfaces, you can implement any of the other interfaces described in this step, as your adapter needs dictate.

ManagedConnectionFactory

javax.resource.spi.ManagedConnectionFactory

ManagedConnectionFactory instance is a factory of both ManagedConnection and EIS-specific connection factory instances. This interface supports connection pooling by providing methods for matching and creating a ManagedConnection instance.

Transaction Demarcation

A critical component of the ManagedConnectionFactory is transaction demarcation. You will need to determine which statements in your program are included in a single transaction. J2EE defines a transaction management contract between an application server and an adapter (and its underlying resource manager). The transaction management contract has two parts, depending of the type of transaction:

XA-compliant Transaction

A javax.transaction.xa.XAResource-based contract occurs between a transaction manager and a resource manager in a distributed transaction processing (DTP) environment. A JDBC driver or a JMS provider implements this interface to support association between a global transaction and a database or message service connection.

The XAResource interface can be supported by any transactional resource that is intended for use by application programs in an environment where transactions are controlled by an external transaction manager; for example a database management system where an application accesses data through multiple database connections. Each database connection is enlisted with the transaction manager as a transactional resource. The transaction manager obtains an XAResource for each connection participating in a global transaction. The transaction manager uses the start() method to associate the global transaction with the resource; it uses the end() method to disassociate the transaction from the resource. The resource manager associates the global transaction to all work performed on its data between the start() and end() method invocation.

At transaction commit time, the resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two-phase commit protocol.

Local Transaction

A local transaction management contract occurs when an adapter implements the javax.resource.spi.LocalTransaction interface to provide support for local transactions that are performed on the underlying resource manager. These contracts enable an application server to provide the infrastructure and run-time environment for transaction management. Application components rely on this transaction infrastructure to support their component-level transaction model.

For more information on transaction demarcation support, please refer to:

ADK Implementations

The ADK provides an abstract foundation for an adapter, the AbstractManagedConnectionFactory. This foundation provides the following feature:

There are several key methods that you must supply implementations for. The following paragraphs describe these methods.

createConnectionFactory()

If the adapter supports a CCI interface, it is recommended that you return an instance of com.bea.adapter.cci.ConnectionFactoryImpl or an extension of this class. The key to implementing this method correctly is to propagate the ConnectionManager, LogContext, and ResourceAdapterMetaData into the client API.

Listing 6-21 createConnectionFactory() Example

protected Object
    createConnectionFactory(ConnectionManager connectionManager,
                            String strAdapterName,
                            String strAdapterDescription,
                            String strAdapterVersion,
                            String strVendorName)
    throws ResourceException

createManagedConnection()

Listing 6-22 createManagedConnection() Example

public ManagedConnection
createManagedConnection(Subject subject, ConnectionRequestInfo
info)
throws ResourceException

checkState()

checkState() gets called by the AbstractManagedConnectionFactory before it attempts to perform any of its factory responsibilities. Use this method to verify that all members that need to be initialized before the ManagedConnectionFactory can perform its SPI responsibilities have been initialized correctly. Implement this method as shown here:

protected boolean checkState()

equals()

equals() tests the object argument for equality. It is important to implement this method correctly as it is used by the ConnectionManager for managing the connection pools. This method should include all important members in its equality comparison. Implement this method as shown here:

public boolean equals(Object obj)

hashCode()

hashCode() provides a hash code for the factory. It is also used by the ConnectionManager for managing the connection pools. Consequently, this method should generate a hashCode based upon properties that determine the uniqueness of the object. Implement this method as shown here:

public int hashCode()

matchManagedConnections()

Lastly, the ManagedConnectionFactory must supply an implementation of the matchManagedConnections() method. The AbstractManagedConnectionFactory provides an implementation of the matchManagedConnections() method that relies upon the compareCredentials() method on AbstractManagedConnection.

In order to provide logic that will match managed connections, you will need to override AbstractManagedConnection's compareCredentials() method. This method is invoked when the ManagedConnectionFactory attempts to match a connection with a connection request for the ConnectionManager.

Listing 6-23 compareCredentials() Implementation

public boolean compareCredentials(Subject subject,
                           ConnectionRequestInfo info)
            throws ResourceException
     {
       ILogger logger = getLogger();

Listing 6-24 Extracting a PasswordCredential

PasswordCredential pc = getFactory().
getPasswordCredential(subject, info);
     if (pc == null)
     {
       logger.debug(this.toString() + ": compareCredentials

Listing 6-25 Pinging a Connection

return ping();
}
        boolean bUserNameMatch = true;
        String strPcUserName = pc.getUserName();
           if (m_strUserName != null)
{

logger.debug(this.toString() + ": compareCredentials >>> comparing
   my username ["+m_strUserName+"] with client username
   ["+strPcUserName+"]");

Next, you need to see if the user supplied in either the Subject or the ConnectionRequestInfo is the same as our user. We do not support re-authentication in this adapter, so if they do not match, this instance cannot satisfy the request. The following line of code does that:

bUserNameMatch = m_strUserName.equals(strPcUserName);

If usernames match, ping the connection to determine if this is still a good connection. Otherwise, there is no match and no reason to ping. The following line of code does that:

return bUserNameMatch ? ping() : false;

Explanation of the Implementation

Under a managed scenario, the application server invokes the matchManagedConnections() method on the ManagedConnectionFactory for an adapter. The specification does not indicate how the application server determines which ManagedConnectionFactory to use to satisfy a connection request. The ADKs AbstractManagedConnectionFactory implements matchManagedConnections(). The first step in this implementation is to compare "this" (that is, the ManagedConnectionFactory instance on which the ConnectionManager invoked matchManagedConnections) to the ManagedConnectionFactory on each ManagedConnection in the set supplied by the application server. For each ManagedConnection in the set that has the same ManagedConnectionFactory, the implementation invokes the compareCredentials() method. This method allows each ManagedConnection object to determine if it can satisfy the request.

Listing 6-26 matchManagedConnections() Method Implementation

public ManagedConnection
matchManagedConnections(Set connectionSet,
                            Subject subject,
                            ConnectionRequestInfo info)
        throws ResourceException

This class uses the following approach to matching a connection:

AbstractManagedConnectionFactory Properties Required at Deployment

To use the base implementation of AbstractManagedConnectionFactory, you need to provide the following properties at deployment time:

Other Key ManagedConnectionFactory Features in the ADK

In the ADK sample adapter, the class sample.spi.ManagedConnectionFactoryImpl is provided. This class extends AbstractManagedConnectionFactory. Use this class as an example of how to extend the ADK's base class.

For the complete sample adapter ManagedConnectionFactory implementation code listing, see:

WLI_HOME/adapters/sample/src/sample/spi/
ManagedConnectionFactoryImpl.java

ManagedConnection

javax.resource.spi.ManagedConnection

The ManagedConnection object is responsible for encapsulating all expensive resources needed to establish connectivity to the EIS. A ManagedConnection instance represents a physical connection to the underlying EIS. ManagedConnection objects are pooled by the application server in a managed environment.

ADK Implementation

The ADK provides an abstract implementation of ManagedConnection. The base class provides logic for managing connection event listeners and multiple application-level connection handles per ManagedConnection instance.

The ADK provides AbstractManagedConnection, an abstract implementation for the javax.resource.spi.ManagedConnection interface that:

The sample adapter that comes with the ADK includes ManagedConnectionImpl, which extends AbstractManagedConnection. For the complete sample adapter ManagedConnection implementation code listing, see:

WLI_HOME/adapters/sample/src/sample/spi/
ManagedConnectionFactoryImpl.java

ManagedConnectionMetaData

javax.resource.spi.ManagedConnectionMetaData

The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with a ManagedConnection instance. An application server uses this information to get run-time information about a connected EIS instance.

ADK Implementation

The ADK provides AbstractManagedConnectionMetaData, an abstract implementation of the javax.resource.spi.ManagedConnectionMetaData and javax.resource.cci.ConnectionMetaData interfaces that:

The sample adapter that comes with the ADK includes ConnectionMetaDataImpl, which extends AbstractManagedConnectionMetaData. For the complete code listing, see:

WLI_HOME/adapters/sample/src/sample/spi/
ConnectionMetaDataImpl.java 

ConnectionEventListener

javax.resource.spi.ConnectionEventListener

The ConnectionEventListener interface provides an event callback mechanism that enables an application server to receive notifications from a ManagedConnection instance.

ADK Implementation

The ADK provides two concrete implementations of ConnectionEventListener:

In most cases, the implementations provided by the ADK are sufficient; you should not need to provide your own implementation of this interface.

ConnectionManager

javax.resource.spi.ConnectionManager

The ConnectionManager interface provides a hook for the adapter to pass a connection request to the application server.

ADK Implementation

The ADK provides a concrete implementation of this interface, com.bea.adapter.spi.NonManagedConnectionManager. This implementation provides a basic connection manager for adapters running in a non-managed environment. In a managed environment, this interface is provided by the application server. In most cases, you can use the implementation provided by the ADK.

NonManagedConnectionManager is a concrete implementation of the javax.resource.spi.ConnectionManager interface. It serves as the ConnectionManager in the non-managed scenario for an adapter; it does not provide any connection pooling or any other quality of service.

ConnectionRequestInfo

javax.resource.spi.ConnectionRequestInfo

The ConnectionRequestInfo interface enables an adapter to pass its own request specific data structure across the connection request flow. An adapter extends the empty interface to support its own data structures for a connection request.

ADK Implementation

The ADK provides a concrete implementation of this interface called ConnectionRequestInfoMap. This is a concrete implementation of the javax.resource.spi.ConnectionRequestInfo interface and provides a java.util.Map interface to such connection request information as username and password.

LocalTransaction

javax.resource.spi.LocalTransaction

The LocalTransaction interface provides support for transactions that are managed internal to an EIS resource manager, and do not require an external transaction manager.

ADK Implementation

The ADK provides an abstract implementation of this interface called AbstractLocalTransaction. This implementation allows you to focus on implementing the EIS-specific aspects of a LocalTransaction. This implementation:

Step 4: Implementing the CCI

The client interface allows a J2EE-compliant application to connect to and access back-end systems. The client interface manages the flow of data between the client application and the back-end system and does not have any visibility into what either the container or the application server are doing with the adapter. The client interface specifies the format of the request and response records for a given interaction with the EIS.

First, you must determine if your adapter must support the J2EE-compliant Common Client Interface (CCI). Although not a requirement in the current J2EE specification, it is likely to be a requirement in a later version. Consequently, the ADK focuses on helping you implement a CCI interface for your adapter.

How to Use this Section

Following the two required interfaces, the additional interfaces are described in detail, including information regarding why you might use them and what benefit they provide to an adapter.

Basic CCI Implementation

To implement the CCI for your adapter, you need to extend at least these two interfaces:

Ideally, you will implement these interfaces in the order specified above.

In addition to these interfaces, you can implement any of the other interfaces described in this step, as your adapter needs dictate. These interfaces are:

Connection

javax.resource.cci.Connection

A Connection represents an application-level handle that is used by a client to access the underlying physical connection. The actual physical connection associated with a Connection instance is represented by a ManagedConnection instance.

A client gets a Connection instance by using the getConnection() method on a ConnectionFactory instance. A Connection can be associated with zero or more Interaction instances.

ADK Implementation

The ADK provides an abstract implementation of this interface called AbstractConnection. This interface provides the following functionality:

You will need to extend this class by providing an implementation for:

public Interaction createInteraction()

throws ResourceException

This method creates an interaction associated with this connection. An interaction enables an application to execute EIS functions. This method:

Interaction

javax.resource.cci.Interaction

The javax.resource.cci.Interaction enables a component to execute EIS functions. An Interaction instance supports the following ways of interacting with an EIS instance:

An Interaction instance is created from a connection and is required to maintain its association with the Connection instance. The close() method releases all resources maintained by the adapter for the interaction. The close of an Interaction instance should not close the associated Connection instance.

ADK Implementation

The ADK provides an implementation of this interface called AbstractInteraction. This interface:

You must supply a concrete extension to AbstractInteraction that implements execute(). Use at least one of the following versions of execute():

execute() Version 1

This method:

The parameters for execute() version 1 are:

execute() Version 2

This method:

If an exception occurs, this method will notify its Connection, which will take the appropriate action, including closing itself.

Listing 6-28 execute() Version 2 Code Example

public Record execute(InteractionSpec ispec,
                      Record input)
               throws ResourceException

The parameters for execute() version 2 are:

Using XCCI to Implement the CCI

XCCI (XML-CCI) It is a dialect of CCI that uses XML-based record formats to represent data. It provides the tools and framework for supporting this record format. There are two primary components of XCCI: Services and DocumentRecords.

A service represents functionality available in an EIS and is comprised of four components:

DocumentRecord

com.bea.connector.DocumentRecord

IDocument

com.bea.document.IDocument

Listing 6-29 XML Example

<Person name="Bob">
    <Home squareFeet="2000"/>
    <Family>
       <Child name="Jimmy">
          <Stats sex="male" hair="brown" eyes="blue"/>
       </Child>
       <Child name="Susie">
          <Stats sex="female" hair="blonde" eyes="brown"/>
        </Child>
    </Family>
</Person>

Listing 6-30 IDocument Data Retrieval Code Sample

System.out.println("Jimmy's hair color: " +
   person.getStringFrom("//Person[@name=\"Bob\"]/Family/Child
   [@name=\"Jimmy\"]/Stats/@hair");

Listing 6-31 DOM Data Retrieval Code Sample

String strJimmysHairColor = null;
org.w3c.dom.Element root = doc.getDocumentElement();
if (root.getTagName().equals("Person") &&
    root.getAttribute("name").equals("Bob") {
     org.w3c.dom.NodeList list = root.
        getElementsByTagName("Family");
   if (list.getLength() > 0) {
     org.w3c.dom.Element family = (org.w3c.dom.
        Element)list.item(0);

    org.w3c.dom.NodeList childList = family.getElementsByTagName("Child");
    for (int i=0; i < childList.getLength(); i++) {
    org.w3c.dom.Element child = childList.item(i);
       if (child.getAttribute("name").equals("Jimmy")) {
    org.w3c.dom.NodeList statsList =
       child.getElementsByTagName("Stats");
       if (statsList.getLength() > 0) {
    org.w3c.dom.Element stats = statsList.item(0);
           strJimmysHairColor = stats.getAttribute("hair");

        }
      }
    }
  }
}

As you can see, by using IDocument, you can simplify your code.

ADK-Supplied XCCI Classes

The ADK provides several classes that will help you implement XCCI for your adapters. This section describes those classes.

AbstractDocumentRecordInteraction

com.bea.adapter.cci.AbstractDocumentRecordInteraction

This class extends the ADK's abstract base Interaction, com.bea.adapter.cci.AbstractInteraction. The purpose of this class is to provide convenience methods for manipulating DocumentRecords and to reduce the amount of error handling the you need to implement. Specifically, this class declares:

protected abstract boolean execute(InteractionSpec ixSpec, DocumentRecord inputDoc, DocumentRecord outputDoc) throws ResourceException

and

protected abstract DocumentRecord execute(InteractionSpec ixSpec, DocumentRecord inputDoc) throws ResourceException

These methods will not be invoked on the concrete implementation until the parameters have been verified that they are DocumentRecord objects.

DocumentDefinitionRecord

com.bea.adapter.cci.DocumentDefinitionRecord

This class allows the adapter to return an IDocumentDefinition from its DocumentRecordInteraction implementation. This class is useful for satisfying design-time requests to create the request and/or response document definitions for a service.

DocumentInteractionSpecImpl

com.bea.adapter.cci.DocumentInteractionSpecImpl

This class allows you to save the request document definition and response document definition for a service into the InteractionSpec provided to the execute method at run time. This is useful when the Interaction for an adapter needs access to the XML schemas for a service at run time.

XCCI Design Pattern

A common design pattern that emerges when using the XCCI approach is to support the definition of services in the Interaction implementation. In other words, the javax.resource.cci.Interaction implementation for an adapter allows a client program to retrieve metadata from the underlying EIS in order to define a WebLogic Integration service. Specifically, this means that the interaction must be able to generate the request and response XML schemas and additional metadata for a service. Additionally, the Interaction could also allow a client program to browse a catalog of functions provided by the EIS. This approach facilitates a thin client architecture for your adapter.

The ADK provides the com.bea.adapter.cci.DesignTimeInteraction- SpecImpl class to help you implement this design pattern. The sample.cci.InteractionImpl class demonstrates how to implement this design pattern using the DesignTimeInteractionSpecImpl class.

Using Non-XML J2EE-Compliant Adapters

The ADK provides a plug-in mechanism for using non-XML adapters with WebLogic Integration. Not all pre-built adapters use XML as their javax.resource.cci.Record data type; for example:

To facilitate implementation of these types of adapters, the ADK provides the com.bea.connector.IRecordTranslator interface. At run time, the application view engine uses an adapter's IRecordTranslator implementation to translate request and response records before executing the adapter's service.

Since the application integration engine only supports javax.resource.cci.Record of type com.bea.connector.DocumentRecord, you must translate this proprietary format to a document record for request and response records. You do not need to rewrite the adapter's CCI interaction layer. By inserting a class into the WebLogic Integration engine classpath that implements IRecordTranslator, the application view engine will execute the translate methods in your translator class on each record for request and response.

The requirements and restrictions for implementing this translator class are that there is a one to one correlation between adapter and the translator. The plug-in architecture loads the translator class by name, using the full class name of the adapter's InteractionSpec plus the phrase "RecordTranslator"; for example, if the adapter's InteractionSpec class name was com.bea.adapter.dbms.cci. InteractionSpecImpl, then the engine would load the class com.bea.adapter. dbms.cci.InteractionSpecImplRecordTranslator if it was available.

See the Javadoc for com.bea.connector.IRecordTranslator at WLI_HOME/docs/apidocs/com/bea/connector/IRecordTranslator.html for a description of the methods that must be implemented.

ConnectionFactory

javax.resource.cci.ConnectionFactory

ConnectionFactory provides an interface for getting connection to an EIS instance. An implementation of the ConnectionFactory interface is provided by an adapter.

The application code looks up a ConnectionFactory instance from JNDI namespace and uses it to get EIS connections.

An implementation class for ConnectionFactory is required to implement java.io.Serializable and javax.resource.Referenceableinterfaces to support JNDI registration.

ADK Implementation

The ADK provides ConnectionFactoryImpl, a concrete implementation of the javax.resource.cci.ConnectionFactory interface that provides the following functionality:

Typically, you will not need to extend this class and can use it outright.

ConnectionMetaData

javax.resource.cci.ConnectionMetaData

ConnectionMetaData provides information about an EIS instance connected through a Connection instance. A component calls the method Connection.getMetaData to get a ConnectionMetaData instance.

ADK Implementation

By default, the ADK provides an implementation of this class via the com.bea.adapter.spi.AbstractConnectionMetaData class. You will need to extend this abstract class and implement its four abstract methods for your adapter.

ConnectionSpec

javax.resource.cci.ConnectionSpec

ConnectionSpec is used by an application component to pass connection request-specific properties to the ConnectionFactory.getConnection() method.

It is recommended that you implement the ConnectionSpec interface as a JavaBean so that it can support tools. The properties on the ConnectionSpec implementation class must be defined through the getter and setter methods pattern.

The CCI specification defines a set of standard properties for an ConnectionSpec. The properties are defined either on a derived interface or an implementation class of an empty ConnectionSpec interface. In addition, an adapter may define additional properties specific to its underlying EIS.

ADK Implementation

Since the ConnectionSpec implementation must be a JavaBean, the ADK does not supply an implementation for this class.

InteractionSpec

javax.resource.cci.InteractionSpec

An InteractionSpec holds properties for driving an interaction with an EIS instance. It is used by an interaction to execute the specified function on an underlying EIS.

The CCI specification defines a set of standard properties for an InteractionSpec. An InteractionSpec implementation is not required to support a standard property if that property does not apply to its underlying EIS.

The InteractionSpec implementation class must provide getter and setter methods for each of its supported properties. The getter and setter methods convention should be based on the JavaBeans design pattern.

The InteractionSpec interface must be implemented as a JavaBean in order to support tools. An implementation class for InteractionSpec interface is required to implement the java.io.Serializable interface.

The InteractionSpec contains information that is not in Record but helps determine what EIS function to invoke.

The following standard properties are used to give hints to an interaction instance about the ResultSet requirements:

A CCI implementation can provide additional properties beyond that described in the InteractionSpec interface.

Note: The format and type of the additional properties is specific to an EIS and is outside the scope of the CCI specification.

ADK Implementation

LocalTransaction

javax.resource.cci.LocalTransaction

The LocalTransaction interface is used for application-level local transaction demarcation. It defines a transaction demarcation interface for resource manager local transactions. The system contract level LocalTransaction interface (as defined in the javax.resource.spi package) is used by the container for local transaction management.

A local transaction is managed internal to a resource manager. There is no external transaction manager involved in the coordination of such transactions.

A CCI implementation can (but is not required to) implement the LocalTransaction interface. If the LocalTransaction interface is supported by a CCI implementation, then the method Connection.getLocalTransaction() should return a LocalTransaction instance. A component can then use the returned LocalTransaction to demarcate a resource manager local transaction (associated with the Connection instance) on the underlying EIS instance.

The com.bea.adapter.spi.AbstractLocalTransaction class also implements this interface.

Record

javax.resource.cci.Record

A MappedRecord or IndexedRecord can contain another Record. This means that you can use MappedRecord and IndexedRecord to create a hierarchical structure of any arbitrary depth. A basic Java type is used as the leaf element of a hierarchical structure represented by a MappedRecord or IndexedRecord.

Assuming the adapter implements a CCI interface, the next consideration is the record format for a service. A service has a request record format and a response record format. The request record provides input to the service and the response record provides the EIS response.

ADK Implementation

The ADK focuses on helping you implement an XML-based record format in the CCI layer. To this end, the ADK provides the DocumentRecord class. In addition, you can use BEA's schema toolkit to develop schemas to describe the request and response documents for a service.

The ADK provides RecordImpl, a concrete implementation of the javax.resource.cci.Record interface that provides getter and setter methods for record name and description.

If an adapter provider wants to use an XML-based record format (which is highly recommended), the ADK also provides the com.bea.adapter.cci.Abstract DocumentRecordInteraction class. This class ensures that the client passes DocumentRecord objects. In addition, this class provides convenience methods for accessing content in a DocumentRecord.

ResourceAdapterMetaData

javax.resource.cci.ResourceAdapterMetaData

The interface javax.resource.cci.ResourceAdapterMetaData provides information about capabilities of an adapter implementation. A CCI client uses a ConnectionFactory.getMetaData to get metadata information about the adapter. The getMetaData() method does not require establishment of an active connection to an EIS instance. The ResourceAdapterMetaData interface can be extended to provide more information specific to an adapter implementation.

Note: This interface does not provide information about an EIS instance that is connected through the adapter.

ADK Implementation

The ADK provides ResourceAdapterMetaDataImpl that encapsulates adapter metadata and provides getters and setters for all properties.

Step 5: Testing the Adapter

The ADK provides a test harness that leverages JUnit, an open-source tool for unit testing. You can find more information on JUnit at:

com.bea.adapter.test.TestHarness does the following:

Using the Test Harness

To use the test harness in the ADK, complete the following steps:

Test Case Extensions Provided by the ADK

The sample adapter ships with two basic TestCase extensions:

sample.spi.NonManagedScenarioTestCase

NonManagedScenarioTestCase allows you to test your SPI and CCI classes in a non-managed scenario. Specifically, this class tests the following:

sample.event.OfflineEventGeneratorTestCase

sample.event.OfflineEventGeneratorTestCase allows you to test the inner workings of your event generator outside of Weblogic Server. Specifically, this class tests the following for the event generator:

sample.client.ApplicationViewClient

sample.client.ApplicationViewClient offers an additional way of test your adapter. This class is a Java program that demonstrates how to invoke a service and listen for an event on an application view. The Ant build.xml provides the "client" target to allow you to use the ApplicationViewClient program. Executing ant client will provide the usage for the program. To see an example of sample.client.ApplicationViewClient.java, go to WLI_HOME/adapters/ sample/src/sample/client.

Note: sample.client.ApplicationViewClient is not integrated with the test harness.

Step 6: Deploying the Adapter