Common Client Interface

Overview

The CCI is a standard client API for use by application components. It is designed to provide a base-level API for EIS access upon which higher level functionality will be built by EAI and tools vendors. The CCI is divided into five parts, each of which we'll discuss in the panels that follow. The CCI's five parts are:

• Connection-related interfaces
• Interaction-related interfaces
• Data representation-related interfaces
• Metadata-related interfaces
• Exceptions and warnings

A resource adapter is not required to provide support for the CCI. In fact, the resource adapter may define its own client API, different from the CCI.

Connection-related interfaces

The CCI uses its ConnectionFactory interface to get a connection handle to an EIS. The ConnectionFactory provides two getConnection() methods: one with no parameters and one that takes a ConnectionSpec instance as a parameter. The second getConnection() is used when connection request-specific information must be provided with the connection request.

The ConnectionFactory also provides methods to return metadata information about the resource adapter (getResourceAdapterMetaData()) and to return a record factory (getRecordFactory()).

ConnectionSpec is an empty interface that may be extended to add whatever properties are desired. Two standard properties, UserName and Password, are defined by JCA, but additional properties (or no properties) may be supported. The resource adapter should map the properties of ConnectionSpec to those of ConnectionRequestInfo when calling allocateConnection() on the ConnectionManager.

Connection methods

The Connection interface is an application-level connection handle that is used to access an EIS. It provides the following methods to manage connections between the application and the EIS:

• The close() method allows an application to close the connection handle, as required by the connection-management contract.
• The getLocalTransaction() method allows an application component to use local transactions.
• The createInteraction() method returns an Interaction object, which is used for accessing EIS functions.
• The getResultSetInfo() method returns information about the result set functionality supported by the EIS.
• The getMetaData() function returns metadata about the connection.

Interaction-related interfaces

An Interaction instance allows an application component to execute EIS functions. It has two execute() methods: one that takes an InteractionSpec and an input Record and returns an output Record, and one that takes an InteractionSpec, an input Record, and an output Record. This method executes the appropriate EIS function, as defined in InteractionSpec, and updates the output Record.

The Interaction must maintain its association with the Connection that created it, and the getConnection() must return that Connection.

The close() method on an Interaction should release all resources maintained for the Interaction, but should not close the Connection.

Standard interaction properties and values

The InteractionSpec interface provides properties for a specified EIS function. It defines the following standard properties:

• FunctionName is a string that represents the name of an EIS function.
• InteractionVerb is an integer that specifies the mode of interaction with the EIS.

Allowable values for InteractionVerb are:

• SYNC_SEND: The input record is sent to the EIS with no results returned.
• SYNC_SEND_RECEIVE: The input record is sent to the EIS and a result is returned.
• SYNC_RECEIVE: A result is synchronously retrieved from the EIS.
• ExecutionTimeout is the number of milliseconds to wait for the EIS to execute the function.

Data representation-related interfaces

The Record interface provides for a Java representation of the data used for input or output to an EIS. Record has two standard properties: RecordName and

RecordShortDescription. Additional properties to represent EIS record data must be defined by the implementer.

Three additional interfaces that extend Record are also provided. The MappedRecord interface provides access to the record elements in a key-value map collection. The IndexedRecord interface provides access to the record elements as an ordered collection. The ResultSet interface is based on the JDBC ResultSet and provides similar functionality for accessing EIS data.

The RecordFactory interface provides methods to create MappedRecord and IndexedRecord instances. One, both, or neither type of record may be supported by the RecordFactory. If neither, then the getRecordFactory() method of ConnectionFactory should throw an exception.

Metadata-related interfaces

The ConnectionMetaData interface provides information about the EIS name, the EIS version, and the user name, similar to the ManagedConnectionMetaData interface. The ResourceAdapterMetaData interface provides information about the adapter name, version, vendor, description, and the version of JCA supported by the resource adapter. It also provides methods to determine the following capabilities of the resource adapter: whether InteractionSpecs are used; which execute() method variants are supported; and whether local transactions can be demarcated by application components.

Exceptions and warnings

ResourceException is the root of the exception hierarchy for the system contracts and for CCI. It provides a string describing the error, an error code, and a reference to another exception, which may be the lower-level problem that caused the ResourceException. ResourceWarning provides information about warnings that have been returned by an EIS as the result of an Interaction. ResourceWarnings form a chain; a call to getWarnings() on Interaction retrieves the first warning, and the rest of the chain is accessed through that warning.

---