Configuring tBridge

 

The following sections provide information on tBridge functionality and configuration.

• Overview of the tBridge

• WebLogic Tuxedo Configuration XML File Configuration for tBridge

• tBridge Connectivity

• Example Connection Type Configurations

• Priority Mapping

• Error Queues

  Note: For more detailed reference information on the WebLogic Tuxedo Connector XML configuration file, elements and attributes, and the wtc_config.dtd, see The wtc_config.dtd.

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 parameters in the tBridge section of the WebLogic Tuxedo Connector XML configuration file. No additional application programming is required.

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

WebLogic Tuxedo Configuration XML File Configuration for tBridge

The WebLogic Tuxedo Connector tBridge connectivity is determined by the XML configuration file which contains 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 tBridge section of the XML configuration file is configured. 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

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 in the tBridge section of the configuration file as a <fromto> element. Each data connection provides a one-to-one connection between the identified points. Three types of connections can be configured. Each connection type is represented in the tBridge section of the configuration file as the value of the <direction> element. 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.

  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.

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.

<fromto>
<direction>JmsQ2TuxQ</direction>
<source>
<Name>weblogic.jms.Jms2TuxQueue</Name>
</source>
<target>
<AccessPoint>TDOM2</AccessPoint>
<Qspace>QSPACE</Qspace>
<Name>STRING</Name>
</target>
<replyQ>RPLYQ</replyQ>
<translateFML>NO</translateFML>
</fromto>

The following section describes the components of the JmsQ2TuxQ configuration:

• The <direction> connection typeJmsQ2TuxQ.

• The <source> <Name> keyword 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.

• The <target> keyword specifies the elements necessary to explicitly reference the destination.

  • The <AccessPoint> keyword specifies the name of the access point is TDOM2

  • The <Qspace> keyword specifies the name of the Qspace is Qspace.

  • The <Name> keyword specifies the name of the queue is STRING.

• The <replyQ> keyword specifies the name of a JMS reply queue is ReplyQ. Use of this queue causes tpenqueue to provide TMFORWARD functionality.

• The <translateFML> keyword NO specifies that no data translation is provided by the tBridge.

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

The following table provides information on JmsQtoTuxQ message mapping:

Example TuxQ2JmsQ Configuration

The following section provides example code for importing Tuxedo /Q into WebLogic Server.

<T_DM_IMPORT
     ResourceName="QSPACE"
     LocalAccessPoint="LDOM2"
     RemoteAccessPointList="MYLOCAL"
<TranTime>600</TranTime>
</T_DM_IMPORT>

Where

• ResourceName is the Tuxedo /Q described in the *DM_LOCAL_SERVICES section of your BDMCONFIG file.

• LocalAccessPoint is the name of your WebLogic Server domain described in the *DM_REMOTE_DOMAINS section of your BDMCONFIG file.

• RemoteAccessPointList is the name of your Tuxedo domain described in the *DM_LOCAL_DOMAINS section of your BDMCONFIG file.

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

<fromto>
<direction>TuxQ2JmsQ</direction>
<source>
<AccessPoint>TDOM2</AccessPoint>
<Qspace>QSPACE</Qspace>
<Name>STRING</Name>
</source>
<target>
<Name>weblogic.jms.Tux2JmsQueue</Name>
</target>
<translateFML>NO</translateFML>
</fromto>

The following section describes the components of the TuxQ2JmsQ configuration:

• The <direction> connection type is TuxQ2JmsQ.

• The <source> <Name> keyword specifies the name of the JMS queue to read is weblogic.jms.Tux2JmsQueue.

• The <target> specifies the elements necessary to explicitly reference the destination.

  • The <AccessPoint> keyword specifies the name of the access point is TDOM2.

  • The <Qspace> keyword specifies the name of the Qspace is Qspace.

  • The <Name> keyword specifies the name of the queue is STRING.

• The <translateFML> keyword NO specifies that no data translation is provided by the tBridge.

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

The following table provides information on TuxQ2JmsQ message mapping:

Example JmsQ2TuxS Configuration

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.

<fromto>
<direction>JmsQ2TuxS</direction>
<source>
<Name>weblogic.jms.Jms2TuxQueue</Name>
</source>
<target>
<AccessPoint>TDOM2</AccessPoint>
<Name>REVERSE_STRING</Name>
</target>
<replyQ>weblogic.jms.Tux2JmsQueue</replyQ>
<translateFML>FLAT</translateFML>
</fromto>

The following section describes the components of the JmsQ2TuxS configuration:

• The <direction> connection type is JmsQ2TuxS.

• The <source> <Name> keyword specifies the name of the JMS queue to read is weblogic.jms.Jms2TuxQueue.

• The <target> specifies the elements necessary to explicitly reference the destination.

  • The <AccessPoint> keyword specifies the name of the access point is TDOM2.

  • The <Name> keyword specifies the name of the queue is REVERSE_STRING.

• The <replyQ> keyword specifies the name of a JMS reply queue is ReplyQ.

• The <translateFML> keyword 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 REVERSE_STRING. The resulting message is then translated from FML into XML and placed on the weblogic.jms.Tux2JmsQueue.

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

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

The following table provides information on the JMSQ2TuxX message mapping:

Priority Mapping

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.

- Tthe 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

Note: tBridge does not take the priority when setting JMS priority for the message using setJMSPriority(), set to QueueSender using setPriority().

Example:

The following priorityMapping represents the default mapping:

<priorityMapping>

         <TuxtoJms>

            <pMap>

               <value>1-10</value>

               <range>0</range>

            </pMap>

            <pMap>

               <value>11-20</value>

               <range>1</range>

            </pMap>

            <pMap>

               <value>21-30</value>

               <range>2</range>

            </pMap>

            <pMap>

               <value>31-40</value>

               <range>3</range>

            </pMap>

            <pMap>

               <value>41-50</value>

               <range>4</range>

            </pMap>

            <pMap>

               <value>51-60</value>

               <range>5</range>

            </pMap>

            <pMap>

               <value>61-70</value>

               <range>6</range>

            </pMap>

            <pMap>

               <value>71-80</value>

               <range>7</range>

            </pMap>

            <pMap>

               <value>81-90</value>

               <range>8</range>

            </pMap>

            <pMap>

               <value>91-100</value>

               <range>9</range>

            </pMap>

     </TuxtoJms>

         <JmstoTux>

            <pMap>

               <value>0</value>

               <range>1</range>

            </pMap>

            <pMap>

               <value>1</value>

               <range>12</range>

            </pMap>

            <pMap>

               <value>2</value>

               <range>23</range>

            </pMap>

            <pMap>

               <value>3</value>

               <range>34</range>

            </pMap>

            <pMap>

               <value>4</value>

               <range>45</range>

            </pMap>

            <pMap>

               <value>5</value>

               <range>56</range>

            </pMap>

            <pMap>

               <value>6</value>

               <range>67</range>

            </pMap>

            <pMap>

               <value>7</value>

               <range>78</range>

            </pMap>

            <pMap>

               <value>8</value>

               <range>89</range>

            </pMap>

            <pMap>

               <value>9</value>

               <range>100</range>

            </pMap>

        </JmstoTux>

 </priorityMapping>

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 tpenqueue during a JMS to Tuxedo /Q operation.

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.