bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

WebLogic Tuxedo Connector Administration Guide

How to Configure the tBridge Message Interface

The following sections provide information on tBridge functionality and configuration.

- Overview of the tBridge

- WTCServer MBean Configuration for tBridge

- tBridge Connectivity

- Example Connection Type Configurations

- Priority Mapping

- Error Queues

Overview of the tBridge

The tBridge is a part of the WebLogic Tuxedo Connector that provides a bi-directional JMS interface for your WebLogic Server applications 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.

The following features determine the functionality of the tBridge:

- Connectivity is determined by the configuration of the attributes in the WTCtBridgeGlobal and WTCtBridgeRedirect MBeans of a WTCServer MBean

- The tBridge uses Java Messaging Service (JMS) to provide an interface to a Tuxedo /Q or a Tuxedo service.

- The tBridge provides simple translation between XML and FML32 to provide connectivity to existing Tuxedo systems.

How tBridge connects JMS with Tuxedo

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

This section provides information on how JMS messages flow through the tBridge 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 tBridge Converter.

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

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

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

   - 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 tBridge does not redirect the message to the error queue.

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

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

   - 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, tBridge 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 tBridge processes the next available unacknowledged message.

How tBridge connects Tuxedo to JMS

Note: tBridge 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 tBridge to a JMS queue using the TuxQ2JmsQ redirect.

1. tBridge polls the Tuxedo queue for available messages.

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

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

   - If a message cannot be redirected to a JMS queue for any reason after the specified retries have been exhausted, the message is put into the tuxErrorDestination queue within the same queue space as the Tuxedo queue.

   - If the tBridge is not able to put the message into the tuxErrorDestination queue for any reason, an error is logged and the message is lost.

   - If the tuxErrorDestination queue is not specified, the message is lost.

tBridge Limitations

The tBridge has the following limitations:

- Transactions are not used when retrieving messages from the JMS location and placing them on the Tuxedo queue or invoking a Tuxedo service.

- tBridge is thread intensive. A thread is used to transport each message from JMS queue to Tuxedo. A polling thread is required to monitor the configured Tuxedo queue.

- The XML/FML translator is intended to construct simple message structures. For more information on XML to FML conversion see, FML32 Considerations.

WTCServer MBean Configuration for tBridge

The WebLogic Tuxedo Connector tBridge connectivity is determined by configuring the WTCtBridgeGlobal and WTCtBridgeRedirect MBeans which contain the necessary information to establish a connection to Tuxedo.

Starting the tBridge

The tBridge is started as part of the WebLogic Server application environment if the the WTCtBridgeGlobal and WTCtBridgeRedirect MBeans of a WTCServer MBean are configured and the WTCServer MBean is deployed to a target server. Any configuration condition that prevents the tBridge from starting results in an error being logged.

Error Logging

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

tBridge Connectivity

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

The tBridge 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 a WTCtBridgeRedirect MBean 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:

- JmsQ2TuxQ: Reads from a given JMS queue and transports the messages to the specified Tuxedo /Q.

- TuxQ2JmsQ: Reads from a Tuxedo /Q and transports the messages to JMS.

- JmsQ2TuxS: Reads from a given JMS queue, synchronously calls the specified Tuxedo service, and places the reply back onto a specified JMS queue.

Example Connection Type Configurations

The following sections provide example configurations for each connection type.

Example JmsQ2TuxQ Configuration

The following section provides example code for reading from a JMS queue and sending to Tuxedo /Q.

>     <WTCtBridgeRedirect
>          Direction="JmsQ2TuxQ"
>          Name="redir0"
>          ReplyQ="RPLYQ"
>          SourceName="weblogic.jms.Jms2TuxQueue"
>          TargetAccessPoint="TDOM2"
>          TargetName="STRING"
>          TargetQspace="QSPACE"
>          TranslateFML="NO"/>

The following section describes the components of the JmsQ2TuxQ configuration:

- The Direction connection type is JmsQ2TuxQ.

- SourceName specifies the name of the JMS queue to read is weblogic.jms.Jms2TuxQueue. The tBridge establishes a JMS client session to this queue using CLIENT_ACKNOWLEDGE semantics.

- TargetAccessPoint specifies the name of the access point is TDOM2.

- TargetQspace specifies the name of the Qspace is Qspace.

- TargetName specifies the name of the queue is STRING.

- ReplyQ specifies the name of a JMS reply queue is RPLYQ. Use of this queue causes tpenqueue to provide TMFORWARD functionality.

- TranslateFML set to NO specifies that no data translation is provided by the tBridge.

The following table provides information on JmsQtoTuxQ message mapping:

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

Example TuxQ2JmsQ Configuration

The following section provides example code for reading from a Tuxedo /Q and sending to a JMS queue.

>     <WTCtBridgeRedirect
>          Direction="TuxQ2JmsQ"
>          Name="redir1"
>          SourceAccessPoint="TDOM2"
>          SourceName="STRING"
>          SourceQspace="QSPACE"
>          TargetName="weblogic.jms.Tux2JmsQueue"
>          TranslateFML="NO"/>

The following section describes the components of the TuxQ2JmsQ configuration:

- The Direction connection type is TuxQ2JmsQ.

- TargetName specifies the name of the JMS queue to read is weblogic.jms.Tux2JmsQueue.

- SourceAccessPoint specifies the name of the access point is TDOM2.

- SourceQspace specifies the name of the Qspace is Qspace.

- SourceName specifies the name of the queue is STRING.

- TranslateFML set to NO specifies that no data translation is provided by the tBridge.

- TranslateFML set to Flat specifies that the data is translated from FML to XML by the tBridge.

The following table provides information on TuxQ2JmsQ message mapping:

From: 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

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

The following section provides example code for reading from a JMS queue, calling a Tuxedo service, and then writing the results back to a JMS queue.

>     <WTCtBridgeRedirect
>          Direction="JmsQ2TuxS"
>          Name="redir0"
>          ReplyQ="weblogic.jms.Tux2JmsQueue"
>          SourceName="weblogic.jms.Jms2TuxQueue"
>          TargetAccessPoint="TDOM2"
>          TargetName="TOUPPER"
>          TranslateFML="FLAT"/>

The following section describes the components of the JmsQ2TuxS configuration:

- The Direction connection type is JmsQ2TuxS.

- SourceName specifies the name of the JMS queue to read is weblogic.jms.Jms2TuxQueue.

- TargetAccessPoint specifies the name of the access point is TDOM2.

- TargetName specifies the name of the queue is TOUPPER.

- ReplyQ specifies the name of the JMS reply queue is weblogic.jms.Tux2JmsQueue.

- TranslateFML set to FLAT specifies that when a JMS message is received, the message is in XML format and is converted into the corresponding FML32 data buffer. The message is then placed in a tpcall with arguments TDOM2 and TOUPPER. The resulting message is then translated from FML32 into XML and placed on the weblogic.jms.Tux2JmsQueue.

The following table provides information on the JMSQ2TuxX message mapping:

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

Priority Mapping

WebLogic Tuxedo Connector supports multiple tBridge 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 tBridge redirect instance.

Use priorityMapping to map priorities between the JMS and Tuxedo.

- JMS has ten priorities (0 - 9).

- Tuxedo/Q has 100 priorities (1 - 100).

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

- JmstoTux

- TuxtoJms

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

- The value specifies the given input priority.

- The range specifies a sequential group of resulting output priorities.

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

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

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 tBridge encounters a problem retrieving messages from Tuxedo Queue or JMS Queue after the retry interval:

- The information is logged.

- The message is saved in the error queue if it is configured.

wlsServerErrorDestination

The wlsErrorDestination 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 tBridge does not redirect the message to the error queue.

tuxErrorQueue

The tuxErrorQueue is the failure queue for the JATMI primitive tpdequeue during a TuxQ2JmsQ redirect.

Limitations

The tBridge error queues have the following limitations:

- TuxErrorDestination can be specified only once. Any error queue name associated with the ErrorDestination implies that all the QSPACEs have the same error queue name available.

- When there is an error, the message is put back in the source QSPACE. Assuming the QSPACE is corrupted or full, subsequent messages would be lost.

- There is no way to specify to drop messages on error. All messages are received or none are received.

- Information about the error is only available in the server log.