Technical Overview of JCA Adapters

The components provided for developing Oracle Java CAPS JCA Adapters include the runtime JCA resource adapter component as well as the design time tools to facilitate developing applications that utilize the JCA resource adapter. The design time tools included are:

• Code wizards that generate template JCA resource adapter client code.

• Wizards that generate code based on higher level object models pertaining to the external applications. The model used is referred to as Object Type Definitions (OTD) and the application-specific wizards are referred to as OTD Wizards.

Inbound JCA Resource Adapter Client Code

JCA Resource Adapters that support inbound communication depend on deployment of a Message-Driven Bean (MDB). To develop an application utilizing a JCA Adapter for inbound communication, the JCA Message-Drive Bean wizard must be used. When the wizard is finished, the message driven bean code skeleton is generated. For example, for the File JCA Adapter, the following MDB code skeleton is created:

/*

* To change this template, choose Tools | Templates

* and open the template in the editor.

*/

package test;

import javax.ejb.MessageDriven;

import com.stc.connector.fileadapter.eway.FileListener;

import com.stc.connector.framework.eway.FaultException;

import com.stc.connector.framework.eway.InboundException;

/**

*

* @author

*/

@MessageDriven(name="test.FileJCAMessageBean")

public class FileJCAMessageBean implements FileListener {

public FileJCAMessageBean() {

}

public void onContents(byte[] data, String encoding) throws FaultException,

InboundException {

// implement listener interface here

}

}

Outbound JCA Resource Adapter Client Code

JCA Adapters that support outbound connection to an external application are utilized via the client interface supported by the adapter. The client interface supported by Oracle Java CAPS JCA Adapters are based on a simple Application Client Interface. The client interface involves establishment of an application connection via JNDI. The application connection is a container managed connection obtained from a connection pool. The application connection is used along with the OTD objects provided with the JCA adapter to perform operations on the external application.

The tooling for creating code, based on the outbound JCA's client interface is provided via the adapter in the form of specific objects from the Palette draggable onto the code editor. The Palette is made visible by selecting Palette from the Window top-level drop-down menu.

Upon dragging an item from the Palette to the code editor, the JCA wizard is started. In the JCA wizard, a method name must be specified. The method will be added to the code being edited. Depending on the type of external dragged from the Palette, the choice of OTD to be used may need to be specified. The JCA client interface code, required to obtain a JCA connector resource from JNDI, establishes then closes the JCA connection. It then instantiates the associated OTD object, which is also added. The method specified in the JCA wizard is created to simplify development of application logic as the method implementation can simply use OTD objects passed in.

For example, dragging the File object from the Palette to the onContents method of the File MDB and specifying a method name "send" in the JCA wizard adds the following code in the onContents method implementation:

public void onContents(byte[] data, String encoding) throws FaultException,

InboundException {

try {

_invoke_send(data, encoding);

} catch (java.lang.Throwable t) {

ectx.setRollbackOnly();

java.util.logging.Logger.getLogger(this.getClass().getName(

)).log(java.util.logging.Level.WARNING, "Failed to invoke _invoke_send: " + t, t);

}

}

The user application logic can be implemented in the send method which works directly with the OTD objects passed in.

private void send(byte[] data, String encoding, com.stc.connector.fileadapter.appconn.FileClientApplication fileOTD) throws java.lang.Exception {

}

The additional code shown below are also added providing the connection establishment and OTD instantiation.

// <editor - fold defaultstate= collapsed desc="Connection setup and takedown.

Click on the + sign on the left to edit the code.">

private void _invoke_send(byte[] data, String encoding) throws java.lang.Exception {

com.stc.connector.appconn.common.ApplicationConnection fileConnection = null;

try {

if (fileConnection != null) {

fileConnection.close();

}

} catch (Exception e) {

}

}

} // </editor-fold>

// <editor-fold defaultstate="collapsed" desc="file resource declaration. Click on the + sign on the left to edit the code.">

// comments for inserted variable

@javax.annotation.Resource(name = "jca/file", description = "", shareable = false)

private com.stc.connector.appconn.common.ApplicationConnectionFactory file; // </editor-fold>

// <editor-fold defaultstate="collapsed" desc="EJBContext declaration. Click on the + sign on the left to edit the code.">

@javax.annotation.Resource

private javax.ejb.EJBContext ectx; // <editor-fold>

Object Type Definition Wizards

The client interface to certain external applications may involve dynamically generating Object Type Definition code based on the external application metadata. This step is accomplished by executing the OTD wizards. The jar containing the generated OTD code is added to the NetBeans project where it can be used as a library.

The classes generated by the OTD wizard varies for each external system or application. The database OTD wizards, for instance, will generate code that will facilitate querying or updating databases while the SAP OTD wizards will provide objects representing SAP BAPIs or IDocs to facilitate operations on those entities. For more detailed information on the specific OTDs or models, refer to the corresponding sections on Designing with the respective JCA Adapters.