Oracle WebLogic Tuxedo Connector Administration Guide

      

How to Configure the Oracle Tuxedo Queuing Bridge

The following sections provide information on the Tuxedo Queuing Bridge functionality and configuration.

 


Overview of the Tuxedo Queuing Bridge

The Tuxedo Queuing Bridge is a part of the Oracle WebLogic Tuxedo Connector that provides a bi-directional JMS interface for your WebLogic Server applications to communicate to Tuxedo application environments. The transfer of messaging between the environments consists of JMS based messages containing text, Byte, or XML data streams used to invoke services on behalf of the client application. Figure 7-1 Interaction between WebLogic Server and Tuxedo with Queuing Bridge

Interaction between WebLogic Server and Tuxedo with Queuing Bridge

The following features determine the functionality of the Tuxedo Queuing Bridge:

 

How Tuxedo Queuing Bridge connects JMS with Tuxedo

All messages remain on the JMS queue until they have been acknowledged.

This section provides information on how JMS messages flow through the Tuxedo Queuing Bridge to Tuxedo queues and services.

  1. A JMS client, such as a web enabled WLPI application, places a message to be processed by Tuxedo on a JMS Queue. If this message was part of a transaction, the transaction commits.

  2. The message is removed from the JMS queue to be processed by the Tuxedo Queuing Bridge Converter.

  3. The Tuxedo Queuing Bridge Converter checks the message type and converts supported JMS types to JATMI buffer types.

    1. BytesMessage, TextMessage, XML are converted respectively to TypedCArray, TypedString, and TypedFML32. XML/FML translation is performed according to the TranslateFML attribute.

    2. Translation errors are sent to the wlsServerErrorDestination queue and the message is acknowledged in the JMS session.

    3. If an unrecognized JMS message is received: an appropriate error message is logged, the message is acknowledged, and then is discarded. This is considered a configuration error and the Tuxedo Queuing Bridge does not redirect the message to the error queue.

  4. The converted message is sent to Tuxedo using the T/Domain gateway.

    1. Messages with a redirect set to JmsQ2TuxQ use JATMI tpenqueue to deliver the message to a Tuxedo queue.

    2. Messages with a redirect set to JmsQ2TuxS use JATMI tpcall to deliver the message to a Tuxedo service.

  5. The tpenqueue is successful or tpcall is successful and the return results are placed in the replyQ. The message is acknowledged in the JMS session.

    If the tpenqueue or tpcall fails, Tuxedo Queuing Bridge delivers the message to the wlsServerErrorDestination queue and the message is acknowledged in the JMS session. If a wlsServerErrorDestination queue is not configured, the message is discarded and the Tuxedo Queuing Bridge processes the next available unacknowledged message.

 

How Tuxedo Queuing Bridge connects Tuxedo to JMS

Tuxedo Queuing Bridge uses a transaction to prevent the loss of messages while transferring messages from Tuxedo /Q to a JMS queue.

This section provides information on how Tuxedo messages flow through the Tuxedo Queuing Bridge to a JMS queue using the TuxQ2JmsQ redirect.

  1. Tuxedo Queuing Bridge polls the Tuxedo queue for available messages.

  2. A Tuxedo service places a message on a Tuxedo queue.

  3. Tuxedo Queuing Bridge uses JATMI tpdequeue to forward the message from Tuxedo and places the message in the JMS queue.

 

Tuxedo Queuing Bridge Limitations

The Tuxedo Queuing Bridge has the following limitations:

 


Configuring the Tuxedo Queuing Bridge

Tuxedo Queuing Bridge connectivity is determined by configuring the attributes in the Tuxedo Queuing Bridge and Redirections of your WTC Service. These attributes contain the necessary information to establish a connection to Tuxedo.

A complete Tuxedo Queuing Bridge configuration requires the following:

 

Dynamically Adding/Modifying Tuxedo Queuing Bridge

Dynamically adding/modifying Tuxedo Queuing Bridge is only possible if the Queuing Bridge is not activated. WTC can be activated, but the Queuing Bridge must not be activated. To shut down the WTC Queuing Bridge, you should deactivate the WTC server.

Typically, after a complete Tuxedo Queuing Bridge configuration exists and WTC is deployed, the Tuxedo Queuing Bridge is activated. After the Tuxedo Queuing Bridge is active, no additions or modifications to the configuration can occur without shutting the WTC Queuing Bridge down.

If WTC is activated and the Tuxedo Queuing Bridge is deactivated, the following additions and modifications are possible.

After completing the WTC Queuing Bridge configuration changes, activate the changes.

 

Tuxedo Queuing Bridge Instantiate

If, and only if, a complete WTC Queuing Bridge configuration is available at the time of activation will WTC start the Tuxedo Queuing Bridge.

If the WTC Queuing Bridge configuration is incomplete, then no Tuxedo Queuing Bridge instance is available.

 

Starting the Tuxedo Queuing Bridge

The Tuxedo Queuing Bridge is started as part of the WebLogic Server application environment if the Tuxedo Queuing Bridge and Redirections of your WTC Service are configured and the WTC Service is deployed to a target server. Any configuration condition that prevents the Tuxedo Queuing Bridge from starting results in an error being logged.

 

Error Logging

Oracle WebLogic Tuxedo Connector errors are logged to the WebLogic Server error log.

 


Tuxedo Queuing Bridge Connectivity

JMS message types: MapMessage, ObjectMessage, StreamMessage are not valid in Oracle WebLogic Tuxedo Connector. If one of these message types is received by the Tuxedo Queuing Bridge, a log entry is generated indicating this is an unsupported type and the message is discarded.

The Tuxedo Queuing Bridge establishes a one-way data connection between instances of a JMS queue and a Tuxedo /Q or a JMS queue and a Tuxedo service. This connection is represented by the Tuxedo Queuing Bridge and Redirections configurations of your WTC Service and provides a one-to-one connection between the identified points. Three types of connections can be configured. The following is a description of each of the connection types:

 


Example Connection Type Configurations

The following sections provide example configurations for each connection type.

 

Example JmsQ2TuxQ Configuration

The following section provides an example configuration in the config.xml file for reading from a JMS queue and sending to Tuxedo /Q.

<wtc-tbridge-redirect>

<direction>JmsQ2TuxQ</direction>
<name>redir0</name>
<reply-q>RPLYQ</reply-q>
<source-name>weblogic.jms.Jms2TuxQueue</source-name>
<target-access-point>TDOM2</target-access-point>
<target-name>STRING</target-name>
<target-qspace>QSPACE</target-qspace>
<translate-fml>NO</translate-fml>
</wtc-tbridge-redirect>

The following section describes the components of the JmsQ2TuxQ configuration:

The following table provides information on JmsQtoTuxQ message mapping:

From: JMS Message Type To: Oracle WebLogic Tuxedo Connector JATMI (Tuxedo)
BytesMessage TypedCArray
TextMessage (translateFML = NONE) TypedString
TextMessage (translateFML = FLAT) TypedFML32

 

Example TuxQ2JmsQ Configuration

The following section provides an example configuration in the config.xml file for reading from a Tuxedo /Q and sending to a JMS queue.

<wtc-tbridge-redirect>

<direction>TuxQ2JmsQ</direction>
<name>redir1</name>
<source-access-point>TDOM2</source-access-point>
<source-name>STRING</source-name>
<source-qspace>QSPACE</source-qspace>
<target-name>weblogic.jms.Tux2JmsQueue</target-name>
<translate-fml>NO</translate-fml>
</wtc-tbridge-redirect>

The following section describes the components of the TuxQ2JmsQ configuration:

The following table provides information on TuxQ2JmsQ message mapping:

From: Oracle WebLogic Tuxedo Connector JATMI (Tuxedo) To: JMS Message Type
TypedCArray BytesMessage
TypedString (translateFML = NO) TextMessage
TypedFML32 (translateFML = FLAT) TextMessage
TypedFML (translateFML = FLAT) TextMessage
TypedXML TextMessage

 

Example JmsQ2TuxS Configuration

For more information on XML/FML conversion, see Using FML with WebLogic Tuxedo Connector.

The following section provides an example configuration in the config.xml file for reading from a JMS queue, calling a Tuxedo service, and then writing the results back to a JMS queue.

<wtc-tbridge-redirect>

<direction>JmsQ2TuxS</direction>
<name>redir0</name>
<replyq>weblogic.jms.Tux2JmsQueue</replyq>
<source-name>weblogic.jms.Jms2TuxQueue</source-name>
<target-access-point>TDOM2</target-access-point>
<target-name>TOUPPER</target-name>
<translate-fml>FLAT</translate-fml>
</wtc-tbridge-redirect>

The following section describes the components of the JmsQ2TuxS configuration:

The following table provides information on the JMSQ2TuxX message mapping:

JMS Message Type Oracle WebLogic Tuxedo Connector JATMI (Tuxedo) JMS Message Type
BytesMessage TypedCArray BytesMessage
TextMessage (translateFML = NONE) TypedString TextMessage
TextMessage (translateFML = FLAT) TypedFML32 TextMessage

There may be scenarios where a reply from Tuxedo is returned and the translateFML parameter has no effect. Translation may occur automatically.

 


Priority Mapping

Oracle WebLogic Tuxedo Connector supports multiple Tuxedo Queuing Bridge redirect instances. In many environments, using multiple redirect instances significantly improves application scalability and performance. However, it does randomizes the order in which messages are processed. Although priority mapping does not guarantee ordering, it does provides a mechanism to react to messages based on an assigned importance. If the order of delivery must be guaranteed, use a single Tuxedo Queuing Bridge redirect instance.

Use Priority Mapping to map priorities between the JMS and Tuxedo.

This section provides a mechanism to map the priorities between the Tuxedo and JMS subsystems. There are two mapping directions:

Defaults are provided for all values, shown below in pairs of value:range.

JmstoTux- 0:1 | 1:12 | 2:23 | 3:34 | 4:45 | 5:56 | 6:67 | 7:78 | 8:89 | 9:100

TuxtoJms- 0:1-10|1:11-20|2: 21-30|3: 31-40|4: 41-50|5:51-60|6: 61-70|7:71-80|8:81-90|9:91-100

For this configuration, a JMS message of priority 7 is assigned a priority of 78 in the Tuxedo /Q. A Tuxedo /Q with a priority of 47 is assigned a JMS priority of 4.

 


Error Queues

When Tuxedo Queuing Bridge encounters a problem retrieving messages from Tuxedo Queue or JMS Queue after the retry interval:

 

WLS Error Destination

The WLS Error Destination queue is used if a JMS message cannot be properly delivered due to Tuxedo failure or a translation error.

 

Unsupported Message Types

If an unrecognized JMS message is received, an appropriate error message is logged and the message is discarded. This is considered a configuration error and the Tuxedo Queuing Bridge does not redirect the message to the error queue.

 

Tuxedo Error Queue

The Tuxedo Error Queue is the failure queue for the JATMI primitive tpdequeue during a TuxQ2JmsQ redirect.

 

Limitations

The Tuxedo Queuing Bridge error queues have the following limitations: