6 Integrating OracleAS Adapters for Tuxedo with OC4J

This section includes the following topics:

• Overview of OC4J Functionality

• Integrating the Tuxedo Adapter for Outbound

• Integrating the Tuxedo Queue Inbound Adapter

• Integrating the J2CA Tuxedo Gateway Synchronous Inbound Adapter

Overview of OC4J Functionality

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 J2EE specific containers, APIs, and services. OC4J supports the J2CA 1.5 standards.

J2CA defines standard Java interfaces for simplifying the integration of applications with the EIS. OracleAS adapters are deployed as resource adapters 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 (such as security and transaction).

Message inflow, which refers to inbound communications from an EIS to the application server (see Configuring the Tuxedo Queue Inbound Adapter).

See Also:

Oracle Application Server Adapter Concepts Guide, Oracle Application Server Containers for J2EE User's Guide, Oracle Application Server Containers for J2EE Services Guide, and Oracle Application Server Containers for J2EE Security Guide.

Integrating the Tuxedo Adapter for Outbound

This section includes the following topics:

• Configuring the Tuxedo Adapter for Outbound

• Using the CCI API to Develop Applications

Configuring the Tuxedo Adapter for Outbound

Deploy the Oracle Connect Legacy Adapter RAR into the OC4J server with the name jca-legacy-adapter.

Create the appropriate connection factories in the OC4J Enterprise Manager.

Table 6-1 provides a description of the connection factory properties.

Table 6-1 OC4J Connection Properties for Outbound Interactions

Property	Description
eisName	Required. Sets the name of the adapter to use. The adapter is defined in the Oracle Connect server using Oracle Studio, as described in Setting up the Tuxedo OracleAS Adapter.
serverName	Required. Enter the name of the server with the TCP/IP address or host name where the Oracle Connect daemon is running. See Also: Advanced Tuning of the Daemon for details about the daemon.
workspace	Optional. Specifies the name of an Oracle Connect server workspace to use. The default workspace is Navigator. See Also: Workspaces for details about workspaces.
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 Workspace 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 RC4. If the value of the property is not defined, the RC4 protocol is used.
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	For outbound interactions only. When set to true, the XA APIs are internally converted to local transaction APIs. The default is set to false.
useNamespace	Optional. Set to true or false. When set to true, the metadata record schema uses namespaces.
exposeEventStreamMetadata	Optional. When set to true, standard XSD schema is used for the Tuxedo/Q adapter inbound events metadata. When false, the native schema is used.

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 Tuxedo resource adapter:

1. Select a ConnectionFactory object for the Tuxedo adapter.

2. Create a Connection object using the selected ConnectionFactory. A Connection is a handle to the underlying network connection to the EIS, which is identified by the serverName property.

3. 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 6-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);
   

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

5. Once the interactions have been processed, close the Interaction and Connection objects.

Integrating the Tuxedo Queue Inbound Adapter

This section includes the following topics:

• Configuring the Tuxedo Queue Inbound Adapter

• Using the CCI API to Develop Message Endpoint Applications

Configuring the Tuxedo Queue Inbound Adapter

The Tuxedo Queue Inbound Adapter supports the standard Java message listener interface. When using the standard Java message listener interface, the Tuxedo adapter sends the CoreDomRecord instance to the endpoint onMessage method.

Table 6-3 Message Listener Type and its ActivationSpec Class

Message Listener Interface	ActivationSpec Class	Record Type
javax.resource.cci.MessageListener	com.oracle.adapter.AttuActivationSpec	com.atunity.adapter.core.CoreDomRecord

The properties listed in the table below are defined on the supported activationSpec class.

Table 6-4 OC4J Connection Properties for Queue Inbound Processes

Property	Description
eisName	Required. Sets the name of the adapter to use. The adapter is defined in the Oracle Connect server using Oracle Studio, as described in Setting up the Tuxedo Queue OracleAS Adapter.
messagesInBatch	Specifies the maximum number of messages that can be moved to an endpoint in batch. The default is set to 50.
support2PC	Enables global transaction support, where applicable. The default is set to False. Do not set to true.
waitTime	Defines the maximum time (in seconds) for an empty transaction duration, and for the Tuxedo adapter to return a "no messages" response (which will cause the current transaction to close). The default is set to 30 seconds.
retryInterval	The amount of time the resource adapter waits if no events are found in the server before issuing the next request.The default is set to 15 seconds.
serverName	Required. Sets the TCP/IP address or host name where the Oracle Connect daemon is running. See Also: Advanced Tuning of the Daemon for details about the daemon.
workspace	Optional. Specifies the name of an Oracle Connect server workspace to use. The default workspace is Navigator. See Also: Workspaces for details about workspaces.
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 Workspace 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.
exposeEventStreamMetadata	When set to true (the default), EventStream schema is sent to the endpoint.
connectionFactory	This property is used only for the BPEL or ESB environment. It specifies the connectionFactory class instance that contains the adapter connection properties. If any connection property is defined on both the activationSpec and the connectionFactory, the activationSpec value is used.

Using the CCI API to Develop Message Endpoint Applications

The endpoint uses the onMessage method. The following sample describes how the DOM is received from the CoreDomRecord class.

Example 6-1 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 Tuxedo 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>
  

Integrating the J2CA Tuxedo Gateway Synchronous Inbound Adapter

The chapter includes the following topic:

• Configuring the J2CA 1.5 Tuxedo Gateway Synchronous Inbound Adapter

Configuring the J2CA 1.5 Tuxedo Gateway Synchronous Inbound Adapter

The Tuxedo Gateway Synchronous Inbound Adapter supports the standard Java message listener interface. When using the standard Java message listener interface, the Tuxedo adapter sends and receives the AttuMappedRecord instance to/from the endpoint onMessage method.

Table 6-5 Message Listener Type and its ActivationSpec Class

Message Listener Interface	ActivationSpec Class	Record Type
javax.resource.cci.MessageListener	com.oracle.adapter.AttuGWActivationSpec	com.atunity.adapter.AttuMappedRecord

The properties listed in the table below are defined on both of the supported activationSpec classes except where noted otherwise.

Table 6-6 OC4J Connection Properties for Synchronous Inbound Processes

Property	Description
eisName	Required. Sets the name of the adapter to use. The adapter is defined in the Oracle Connect server using Oracle Studio, as described in Setting up the Tuxedo Gateway OracleAS Adapter.
serviceName	Required. Sets the name of the Tuxedo service. The service is defined as an interaction in the Oracle Connect Server using Oracle Studio.
waitTime	Defines the maximum time (in seconds) for an empty transaction duration, and for the Tuxedo adapter to return a "no messages" response (which will cause the current transaction to close). The default is set to 30 seconds.
retryInterval	The amount of time the resource adapter waits if no events are found in the server before issuing the next request. The default is 15 seconds.
endpointTimeout	Defines the timeout for endpoint thread activation (in seconds). The default is 600 seconds.
serverName	Required. Sets the TCP/IP address or host name where the Oracle Connect daemon is running. See Also: Advanced Tuning of the Daemon for details about the daemon.
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 Workspace 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.
connectionFactory	This property is used only for the BPEL or ESB environment. It specifies the connectionFactory class instance that contains the adapter connection properties. If any connection property is defined on both the activationSpec and the connectionFactory, the activationSpec value is used.