3 Integrating OracleAS Adapters for CICS with OC4J

To deploy and integrate OracleAS Adapters for CICS with Oracle Application Server Containers for J2EE (OC4J), you need to configure the J2CA 1.5 CICS adapter.

This section includes the following topics:

Overview of Integrating OracleAS Adapters for CICS with OC4J
Integrating the J2CA 1.5 CICS Adapter for Outbound
Integrating the J2CA 1.5 CICS Queue Adapter for Inbound

Overview of Integrating OracleAS Adapters for CICS with OC4J

Oracle Application Server provides a complete Java 2 Enterprise Edition (J2EE) environment that executes on the Java Virtual Machine (JVM) of the standard Java Development Kit (JDK). OC4J is J2EE certified and provides all the J2EE specific containers, APIs, and services. OC4J supports the J2CA 1.5 standard.

J2CA defines standard Java interfaces for simplifying the integration of applications with the EIS. OracleAS adapters are deployed as a Resource Adapter (RA) within the OC4J container.

The contract between the OC4J client application and the resource adapter is defined by the common client interface (CCI). The contract between the OC4J container and the resource adapter is defined by the service provider interface (SPI). The SPI API addresses the connection management, transaction management and the security management.

Connection management enables application components to connect to an EIS and leverage any connection pooling provided by the application server.

Transaction management enables an application server to use a transaction manager to manage transactions across multiple resource managers.

Lifecycle management contracts enable an application server to initialize a resource adapter instance during the deployment of the adapter or application server startup. In addition, it enables the application server to notify the resource adapter instance during server shutdown or undeployment of the adapter.

The lifecycle contract provides the mechanism for the application server to manage the lifecycle of the resource adapter instance.

Work management contracts enable the resource adapter to carry out its logic by using threads dispatched by an application server, rather than creating threads on its own. The handshake is done through a Work instance submission. This makes the application server threads management more efficient, providing better control over their execution contexts (like security and transaction).

Message inflow contracts enable the resource adapter to send asynchronous messages to an application server message endpoints regardless of the messaging style, semantics, or delivering infrastructure. This enables a wide variety of message providers (like Java Message Service (JMS), or Java API for XML (JAXM)) to be plugged into an application server through the resource adapter.

Integrating the J2CA 1.5 CICS Adapter for Outbound

This section includes the following topics:

Configuring the J2CA 1.5 CICS Adapter for Outbound
Using the CCI API to Develop Applications

Configuring the J2CA 1.5 CICS Adapter for Outbound

To connect to the J2CA 1.5 CICS adapter under Oracle Application Server, you need to set the relevant parameters in the connection factory. You can perform this task by using Oracle Enterprise Manager, or by carrying out the following steps:

Open the following file in an editor:
```
root\j2ee\home\application-deployment\default\oracle\oc4j-ra.xml
```
where root is the Oracle Application Server root directory.

In this file, set the following parameters for each connection.

<oc4j-connector-factories>
  <connector-factory location=" " connector-name="Oracle Legacy Adapter">
    <config-property name="userName" value=" "/>
    <config-property name="password" value=" "/>
    <config-property name="eisName" value=" "/>
    <config-property name="serverName" value=" "/>
    <config-property name="workspace" value=" "/>
    <config-property name="portNumber" value=" "/>
    <config-property name="persistentConnection" value=" "/>
    <config-property name="keepAlive" value=" "/>
    <config-property name="firewallProtocol" value=""/>
    <config-property name="connectTimeout" value=""/>
    <config-property name="encryptionProtocol" value=""/>
    <config-property name="encryptionKeyName" value=""/>
    <config-property name="encryptionKeyValue" value=""/>
    <config-property name="fakeXA" value=" "/>
    <config-property name="useNamespace" value=" "/>
    <config-property name="networkXMLProtocol" value=" "/>
    <config-property name="exposeEventStreamMetadata" value=" "/>
  </connector-factory>
</oc4j-connector-factories>

Note:

location is the attribute that specifies the JNDI location where Oracle Application Server should bind the connection factory instance for application components.

Table 3-1 provides a detailed description of these parameters.

Table 3-1 OC4J Connection Properties for Outbound Interactions

Property	Description
`eisName`	Required. Sets the name of the adapter to use. The adapter is defined in Oracle Connect server using Oracle Studio.
`serverName`	Required. Sets the TCP/IP address or host name where the Oracle Connect daemon is running.
`workspace`	Optional. Specifies the name of an Oracle Connect server workspace to use. The default workspace is `Navigator`.
`portNumber`	Optional. Specifies the TCP/IP port where the Oracle Connect daemon is running on the server. The default port is `2551`.
`userName`	Optional. Specifies a user who can access the Oracle Connect server. The user is defined in the Oracle Connect daemon configuration. See Also: "Daemon Security" and "WS Security" for details about users allowed to access an Oracle Connect server.
`password`	Optional. Specifies a valid password for the user.
`persistentConnection`	Optional. Set to `true` or `false`. When set to `true`, connections can persist across multiple requests or connection context changes. It is recommended to set this property to `true`.
`keepAlive`	Optional. Set to `true` or `false`. When set to `true`, the socket used for the connection is always kept open. It is recommended to set this property to `true`.
`firewallProtocol`	Optional. Specifies the firewall protocol used: either `none` or `fixedNat` (the Nat protocol using a fixed address for the daemon). The default is set to `none`.
`connectTimeout`	Optional. Specifies the connection timeout in seconds. The default is 0, indicating that there is no connection timeout.
`encryptionProtocol`	Optional. Specifies the name of encryption protocol to use. The default is set to `null`. The RC4 protocol is supported.
`encryptionKeyName`	Optional. Specifies the name of the symmetric encryption key to use.
`encryptionKeyValue`	Optional. Specifies the value of the symmetric encryption key to use.
`fakeXa`	Optional. Set to `true` or `false`, according to the value of the `transaction support` property of the corresponding CICS adapter. When set to `true`, the XA APIs are internally converted to local transaction APIs.
`useNamespace`	Optional. Set to `true` or `false`. When set to `true`, the metadata record schema uses namespaces.
`networkXMLProtocol`	Optional. Specifies how the XML is passed over the network. `Binary` or `Text` can be selected.
`exposeEventStreamMetadata`	Optional. When set to `true`, the standard XSD schema is used for the CICS/Q adapter inbound events metadata. When `false`, the native schema is used.

Configuring Multiple Adapters

Each J2CA 1.5 CICS adapter requires an entry in the oc4j-ra.xml file as described in "Configuring the J2CA 1.5 CICS Adapter for Outbound".

Updating Configuration Information

You can change the configuration settings for a resource adapter by editing the relevant connector-factory entry in the oc4j-ra.xml file. For these changes to take effect, you need to stop and restart Oracle Application Server.

Using the CCI API to Develop Applications

You can develop applications to run adapter interactions using the Common Client Interface (CCI) API.

Perform the following steps to use the CCI API with the J2CA 1.5 CICS adapter:

Select a ConnectionFactory object for the J2CA 1.5 CICS adapter.
Create a Connection object using the selected ConnectionFactory. A Connection is a handle to the underlying network connection to the EIS, which is identified in the oc4j-ra-xml file by the serverName property.

Create a Connection object using the selected ConnectionFactory. Specify the interaction properties using an AttuInteractionSpec object. The AttuInteractionSpec object has the following format:

AttuInteractionSpec(java.lang.String name, int verb, int timeOut)

The following table describes the properties that can be specified:

Table 3-2 Interaction Spec Properties

Property	Description
`name`	Specifies the interaction name to be executed.
`verb`	Specifies the mode for the interaction: `SYNC_SEND`, `SYNC_SEND_RECEIVE`, or `SYNC_RECEIVE`.
`timeOut`	Specifies the time (in milliseconds) to wait for an EIS to run the specified interaction.

The following is an InteractionSpec sample:

AttuInteractionSpec iSpeq = new AttuInteractionSpec("query", javax.resource.cci.InteractionSpec.SYNC_RECEIVE, 60);javax.resource.cci.RecordFactory rf = new AttuRecordFactory(con, mcf.getLogger());
javax.resource.cci.MappedRecord queryRecord = rf.createMappedRecord("query"), queryRecord.put("##text", "select * from disam:nation"); javax.resource.cci.Record oRec = interaction.execute(iSpec, queryRecord);

Invoke the execute method on the interaction to initiate a call to the EIS. Pass any data for the interaction as input and output records.
Once the interactions have been processed, close the Interaction and Connection objects.

Integrating the J2CA 1.5 CICS Queue Adapter for Inbound

This section includes the following topics:

Configuring the J2CA 1.5 CICS Queue Adapter for Inbound
Using the CCI API to Develop Message Endpoint Applications

Configuring the J2CA 1.5 CICS Queue Adapter for Inbound

The provider of the endpoint must supply the following information in the endpoint deployment descriptor file, called ejb-jar.xml:

The properties of the ActivationSpec class of the CICS Queue adapter
The type of message listener implemented in the endpoint

The orion-ejb.xml file must provide the name of the resource adapter.

OC4J searches the deployment descriptor of the resource adapter for the message listener type and sets the properties that are defined in the endpoint deployment descriptor file for the respective ActivationSpec class.

The resource adapter supports message listener types and ActivationSpec classes as follows:

Table 3-3 Message Listener Types and their ActivationSpec Classes

Message Listener Type	ActivationSpec Class
`javax.resource.cci.MessageListener`	`com.attunity.adapter.AttuActivationSpec`
`oracle.tip.adapter.api.OracleMessageListener`	`com.attunity.adapter.AttuOracleActivationSpec`

Example 3-1 Endpoint Deployment Descriptor (ejb-jar.xml)

<ejb-jar>
 <display-name>AttuMDB1</display-name>
   <enterprise-beans>
   <message-driven>
      <display-name>Attu Test Receiver Bean</display-name>
      <ejb-name>AttuTestReceiverBean</ejb-name>
      <ejb-class>attutestreceiverbean.AttuTestReceiverBean</ejb-class>
      <messaging-type>javax.resource.cci.MessageListener</messaging-type>
      <transaction-type>Container</transaction-type>
      <activation-config>
        <activation-config-property>
          <activation-config-property-name>userName</activation-config-              property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>password</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>firewallProtocol</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>connectTimeout</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>encryptionProtocol</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>encryptionKeyName</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>encryptionKeyValue</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>workspace</activation-config-               property-name>
          <activation-config-property-value>YTEST</activation-config-               property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>portNumber</activation-config-              property-name>
          <activation-config-property-value>4820</activation-config-              property-value> 
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>useNamespace</activation-config-              property-name>
          <activation-config-property-value>true</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>networkXMLProtocol</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>idleTimeout</activation-config-               property-name>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>messagesInBatch</activation-config-              property-name>
          <activation-config-property-value>1</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>support2PC</activation-config-              property-name>
          <activation-config-property-value>true</activation-config-              property-value> 
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>waitTime</activation-config-              property-name>
          <activation-config-property-value>5</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>retryInterval</activation-config-              property-name>
          <activation-config-property-value>10</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>eisName</activation-config-              property-name>
          <activation-config-property-value>QVREAD</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>serverName</activation-config-              property-name>
          <activation-config-property-value>mvs5</activation-config-              property-value>
        </activation-config-property>
        <activation-config-property>
          <activation-config-property-name>exposeEventStreamMetadata</activation-              config-property-name>
          <activation-config-property-value>true</activation-config-              property-value>
        </activation-config-property>
     </activation-config>
     </message-driven>
   </enterprise-beans>
   <assembly-descriptor>
   <!-- NotSupported, Supports, Required, RequiresNew, Mandatory or Never  -->
    <container-transaction>
      <method>
        <ejb-name>
          AttuTestReceiverBean
        </ejb-name>
        <method-name>
          onMessage
        </method-name>
        <method-params>
        <method-param>javax.resource.cci.Record</method-param>
        </method-params>
      </method>
      <trans-attribute>
        Required
      </trans-attribute>
    </container-transaction>
    </assembly-descriptor>
</ejb-jar>

The following table lists the properties that are relevant for inbound interactions.

Table 3-4 OC4J Connection Properties for Inbound Interactions

Property	Description
`eisName`	Required. Sets the name of the adapter to use. The adapter is defined in Oracle Connect server using Oracle Studio.
`serverName`	Required. Sets the TCP/IP address or host name where the Oracle Connect daemon is running.
`messagesInBatch`	Optional. Specifies the maximum number of messages that can be moved to an endpoint in batch. The default is set to 1.
`support2PC`	Optional. Enables 2PC transaction support. The default is set to `False`. Set to `true` or `false`, according to the value of the `transaction support` property of the corresponding event.
`waitTime`	Optional. Defines the maximum time (in seconds) for an empty transaction duration, and for the CICS adapter to return a "no messages" response (which will cause the current transaction to close). The default is set to 30 seconds.
`retryInterval`	Optional. Defines the sleep time after any detected problem before restarting inbound activity. The default is set to 15 seconds.
`workspace`	Optional. Specifies the name of an Oracle Connect server workspace to use. The default workspace is `Navigator`.
`portNumber`	Optional. Specifies the TCP/IP port where the Oracle Connect daemon is running on the server. The default port is `2551`.
`userName`	Optional. Specifies a user who can access the Oracle Connect server. The user is defined in the Oracle Connect daemon configuration. See Also: "Daemon Security" and "WS Security" for details about users allowed to access an Oracle Connect server.
`password`	Optional. Specifies a valid password for the user.
`firewallProtocol`	Optional. Specifies the firewall protocol used: either `none` or `fixedNat` (the Nat protocol using a fixed address for the daemon). The default is set to `none`.
`connectTimeout`	Optional. Specifies the connection timeout in seconds. The default is 0, indicating that there is no connection timeout.
`encryptionProtocol`	Optional. Specifies the name of encryption protocol to use. The default is set to `null`. The RC4 protocol is supported.
`encryptionKeyName`	Optional. Specifies the name of the symmetric encryption key to use.
`encryptionKeyValue`	Optional. Specifies the value of the symmetric encryption key to use.
`useNamespace`	Optional. Set to `true` or `false`. When set to `true`, the metadata record schema uses namespaces.
`networkXMLProtocol`	Optional. Specifies how the XML is passed over the network. `Binary` or `Text` can be selected.
`exposeEventStreamMetadata`	Optional. When set to `true` (the default), the EventStream schema is sent to the endpoint.

Using the CCI API to Develop Message Endpoint Applications

The endpoint must implement the onMessage method. The record that the onMessage method receives is of the CoreDomRecord class, as shown in the following example.

Example 3-2 onMessage method

public Record onMessage(Record inMessage)throws javax.resource.ResourceException {

    …
    CoreDOMWriter domW;
    domW = new CoreDOMWriter(false);
    Element outEl = ((CoreDomRecord)inMessage).getDom();
    String xml = domW.toXMLString(outEl);
    …

 return null;

}

The adapter ignores the return values.

If the CICS Queue adapter describes two types of messages, employee and department, the XML data has the following input record structure:

When the exposeEventStreamMetadata property is set to true:

<eventStream>
  < EMPLOYEE>
     ...
  </ EMPLOYEE>
  <DEPARTMENT>
     ...
  </DEPARTMENT>
</eventStream>

When the exposeEventStreamMetadata property is set to false:

<getEventsResponse xmlns="noNamespace://QVREAD">
<event eventName="EMPLOYEE" timestamp="2005-08-23T15:23:18">
  < EMPLOYEE>
     ...
  </ EMPLOYEE>
</event>
<event eventName=" DEPARTMENT " timestamp="2005-08-23T15:23:18">
  <DEPARTMENT>
    ...
  </DEPARTMENT>
</event>
</getEventsResponse>