Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| WebLogic Integration
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package com.bea.adapter.cci

The client interface allows a J2EE-based 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.

See:
Description

Class Summary
AbstractConnection | A simple implementation of the CCI Connection interface.
AbstractDocumentRecordInteraction | Provides a base implementation for adapter providers to extend.
AbstractInteraction | Provides a base implementation for adapter providers to extend.
ConnectionFactoryImpl | A simple, concrete implementation of the CCI ConnectionFactory interface.
DesignTimeInteractionSpecImpl | Encapsulates properties for driving an `Interaction` with an EIS instance that is used to generate metadata for design-time.
DocumentDefinitionRecord | This class encapsulates an IDocumentDefinition as a DocumentRecord.
DocumentInteractionSpecImpl | Extends the base InteractionSpecImpl class to provide an implementation of the com.bea.connector.DocumentInteractionSpec interface.
InteractionSpecImpl | Encapsulates properties for driving an `Interaction` with an EIS instance.
RecordImpl | Provides a base implementation for a `Record`.
ResourceAdapterMetaDataImpl | Encapsulates metadata about a resource adapter.

## Package com.bea.adapter.cci Description

The client interface allows a J2EE-based 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, an adapter developer must determine if their must support the J2EE Connector Architecture Common Client Interface (CCI). Although not a requirement in the 1.0 J2EE Connector Architecture specification, it is likely to be a requirement in the next version. Consequently, the ADK focuses on helping developers implement, a CCI interface for their adapter.

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

The ADK provides AbstractConnection: abstract implementation of the javax.resource.cci.Connection interface that:

- Provides access to the ADK logging framework.
- Provides access to an AbstractManagedConnection instance

· Provides state management and assertion checking.

Adapter developers will need to extend this class. Specifically, they must provide an implementation for:

public Interaction createInteraction()

throws ResourceException

Creates an Interaction associated with this Connection. An Interaction enables an application to execute EIS functions.

Returns:

Interaction instance

Throws:

ResourceException - Exception if the create operation fails

### javax.resource.cci.ConnectionFactory

``

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

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.Referenceable`interfaces to support JNDI registration.

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

- Provides access to the ADK logging framework.

· Provides access to resource adapter metadata.

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

### javax.resource.cci.ConnectionMetaData

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

By default, the ADK provides an implementation of this class via the com.bea.adapter.spi.AbstractConnectionMetaData class.

### 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 the ConnectionSpec interface be implemented as a JavaBean to 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, a resource adapter may define additional properties specific to its underlying EIS.

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

### 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:

· `execute` method that takes an input Record, output Record and an InteractionSpec. This method executes the EIS function represented by the InteractionSpec and updates the output Record

· `execute` method that takes an input Record and an InteractionSpec. This method implementation executes the EIS function represented by the InteractionSpec and produces the output Record as a return value.

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 resource adapter for the Interaction. The close of an Interaction instance should not close the associated Connection instance.

AbstractInteraction: concrete implementation of the javax.resource.cci.Interaction interface that:

- Provides access to the ADK logging framework.

· Manages warnings.

Adapter developers must supply a concrete extension to AbstractInteraction that implements:

execute

public boolean execute(InteractionSpec ispec,

Record input,

Record output)

throws ResourceException

Executes an interaction represented by the InteractionSpec. This form of invocation takes an input Record and updates the output Record.

Parameters:

ispec - InteractionSpec representing a target EIS data/function module

input - Input Record

output - Output Record

Returns:

true if execution of the EIS function has been successful and output Record has been updated; false otherwise

Throws:

ResourceException - Exception if execute operation fails

execute

public Record execute(InteractionSpec ispec,

Record input)

throws ResourceException

Executes an interaction represented by the InteractionSpec. This form of invocation takes an input Record and returns an output Record if the execution of the Interaction has been successfull.

Parameters:

ispec - InteractionSpec representing a target EIS data/function module

input - Input Record

Returns:

output Record if execution of the EIS function has been successful; null otherwise

Throws:

ResourceException - Exception if execute operation fails

### javax.resource.cci.InteractionSpec

An InteractionSpec holds properties for driving an Interaction with an EIS instance. An InteractionSpec 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 Java Beans design pattern.

The standard properties are as follows:

FunctionName: name of an EIS function

InteractionVerb: mode of interaction with an EIS instance: SYNC_SEND, SYNC_SEND_RECEIVE, SYNC_RECEIVE

ExecutionTimeout: the number of milliseconds an Interaction will wait for an EIS to execute the specified function

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

FetchSize

FetchDirection

MaxFieldSize

ResultSetType

ResultSetConcurrency

A CCI implementation can provide additional properties beyond that described in the InteractionSpec interface. Note that the format and type of the additional properties is specific to an EIS and is outside the scope of the CCI specification.

It is required that the InteractionSpec interface be implemented as a JavaBean for the toolability support. The properties on the InteractionSpec implementation class should be defined through the getter and setter methods pattern. An implementation class for InteractionSpec interface is required to implement the

java.io.Serializable interface.

>>> Interaction spec contains information that is not in record but helps determine what EIS function to invoke.

InteractionSpecImpl: concrete implementation of the javax.resource.cci.InteractionSpec interface that:

Provides getter and setter methods for the standard interaction properties: function name, timeout, and interaction verb.

### javax.resource.cci.LocalTransaction

The LocalTransaction defines a transaction demarcation interface for resource manager local transactions. Note that this interface is used for application level local transaction demarcation. 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.

### javax.resource.cci.Record

The `javax.resource.cci.Record` interface is the base interface for the representation of an input or output to the execute methods defined on an Interaction.

The Record interface can be extended to form a one of the following representations:

MappedRecord: A key-value pair based collection represents a record. This interface is based on the `java.util.Map`

IndexedRecord:An ordered and indexed collection represents a record. This interface is based on the `java.util.List`.

JavaBean based representation of an EIS abstraction: An example is a custom record generated to represent a purchase order in an ERP system.

`javax.resource.cci.ResultSet`: This interface extends both `java.sql.ResultSet` and `javax.resource.cci.Record`. A ResultSet represents tabular data.

A MappedRecord or IndexedRecord can contain another Record. This means that MappedRecord and IndexedRecord can be used 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's response. The ADK focuses on helping developers implement an XML-based record format in the CCI layer. To this end, the ADK provides the DocumentRecord class. In addition, an adapter developer 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 wishes to use an XML-based record format, the ADK also provides the com.bea.adapter.cci.AbstractDocumentRecordInteraction class. This class ensures that the client passes DocumentRecord objects. In addition, this class provides convenience methods for accessing content in a DocumentRecord.

### javax.resource.cci.ResourceAdapterMetaData

The interface `javax.resource.cci.ResourceAdapterMetaData` provides information about capabilities of a resource adapter implementation. Note that this interface does not provide information about an EIS instance that is connected through the resource adapter.

A CCI client uses a `ConnectionFactory.getMetaData` to get metadata information about the resource adapter. The `getMetaData` method does not require that an active connection to an EIS instance should have been established.

The ResourceAdapterMetaData can be extended to provide more information specific to a resource adapter implementation.

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

Author:
  Copyright © 2000, 2001 BEA Systems, Inc. All Rights Reserved.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| WebLogic Integration
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

WebLogic Integration (WLI)