37 Using the Tuxedo Transport

This chapter provides an overview of the Tuxedo transport and describes how to use and configure it in your services. The Tuxedo transport lets you bring Tuxedo services into the Service Bus environment.

This chapter includes the following sections:

• Introduction to the Tuxedo Transport

• Configuring Oracle Tuxedo Connector

• Using Tuxedo Services from Service Bus

• Using Service Bus from Tuxedo

• Tuxedo Transport Buffer Transformation

• Tuxedo Transport Transaction Processing

37.1 Introduction to the Tuxedo Transport

Service Bus and Oracle Tuxedo can work together to use the services that each product offers. The Tuxedo transport provides secure, guaranteed, high performance, bi-directional access to a Tuxedo domain from Service Bus. The Tuxedo transport lets Tuxedo domains call services, as well as have services called, in a Tuxedo domain.

Services can either be outbound or inbound.

• When Service Bus uses services offered by Tuxedo, the Tuxedo transport facilitates access to those Tuxedo services. The term outbound refers to this business service scenario.

• When Tuxedo uses services offered by Service Bus, Tuxedo services can call Service Bus services as though they were another Tuxedo application. The term inbound refers to this proxy service scenario.

You configure the Tuxedo transport in either JDeveloper or the Oracle Service Bus Console. Specific parameters provide definitions for both proxy and business services. A basic WebLogic Tuxedo Connector (WTC) configuration with one local access point and one remote access point is required to enable configuration of the Tuxedo transport. Support for transactional and security contexts are available as well.

The following diagram summarizes the message handling processes.

Figure 37-1 WTC Message Handling

Description of "Figure 37-1 WTC Message Handling"

37.1.1 Capabilities of the Tuxedo Transport

The following capabilities are available in the native Tuxedo transport in Service Bus.

• First-class tier transport

  The native Tuxedo transport is fully integrated into Service Bus. You can configure, manage, and monitor both Tuxedo proxy services and Tuxedo businesses services.

• Bi-directional access

  Service Bus is an intermediary between SOAP, JMS, or other services and Tuxedo. The Tuxedo transport provides access to Tuxedo ATMI services as business services in Service Bus and allows Service Bus proxy services to be seen by Tuxedo as another ATMI service.

• Buffer transformation

  You can transform XML messages to Tuxedo buffer types and Tuxedo buffer types to XML. All standard Tuxedo buffer types are supported; transformation is automatic and transparent. For more information, see Tuxedo Transport Buffer Transformation.

• Transactional integrity

  The Tuxedo transport provides transactional integrity for inbound and outbound messages. You can call Tuxedo services in the context of a global transaction allowing Exactly Once quality of service (QoS). A Tuxedo application can start a transaction and call a Service Bus service, and the XA transaction context is carried through to Service Bus through the pipeline and finally to the destination transport. For more information, see Tuxedo Transport Transaction Processing.

• Service Accounts

  You can use service accounts with Tuxedo transport. Use “pass through” to use the sender’s credentials for business service invocation. Use static credentials to specify a username/password combination. You can also use credential mapping. Usernames/passwords must be known to the local Service Bus environment.

• Security propagation

  The security context established at the beginning of the pipeline, from either a Tuxedo client or a Service Bus client, is propagated to the other system. This means that an incoming SOAP over HTTP request to Service Bus that requires authentication is authenticated by Service Bus. As with transactions, this support is fully bi-directional, so a client authenticated to Tuxedo can make requests to Service Bus services without requiring authentication a second time.

• Encrypted network links

  You can encrypt the connections between Service Bus and Tuxedo through WTC configuration to ensure the security and privacy of communications between the two systems.

• Load balancing

  A single network connection is the only requirement to connect Service Bus to a Tuxedo domain. However, it might be necessary to support multiple connections in case of a machine or network failure. You can make multiple connections to a single domain or multiple domains for purposes of load balancing.

37.2 Configuring Oracle Tuxedo Connector

The Tuxedo transport enables access to Tuxedo services using WebLogic Tuxedo Connector (WTC). To use the Tuxedo transport, you must configure a basic WTC server including one local access point and one remote access point.

The following sections describe how to configure WTC:

• Before You Begin

• Configuring Oracle Tuxedo Connector

For information about WTC security, see "How to Configure Oracle WebLogic Tuxedo Connector to Provide Security between Oracle Tuxedo and Oracle WebLogic Server" in the Administering WebLogic Tuxedo Connector for Oracle WebLogic Server.

37.2.1 Before You Begin

Gather the following information about the Tuxedo application that Service Bus will use:

• The ID of the Tuxedo local access point.

• The network address of the Tuxedo local access point.

• The name of the exported Tuxedo service.

• Whether the service needs XML-to-FML and FML-to-XML conversion or VIEW-to-XML or XML-to-VIEW conversion.

  The example described in the following sections assumes the use of FML/FML32 buffer types.

• The ID of the access point that the Tuxedo domain gateway will use to refer to this Oracle Tuxedo Connector instance. This is referred to as the remote access point ID.)

• The network address that the Tuxedo domain gateway has defined for this Oracle Tuxedo Connector local access point.This is referred to as the remote network address.)

37.2.2 Configuring Oracle Tuxedo Connector

When you create or import Tuxedo business and proxy services in Service Bus, the service configuration includes WebLogic Tuxedo Connector configurations that appear as WebLogic Tuxedo Connector resources in the Oracle WebLogic Server Administration Console. Service Bus needs to keep the WebLogic Tuxedo Connector resources it uses in sync. Modifications to those WebLogic Tuxedo Connector resources in the Oracle WebLogic Server Administration Console can cause those resources to become out of sync with Service Bus, and a re-import of those services into Service Bus results in service activation failure.

Use the following guidelines for using and configuring WebLogic Tuxedo Connector resources in Service Bus:

• Do not modify WebLogic Tuxedo Connector resources in the Oracle WebLogic Server Console that you use in Service Bus proxy and business services. Modify the WebLogic Tuxedo Connector configuration in your Service Bus service configurations.

• If the WebLogic Tuxedo Connector configurations do become out of sync between your Tuxedo services in Service Bus and the Oracle WebLogic Server Console, the easiest way to get back in sync is to delete the WebLogic Tuxedo Connector resources in the Oracle WebLogic Server Console and re-configure or re-import the Tuxedo services in Service Bus.

37.3 Using Tuxedo Services from Service Bus

These sections describe how to use Tuxedo services from Service Bus.

• Configuring a Tuxedo-Based Business Service

• Load Balancing and Failover for Tuxedo-Based Business Services

• Error Handling for Tuxedo-Based Business Services

• Testing Your Configuration

37.3.1 Configuring a Tuxedo-Based Business Service

To use Tuxedo services from Service Bus, create a new business service that uses the Tuxedo transport in either JDeveloper or the Oracle Service Bus Console. For more information about creating and configuring business services, see Creating and Configuring Business Services. For information about the business service properties specific to the Tuxedo transport, see Configuring Business Services to Use the Tuxedo Transport.

When you create the business service, select tuxedo for the transport and select either Any XML Service or Messaging Service as the service type.

Note:

When editing the Transport tab of a Tuxedo transport business service in the Service Bus console, you may have to save and close the tab to propagate the changes you have made. For example, when adding an endpoint URI, you should save and close the tab, and then reopen the tab, to display the added endpoint URI on the Transport Details tab.

37.3.1.1 Business Service Endpoint URIs for Tuxedo Transports

When you create a Tuxedo-based business service, you specify the endpoint URIs for the service. Use the following URI format for outbound calls to Tuxedo services:

tuxedo:resourcename[/remotename]

Where:

• resourcename corresponds to a WTC Import service name.

• remotename corresponds to the service name exported by the remote Tuxedo domain. This is optional.

Use the following URI format for outbound calls to Tuxedo resources of type /Q:

tuxedo-queue:sendQspace/sendQname[/[rcvQspace:]/rcvQname][/failureQname]

Where:

• tuxedo-queue indicates that /Q calls will be made.

• sendQspace corresponds to the unique name of the queue space in the Tuxedo domain.

• sendQname corresponds to the queue name in the queue space in which requests will be stored.

• rcvQspace corresponds to the unique name of the queue space in the Tuxedo domain from which replies will be received. This is optional. If it is not specified, the sendQspace value is used.

• rcvQname corresponds to the name of the queue in the Tuxedo domain from which replies will be received. This is optional.

  Note:

  The rcvQspace and rcvQname properties are optional. If you specify neither value, the runtime returns immediately and does not expect a response. In this case, the Response Required option on the Tuxedo Transport Detail page is unavailable.

  If you specify either value and do not select the Response Required option, the values you specified are ignored.

• failureQname corresponds to the name of the queue in the Tuxedo domain where error messages will be stored. This value is also optional. If you specify neither rcvQspace nor rcvQname, but specify failureQname, the URI format is tuxedo-queue:sendQspace/sendQname//failureQname.

  Note:

  When a response is expected, it occurs in the same thread that sends the request.

The Tuxedo transport uses the resource name and remote name from the URI to dynamically create a WTC Import service. If you specify more than one URI, you must have unique resource names for each endpoint. If no remote name is specified, its value is the value of the resource name. If no remote name is entered or if the remote and resource name are the same, only one URI is allowed. This allows already defined WTC Import services to use WTC load balancing and failover.

Note:

If you configure two identical URIs, an error appears notifying you that the service name already exists.

37.3.2 Load Balancing and Failover for Tuxedo-Based Business Services

When specifying a business service and defining the endpoint URIs, you can use the Service Bus load balancing and failover capabilities by entering a remote name that is different from the resource name. In this case, you can define multiple service names and associate them to a service that is replicated across multiple remote domains. The resource name must be unique, but remote names do not have the same restriction.

37.3.3 Error Handling for Tuxedo-Based Business Services

You can configure Tuxedo-based business services to handle application and communication errors as follows:

• Application Errors: Specify whether to retry business service endpoint URIs when application errors occur. For more information, see Business Service Transport Protocol Configuration.

• Communication Errors: Specify whether business service URIs are taken offline when communication errors occur. For more information, see "Configuring Service Bus to Take Unresponsive Endpoint URIs Offline" in Administering Oracle Service Bus.

Table 37-1 describes the following Tuxedo exceptions and the type of Service Bus error they denote.

Table 37-1 Tuxedo Exceptions

Exception	Description
TPESVCFAIL	The service failed—an application error
TPENOENT	The requested entity does not exist—a communication error
TPEPERM	A permissions error has occurred—a communication error

37.3.4 Testing Your Configuration

Once you have configured Service Bus to work with Tuxedo, you can test the configuration using the Test Console in the Oracle Service Bus Console.

The following list of tasks summarizes the process of testing outbound usage of Tuxedo by Service Bus.

1. Build and start the Tuxedo servers.
2. Set up a Tuxedo service to call the Service Bus proxy service associated with the business service you just created.
3. In the Oracle Service Bus Console, click Activate to enable the Test Console.
4. Open the business service in its editor and click the Launch Test Console icon in the upper right corner.
5. Enter a payload in the Test Console. For more information, see Business Service Testing..
6. Click Execute.

   A response page displays the results of the service request.

37.4 Using Service Bus from Tuxedo

These sections describe how to use Service Bus services from Tuxedo.

• Configuring a Tuxedo-Based Proxy Service

• Testing Your Configuration

37.4.1 Configuring a Tuxedo-Based Proxy Service

To use Service Bus services from Tuxedo, configure a new proxy service in JDeveloper or the Oracle Service Bus Console. For more information about creating and configuring proxy services, see Creating and Configuring Proxy Services. For information about the proxy service properties specific to the Tuxedo transport, see Configuring Proxy Services to Use the Tuxedo Transport.

When you create the proxy service, select tuxedo for the transport and select either Any XML Service or Messaging Service as the service type. The endpoint URI is a service name that corresponds to the endpoint URI on the Tuxedo server where the service was deployed.

37.4.2 Testing Your Configuration

Once you have configured Tuxedo to work with Service Bus, you can test the service to verify that it is working correctly. If you are using XML-to-FML32 and FML32-to-XML conversions, test this configuration using the ud32 Tuxedo client program included with Tuxedo. If you are using FML conversions, you can use the ud client. ud32 reads input consisting of the text representation of FML buffers.

If you are not using XML-to-FML and FML-to-XML conversions, you must develop a test client program in Tuxedo to test this configuration.

37.5 Tuxedo Transport Buffer Transformation

Service Bus and Tuxedo can interoperate to use the services that each product offers, which includes buffer transformation. The Service Bus service type and the Tuxedo buffer type determine how transformation occurs.

The Tuxedo transport supports Any XML Service and Messaging Service service types in Service Bus.

• Any XML Services (Non SOAP): The messages to XML-based services are XML, but can be of any Tuxedo buffer type allowed by the service configuration.

• Messaging Services: Messaging services are those that can receive messages of one data type and respond with messages of a different data type. The supported data types include XML, MFL, text, and untyped binary.

The following sections explain how the Tuxedo transport handles buffer transformation.

• Buffer Transformation with the Any XML Service Type

• Buffer Transformation with the Messaging Service Type

37.5.1 Buffer Transformation with the Any XML Service Type

Table 37-2 shows the behavior of the Tuxedo transport depending on the Tuxedo buffer type when the service type is Any XML Service. For Any XML Service, the payload must be a well-formed XML document.

Table 37-2 Buffer Transformation for Any XML Service

Tuxedo Buffer Type	Tuxedo Transport Behavior
STRING	Passes the buffer as is.
CARRAY X_OCTET	Passes the buffer as is.
FML/FML32	Converts the buffer to and from XML using the configured field classes.
XML	Passes the buffer as is. Note: The Tuxedo application should not send NULL bytes when the Tuxedo buffer is XML.
VIEW/VIEW32 X_C_TYPE X_COMMON	Converts the buffer to and from XML using the configured view classes.
MBSTRING	Passes the buffer as is. Note: Encoding is determined by the encoding element of the MetaData of the message sent or received.

37.5.2 Buffer Transformation with the Messaging Service Type

Table 37-3 shows the behavior of the Tuxedo transport depending on the Tuxedo buffer type when the service type is Messaging Service. If None is specified in the subtype, the Tuxedo transport should not receive any buffer.

Table 37-3 Buffer Transformation for Messaging Service

Tuxedo Buffer Type	Binary Messaging Type	Text Messaging Type	MFL Messaging Type	XML Messaging Type
STRING	Passed as is	Passed as is	Passed as is, assuming the buffer is in a suitable format. If not, the transport returns an error.	XML
CARRAY	Passed as is	Not supported	Passed as is, assuming the buffer is in a suitable format. If not, the transport returns an error.	XML
FML/FML32	Passed as is	Not supported	Not supported	XML
XML	Passed as is	Passed as is	Not supported	XML
VIEW/VIEW32	Passed as is	Not supported	Not supported	XML
MBSTRING	Passed as is	Passed as is	Passed as is, assuming the buffer is in a suitable format. If not, the transport returns an error.	XML

The Tuxedo transport handles the buffer manipulation the same way as if the service was Any XML service type.

37.6 Tuxedo Transport Transaction Processing

Service Bus and Tuxedo can interoperate to use the services that each product offers, which often includes transaction processing. Tuxedo transport takes advantage of transactions or starts transactions in Service Bus.

The exception to this transaction support is when the inbound transport is Tuxedo with a transactional message and the outbound is request/response XA-JMS. In this case, Service Bus detects this exception and it results in a TPESYSTEM error.

The Tuxedo transport transactional behavior is driven by the Quality of Service (QoS) setting available at the message context level. For more information, see Quality of Service..

The following sections explain how the Tuxedo transport handles transactions.

• Buffer Transformation with the Any XML Service Type

• Outbound Tuxedo Service Transaction Processing

37.6.1 Inbound Tuxedo Service Transaction Processing

When a transactional context is received, the message going into the pipeline sets the QoS to Exactly Once, otherwise QoS is set to Best Effort. When a TransportException is caught before the reply is sent back to the client, the request aborts by throwing a TPESYSTEM exception and a transaction rollback results.

37.6.2 Outbound Tuxedo Service Transaction Processing

When the thread calling the business service has a transactional context, the Tuxedo transport behaves in the following manner:

• If QoS is set to Exactly Once, the Tuxedo transport automatically forwards the transactional context to the remote domain unless the endpoint is configured to suspend the transaction.

• If QoS is set to Best Effort, the Tuxedo transport suspends the transaction before making the call and resumes it after the call. This is equivalent to making an ATMI call with TPNOTRAN flag set.

When the thread calling the business service has no transaction associated, the Tuxedo call occurs non-transactionally, regardless of the QoS setting. In this case, it will correspond to a tpcall() or tpacall() with the TPNOTRAN flag set.

37.7 Tuxedo Transport Configuration Reference

This section lists and describes the properties you can configure when using the Tuxedo transport with proxy and business services.

• Configuring Proxy Services to Use the Tuxedo Transport

• Configuring Business Services to Use the Tuxedo Transport

37.7.1 Configuring Proxy Services to Use the Tuxedo Transport

The Transport Detail page of the Proxy Service Definition Editor provides the properties listed in the following table for you to configure the transport.

Table 37-4 Tuxedo Transport Properties for Proxy Services

Option	To create or edit...
Field Table Classes	Enter the name of the class or classes describing the FML/FML32 buffer received. These are used for the FML/FML32-to-XML conversion routines to map field names to element names. This is a space separated list of fully qualified class names.
View Classes	Enter the name of the class or classes describing the VIEW/VIEW32 buffer received or sent. These are used for the VIEW-to-XML or VIEW32-to-XML conversion routines to map field names to element names. This is a list of fully qualified class names separated by spaces. X_C_TYPE and X_COMMON Tuxedo buffer types are handled in the same manner as VIEW/VIEW32 buffers. If an incoming request contains a VIEW, then the corresponding VIEW class should be specified in the Service Bus CLASSPATH.
Classes Jar	Select a JAR resource that contains a JAR file with the FML/FML32 or VIEW/VIEW32 classes necessary for this endpoint operation. If you are working in the Oracle Service Bus Console, you must create the JAR resource in the console before you can select it. For more information, see How to Add JAR Files.
Local Access Point	Select a local access point from the list that is associated with the export. The list contains local access points configured in WebLogic Tuxedo Connector (WTC). A proxy service cannot be created if there is not an associated local access point. If no local access points exist or to create a new one, select New. Enter the corresponding Local Access Point Name and Local Network Address in the adjacent fields. Upon validation of the endpoint, the access point is added to the WTC configuration for each WTC server. If no WTC server exists, one is created. You can enter an existing access point name after selecting the New option. This causes the existing information to be updated with the new parameters. You can change only the host name and port number.
Remote Access Point	Select a remote access point from the list to be associated with the newly created local access point. To create a new access point, select New. Enter the corresponding Access Point Name and Network Address in the adjacent fields. This field appears only when you select New in the Local Access Point field. You can enter an existing access point name after selecting the New option. This causes the existing information to be updated with the new parameters. You can change only the host name and port number. The remote access point is also the authentication principal for the WTC connection for inbound requests. Optionally, you can create a user with the same access point ID in the default security realm to allow incoming calls. To do so, select Yes from the Create User? list. The password is randomly generated using a temporary variable to avoid security issues.
Reply Buffer Type	Select the type of buffer that the remote Tuxedo client will receive. This option is available only if the Response Required? field is selected.
Reply Buffer Subtype	Enter the buffer subtype with which to associate the reply buffer. This option is available only when the Response Required? option is selected and the Reply Buffer Type value is VIEW or VIEW32.
Response Required?	Select this check box if this service is expected to send a response. By default, this option is selected. This option is cleared and the unavailable if the service type is Messaging Service and the response message type is None.
Request Encoding	Specify a character set encoding for requests in Tuxedo transports.
Response Encoding	Specify a character set encoding for responses in Tuxedo transports.
Transformation Style	Specify the way you want FML/FML32 buffers to be represented in an XML document. Select one of the following: None: The order of fields may not be respected. This is the default selection. Ordered: The fields are presented with all their occurrences in the correct order. Ordered and Grouped: If the fields are logically structured as records, the fields are ordered by occurrence and grouped by record.

37.7.2 Configuring Business Services to Use the Tuxedo Transport

The Transport Detail page of the Business Service Definition Editor provides the properties listed in the following table for you to configure the transport.

Table 37-5 Tuxedo Transport Properties for Business Services

Property	Description
Field table Classes	Enter the name of the classes describing the FML/FML32 buffer received. These are used for the FML/FML32-to-XML conversion routines to map field names to element names. This is a space separated list of fully qualified class names.
View Classes	Enter the name of the class or classes describing the VIEW/VIEW32 buffer received or sent. These are used for the VIEW-to-XML or VIEW32-to-XML conversion routines to map field names to element names. This is a space separated list of fully qualified class names.
Classes Jar	Select a JAR Resource that contains a JAR file with the FML/FML32 or VIEW/VIEW32 classes necessary for this endpoint operation. If you are working in the Oracle Service Bus Console, you must create the JAR resource in the console before you can select it. For more information, see How to Add JAR Files.
Remote Access Point(s)	Select a remote access point from the list of available options. The list contains remote access points configured in WTC. A business service cannot be created if there is no associated remote access point. If no remote access points exist or to create a new one, select New. Enter the corresponding Access Point Name and Network Address in the adjacent fields. Upon validation of the endpoint, the access point is added to the WTC configuration for each WTC server. If no WTC server exists, one is created. You can enter an existing access point name after selecting the New option. This causes the existing information to be updated with the new parameters. You can change only the host name and port number. If more than one URI is specified, there is one remote access point field per URI and the URI displays for informative purposes. If more than one URI exists, each requires a different remote access point. If the URI specified already corresponds to an existing WTC resource, the corresponding remote access point displays, but cannot be modified.
Local Access Point(s)	Select a local access point to be associated with the newly created remote access point. To create a new access point, select New. Enter the corresponding Local Access Point Name and Local Network Address in the adjacent fields. This field appears only when you select New in the Remote Access Point field. Note: Access points are not deleted by the transport when the endpoints are removed, since they may be used by multiple endpoints. To remove access points, use the Oracle WebLogic Server Administration Console.
Request Buffer Type	Select the type of buffer that the remote Tuxedo service will receive.
Request Buffer Subtype	Enter the buffer subtype with which to associate the request buffer. This option is enabled if the previous Request Buffer Type value is VIEW or VIEW32.
Response Required?	Select this check box to indicate a bidirectional call. If this is not selected, the underlying tpcall is invoked with TPNOREPLY flag, and a null response is posted asynchronously.
Suspend Transaction?	Select this check box to suspend the transaction, if it exists. This is useful when the remote service does not support transactions. When making calls to Tuxedo resources of the type /Q, use the Suspend Transaction option whether or not you expect a reply. A successful return from a one-way call means that a message has been successfully queued. Note: Tuxedo transports to /Q mode endpoints are considered asynchronous transactional if the Suspend Transaction option is not selected. This prevents deadlocks. In /Q mode, when an endpoint expects a reply, multiple threads on multiple Managed Servers may reply using the same destination. Therefore, when a reply is expected, a unique correlation ID is sent along with the request. The dequeue operation then waits for the message containing that correlation ID. Correlation IDs are composed in the same manner as those used by JMS transports in similar situations.
Request Encoding	Specify a character set encoding for requests.
Response Encoding	Specify a character set encoding for responses.
Timeout	Specify the maximum amount of time (in seconds) that the transport runtime waits for replies. This must be an integer greater than or equal to 0. If this is not specified or is set to zero (default), replies will time out at BLOCKTIME, the maximum number of seconds that the local Tuxedo access point allows for a blocking call. At runtime, replies exceeding the timeout value are ignored and an error message with a TPETIME exception is returned. This field is only available for request/response services, and not for m/Q or one-way endpoints. If the outbound call is part of a transaction, the timeout value is ignored. Note: The WTC BLOCKTIME value takes precedence if it is less than the timeout value.
Transformation Style	Select one of the following methods of ordering or grouping elements when FML or FML32 buffers are transformed into XML: None: (default) The order of fields may not be respected. Ordered: The fields are presented with all their occurrences in the correct order. Ordered and Grouped: If the fields are logically structured as records, the fields are ordered by occurrence and grouped by record.
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. Service Bus uses this Work Manager to asynchronously post a null reply in the case of a one-way invocation. For information about Work Managers, see: Using Work Managers with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server