4 Developing an Adapter Runtime Component for Integration with Fusion Middleware

This chapter discusses the process for developing an adapter runtime component for integration with Fusion Middleware.

There are several design and connection configuration steps involved with developing an adapter runtime component.

These include:

4.1 Understanding Overall Design

The Oracle JCA Framework provides pluggability for adapters that comply to the J2EE Java Connector Architecture, version 1.5. That is, any adapter used with the Oracle JCA Framework must fulfill the requirements documented in the JCA 1.5 specification (see also JSR-112, J2EE Connector Architecture 1.5 - Final Release).

Note:

The Oracle JCA Framework implements a lightweight JCA 1.5 container, which enables dynamic (code-driven) deployment of inbound endpoints (activations). This does mean a small disadvantage in precluding support for JCA 1.5 Transaction Inflow (that is, support for XATerminator support).

4.2 Connection Configuration

The Oracle JCA Framework requires a JCA adapter that is deployable on a J2EE 1.4- (or later) compliant Application Server, for example, Oracle WebLogic Server. Hence, any JCA adapter used with the Oracle JCA Framework must implement all the relevant JCA SPI (Service Provider) and CCI (Common Client) interfaces as mandated by the JCA 1.5, specification, principally the following:

javax.resource.spi.ManagedConnectionFactory

javax.resource.cci.ConnectionFactory

javax.resource.spi.ManagedConnection

javax.resource.cci.Connection

The JCA adapter must define the necessary connection properties in its ManagedConnectionFactory to establish a functional connection to an EIS (Enterprise Information System, or "back-end").

Properties in the ManagedConnectionFactory enable the Oracle JCA Framework to obtain a connection via a deployed JCA Adapter. Example code is:

ConnectionFactory cf = initialContext.lookup("eis/Siebel/SiebelApp1-Connection");

Connection c = cf.getConnection();

All connection properties are retrieved through the JNDI lookup contained in the ConnectionFactory instance.

4.3 Run Time Interfaces and Contracts

The Adapter must comply with specific interfaces and contracts to successfully interact with the Oracle JCA Framework. Principally, the JCA adapter must implement at least the following interfaces:

javax.resource.spi.ResourceAdapter
javax.resource.spi.ActivationSpec
javax.resource.spi.work.Work
javax.resource.cci.Interaction
javax.resource.cci.InteractionSpec

These SPI interfaces must be implemented to enable inbound message flow, and the CCI interfaces must be implemented to enable outbound interactions. See the following sub sections.

4.3.1 Inbound

The J2EE Java Connector Architecture, version 1.5, provides interfaces that enable an adapter to asynchronously push messages to endpoints managed by the J2EE Application Server in a well-defined manner in terms of transactions (that is, when an adapter supports transactional semantics).

In the Oracle JCA Framework, these endpoints are managed by the Adapter Framework.

4.3.2 JCA 1.5 Contracts and Interfaces

The following sub-sections describe each of the Service Provider Interfaces (SPI) that a JCA 1.5 compliant Resource Adapter must implement in order to be deployable to Oracle Fusion Middleware.

4.3.2.1 Interfacejavax.resource.spi.ResourceAdapter

Each JCA adapter must implement this interface. The Adapter Framework treats an Adapter's implementation of this interface as a singleton; that is, there will be at most be one instance of an implementation of this interface per Java Virtual Machine.

If an adapter is not used by *any* business process (in particular JVM) then it's ResourceAdapter implementation will not be instantiated

4.3.2.2 Instantiation

The ResourceAdapter implementation is instantiated when the first composite application using the adapter is started.

Subsequent starting composites that also use the same adapter do not cause additional ResourceAdapter instances to be created, but obtain a handle to the first (singleton) instance.

The following method is called immediately after the ResourceAdapter instance is created:

public void start(BootstrapContext ctx)
   throws ResourceAdapterInternalException

The adapter should cache the BootstrapContext, as it contains necessary facilities for creating and scheduling inbound endpoint interactions.

The BootstrapContext also contains a Logging service handle, which the resource adapter should cache and use throughout all classes supporting inbound message flow (that is. classes provided under javax.resource.spi.*).

Outbound, the Logging service handle will be available through the ConnectionFactory.

4.3.2.3 Stop Method and Endpoint Activation

The stop method is called when a resource instance is undeployed, during application server shutdown, or when the last composite referring to the adapter is terminated.

public void stop()

If active endpoints exist, they must be deactivated before returning from the stop() method, invoked by the adapter framework during server or composite shutdown.

Any other allocated resources must similarly be released promptly:

public void endpointActivation(MessageEndpointFactory endpointFactory,
       ActivationSpec spec)

Endpoint activation is called during the activation of a message endpoint.

Each composite that has an initiating or non-initiating JCA-based Service entry point (that is, an entry point using binding.jca in the <service>) causes the invocation of endpointActivation() for each associated (inbound) operation for the ResourceAdapter referenced by the connection factory JNDI in the .jca property file.

4.3.2.4 Connection Factory, Work Request, Endpoint Deactivation

The Adapter Framework provides, through the MessageEndpointFactory, an instance of the ConnectionFactory, as defined in the <connection-factory> element in the .jca property file, which then can be used by the resource adapter to create connections:

javax.resource.cci.ConnectionFactory connectionFactory =
    ((ConnectionFactoryAssociation)activationSpec).getConnectionFactory();
javax.resource.cci.Connection connection = connectionFactory.getConnection();

During this invocation, the resource adapter must use the MessageEndpointFactory to create the inbound endpoint and to submit a Work request for execution, which constitutes the inbound thread that monitors the inbound EIS endpoint.

ResourceAdapterInboundWorkerThread workRequest =
    new ResourceAdapterInboundWorkerThread(endpoint, activationSpec, connection);
      workManager.startWork(workRequest);

Here ResourceAdapterInboundWorkerThread is the resource adapter's implementation of javax.resource.spi.work.Work.

Soon after returning from startWork(),the Adapter Framework allocates and assigns a thread to the submitted workRequest by calling its run()method.

The following method, endpointDeactivation, is called by the Adapter Framework when a message endpoint is deactivated; that is, either when the composite having activated the endpoint shuts down, or when the application server shuts down.

public void endpointDeactivation(MessageEndpointFactory
  endpointFactory, ActivationSpec spec)

Note:

For a custom adapter to work in the Oracle Weblogic environment, the custom adapter's Connetion Factory needs to implement oracle.tip.adapter.api.OracleConnectionFactory. If the custom adapter's Connetion Factory needs to implement oracle.tip.adapter.api.OracleConnectionFactory, then add a <resource-adapter> element to the <connection-factory> in the .jca generated by JDeveloper. For example,

<connection-factory location="eis/Custom/CustomAdapter"/>
        <resource-adapter className="com.custom.oracle.fusion.adapter.CustomAdapter"/>
</connection-factory>

4.3.3 Interfacejavax.resource.spi.work.Work

The Work interface is:

public interface Work extends Runnable

Because a JCA 1.5-compliant resource adapter deployed with the Oracle SOA will be executing in Managed Mode (that is, inside a J2EE container), it cannot create threads on its own. Rather, the adapter must rely on the WebLogic Application Server to create and start threads on its behalf.

To obtain a thread (for example, a thread to be used to poll an inbound endpoint), the adapter must submit an instance of a class implementing the Work interface to the WorkManager (which in turn is obtained via the BootstrapContext).

The adapter does this by the run method:

public void run()

This method is invoked by the WorkManager, using a newly allocated J2EE-compliant thread. The resource adapter can use this thread until it chooses to stop (for example, due to a unrecoverable error condition; however, this convention is not recommended) or, more appropriately, until the adapter is signalled to stop (by the release() method):

public void release()

The adapter itself invokes release() when it is processing the invocation of endpointDeactivation made by the Adapter Framework.

This activity is called on a separate thread from the one currently executing the Work instance, that is, from the system thread invoking endpointActivation.

If the resource adapter does not exit the run()method after a preset time following the invocation of release(), the Adapter Framework attempts to forcefully stop the thread.

4.3.4 Interfacejavax.resource.spi.work.WorkManager

In Oracle SOA, the implementation of the WorkManager interface is provided by the Adapter Framework. The implementation is minimal, because it does not support advanced thread pooling or sophisticated scheduling.

Instead, the Adapter Framework implements only one of six public methods, scheduleWork(Work work). The other public methods are redirected to this method, that is, call blocking is not supported (as for example, it is required by doWork()).

The Adapter Framework leverages the SOA default Work Manager, enabling threads freed from a finished Work instance to be reused in new Work submissions.

The following method accepts a Work instance for processing.

public void scheduleWork(Work work)

   throws WorkException

This call does not block and returns immediately once a Work instance has been accepted for processing. There is no guarantee when the submitted Work instance starts execution; that is, there is no time constraint to start execution.

4.3.5 Outbound Considerations

In outbound and inbound scenarios, the Resource Adapter must comply to the standard contracts defined by the JCA 1.0 specification.

In the outbound scenario, when providing the runtime definition of an adapter, you must adhere to the following requirements:

The ManagedConnectionFactory of the Resource Adapter must define all of its connection related parameters, thereby allowing the Oracle SOA runtime to simply perform. For example:
```
ConnectionFactory cciConnectionFactory = 
   initialContext.lookup("eis/sample/...");
Connection cciConnection = cciConnectionFactory.getConnection();
```
All regular InteractionSpec parameters on any InteractionSpec implementation must be constituted by single argument mutator methods, using one of the following argument types: String, int, boolean, short, long, float, double.
The Resource Adapter must be able to function in a Managed Environment, and as such it must be deployable on the J2EE Application Server.

4.3.6 Translation Service Interface

The Translation Service interface handles translation of a message to and from native formats. The Adapter Framework determines any operation-related message Translation to- or from- native format requirements by inspecting the InteractionSpec or ActivationSpec for a given WSDL Binding Operation.

If one of the indicated Specs implement the Translation marker interface TranslationAware, the Adapter Framework supplies the corresponding XSDElement from the WSDL types section, which defines the input message type.

Specifically, the Adapter Framework performs the following steps:

jcaInteractionSpec=(InteractionSpec)
  Class.forName(_interactionSpecName).newInstance();
    if (jcaInteractionSpec instanceof TranslationAware)
      {
            oracle.xml.parser.schema.XMLSchema nXsdSchemaRoot =
              getInputMessageSchemaElement();
              ((TranslationAware)jcaInteractionSpec).
                 setNXSDSchemaRoot(nXsdSchemaRoot);
                 }
jcaInteraction.execute(jcaInteractionSpec, ...

4.4 Constructing the WebLogic JCA Resource Archive RAR

To deploy a JCA adapter on a WebLogic Application Server, the user must create a Deployment Descriptor file that defines the following properties:

The display name
The adapter vendor
The EIS/back-end type
The version numbers
The class name of adapter implementation of javax.resource.spi.ManagedConnectionFactory
The class name of the adapter implementation of javax.resource.cci.ConnectionFactory
The class name of adapter implementation of javax.resource.cci.Connection
The names of all bean properties exposed in the ManagedConnectionFactory implementation.

The deployment descriptor only defines an instance of <outbound-resourceadapter> because the inbound JCA runtime container is directly managed by the Oracle JCA Framework rather than by the Oracle WebLogic Server.

The deployment descriptor file (ra.xml) must be archived into a RAR file (resource archive), which then can be deployed using the WebLogic Server Console or through scripting.

The RAR file that the user deploys must have the following structure:

/META-INF/ra.xml
/adapter.jar
/dependencies.jar

The adapter.jar file contains the implementation of the JCA adapter, and dependencies.jar contains all dependent Java libraries that are not implicitly provided by the WebLogic Application Server.

Once these constituent files have been placed in the above directory structure, you can create the RAR file using the command:

$ jar cf myAdapter.rar META-INF/ra.xml adapter.jar dependencies.jar

See the appendix for a list of jar files that are required to compile a project.

4.5 Deploying the RAR File to the WebLogic Application Server

After creating the adapter resource archive, the user must deploy the adapter on the WebLogic Application Server, either through the Deployment section of the WLS Management Console, or by using the WLST tool (see http://docs.oracle.com/cd/E13222_01/wls/docs90/config_scripting/reference.html#1024285).

The RAR file can also be directly copied to the autodeploy directory under the WebLogic Server domain directory, where it will be automatically deployed.

After having deployed the RAR, the user can create connection factories under the WebLogic Server Management Console Deployment section. See the following screenshot for an example, using the Outbound Connection Pool Configuration Table.

Figure 4-1 Creating Connection Factories using the WebLogic Server Management Console

Description of "Figure 4-1 Creating Connection Factories using the WebLogic Server Management Console"

4.6 Testing the Custom Adapter

See the Samples section later in this document for information related to testing the Custom Adapter.