33 MQ Transport

This chapter provides an overview of the MQ transport and describes how to use and configure it in your services.

Oracle Service Bus supports access to IBM WebSphere MQ using the MQ Transport. This transport supports both inbound and outbound connectivity. MQ proxy services can receive messages from WebSphere MQ and MQ business services can route messages to WebSphere MQ.

This chapter includes the following sections:

33.1 Key Features

The following key features are supported for the MQ transport:

  • Inbound and outbound connectivity. MQ proxy services can receive messages from WebSphere MQ and MQ business services can route messages to WebSphere MQ.

  • Access to WebSphere MQ. For more information, see Section 33.8.1, "Adding MQ Client Libraries to Your Environment."

  • Sending and receiving messages of Any XML, Binary, XML, Text and MFL types.

  • Processing of all the MQMD (MQ message descriptor) headers. A message descriptor is an attribute representing a property of the message that is either being sent or received.

    For a list of MQ headers that can be configured for outbound response and inbound requests, see Section 33.8.5, "Transport Headers."

  • Support for distributed (XA) transactions using the WebLogic Transaction Manager.

  • TCP/IP and bindings mode for connecting to queue managers.

    Use the bindings mode to connect to WebSphere MQ that is located on the same physical computer as Oracle Service Bus. Use TCP/IP to connect to WebSphere MQ that does not reside on the same computer as Oracle Service Bus.

  • One-way and two-way SSL on inbound and outbound transport.

    SSL is supported only when TCP/IP is used to connect to WebSphere MQ from Oracle Service Bus.

33.2 Advantages of Using the MQ Transport

Using the MQ transport has the following advantages over using the WebSphere MQ JMS interface:

  • Faster connection to WebSphere MQ through the MQ transport than through the WebSphere MQ JMS interface.

  • Ability to read and generate MQ messages. Using the JMS interface, it is not possible to set certain headers.

  • Support for sending and receiving MQ receipt messages.

  • No explicit binding of MQ Connection Factory and MQ Queue to WebLogic's JNDI is required.

  • Configuration of resources like a JMS provider, outside of Oracle Service Bus, is not required.

  • Performance improvement because messages are sent directly using the transport instead of channeling them through the JMS transport.

33.3 Supported Service Types

The MQ transport is available for the Message Service and XML Service service types.

For more information, see Section 4.3, "Proxy Service Configuration" and Section 4.2, "Business Service Configuration."

33.4 Messaging Patterns

The Native MQ transport supports one-way and request-response messaging patterns for both inbound and outbound connectivity. By default, one-way messaging is supported. A proxy or business service supports request-response messaging when you set the Is Response Required option while configuring the service.

The inbound and outbound transports support the asynchronous request-response pattern using messageID or correlationID for correlation between the request and the response. You can set the response correlation pattern during service configuration. For more information, see "CorrelationID" and "MessageID" in Section 33.8.5, "Transport Headers."

The outbound transport provides an option to auto-generate the correlation ID / messageID or use the one specified by you in the message flow. Select the Auto-generate Correlation Value option, to indicate that the correlation ID / message ID should be auto-generated by the transport. If the option is not selected, the value specified by you in the message flow is used.

The outbound transport also lets you use dynamic queues for response correlation if you use dynamic queues in your MQ implementation.

If the correlation value (messageID / correlationID) is not auto-generated and if the Managed Server goes down, the remaining response messages may never get removed when the server is restarted. Oracle recommends that the Expiry header on the request is configured to a finite value and that the Report header contains the MQC.MQRO_PASS_DISCARD_AND_EXPIRY option.

The MQC.MQRO_PASS_DISCARD_AND_EXPIRY option serves as a directive to the receiving client that the message descriptor of the reply should inherit the Expiry header value of the request message. This ensures that the response messages are removed by the MQ server after the configured expiry period has elapsed. When the correlation value is automatically generated, the Oracle Service Bus server is responsible for cleaning up any remaining response messages.

The MQ transport supports local transactions but not remote transactions.

For more information about configuring Is Response Required, Response Correlation Pattern, Auto Generate Correlation Value for a service, see Section 33.8.3, "Configuring Proxy Services to Use the MQ Transport" and Section 33.8.4, "Configuring Business Services to Use the MQ Transport."

33.5 Environment Values

Environment values are certain predefined fields in the configuration data whose values are very likely to change when you move your configuration from one domain to another (for example, from test to production). For information about updating environment values, see "Finding and Replacing Environment Values" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus. The following sections provide a list of environment values for the Native MQ transport services and the MQ connection resource.

Services based on the MQ transport support the Work Manager (Inbound and Outbound) environment value.

MQ connections are sharable resources that can be reused across multiple MQ proxy and business services. MQ Connection resources provide the connection parameters required for connecting to an MQ queue manager. The MQ connection resource supports the following environment and operational values:

  • MQ Connection Host

  • MQ Connection Port

  • MQ Connection Queue Manager Name

  • MQ Connection Channel Name

  • MQ Connection Pool Size

  • MQ Connection Timeout

  • MQ Model Queue

  • MQ Version

  • XA Enabled

33.6 Quality of Service

When the inbound transport is MQ and the Quality of Service (QoS) on the outbound transport is exactly-once, the resultant QoS will be at-least-once. By default, the QoS on the outbound transport is exactly-once.

Note:

You must create error handling logic (including any retry logic) in the pipeline error handler. For information about configuring error handling, see Section 2.4.8, "Adding and Configuring Error Handlers in Message Flows."

When the outbound is request-response, the QoS is at-least-once only if the outbound transport is configured to support exactly-once QoS.

For more information about QoS in Oracle Service Bus messaging, see "Quality of Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

33.7 MQ Clusters and the MQ Transport

The cluster support in WebSphere MQ is that of store-and-forward messaging and not of load-balancing and fail over. The cluster queues in WebSphere MQ are created locally on one of the queue managers and shared with other cluster members that act as remote forwarders to the shared queue.

Requests from the MQ transport are load balanced by sending messages using the load balancing algorithm to the members of the cluster. However, the transport receives messages by accessing only the MQ server node that holds the reference to the local queue.

33.8 Using the MQ Transport

You can use the Oracle Service Bus MQ transport to enable MQ proxy services to get messages from WebSphere MQ and MQ business services to send messages to WebSphere MQ. This document describes how to add WebSphere MQ to your Oracle Service Bus environment, characteristics of the Oracle Service Bus MQ transport, and how to configure MQ proxy and business services.

This section contains the following topics:

33.8.1 Adding MQ Client Libraries to Your Environment

Oracle Service Bus is a client for IBM WebSphere MQ, and although Oracle Service Bus supports runtime server compatibility for supported versions of WebSphere MQ, these MQ libraries are not bundled with the Oracle Service Bus installer. You need to ensure that a supported version of the MQ client library, com.ibm.mq.jar, is available in your environment. For WebSphere MQ version support with Oracle Service Bus, see "Interoperability Scenarios and Considerations" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

For information about the system requirements for WebSphere MQ, see http://www-306.ibm.com/software/integration/wmq/requirements/index.html.

To add the MQ client libraries to your environment:

  1. Stop the domain server.

  2. From your WebSphere MQ installation, copy the com.ibm.mq.jar file to the DOMAIN_HOME/domain_name/lib directory.

  3. Restart the domain server.

If you use bindings mode to connect MQ Queue Manager located on the same computer as Oracle Service Bus, add <MQ_install_directory>/bin and <MQ_install_directory>/java/lib to the PATH environment variable.

33.8.2 MQ Connection Resources

MQ connections are sharable resources that can be reused across multiple MQ proxy and business services. MQ proxy and business services must connect to a MQ queue manager before accessing the MQ queue. MQ connection resources provide the connection parameters required for connecting to a MQ queue manager.

Each MQ connection resource has a connection pool. Multiple business services and proxy services using the same queue manager share a connection pool. Any business or proxy service using a given MQ connection resource to connect to a given queue manager uses the same connection pool that was created for that MQ connection resource.

For information about managing MQ connection resources, see Section 2.6.1, "Adding and Editing MQ Connections."

For information about queue managers, see http://www.redbooks.ibm.com/redbooks/SG247128/wwhelp/wwhimpl/java/html/wwhelp.htm.

33.8.2.1 Creating an MQ Connection Resource

To create an MQ connection resource: 

  1. In an Oracle Service Bus perspective, select File > New > Custom Resource. The Create a New MQ Connection Resource page appears.

  2. Configure the MQ connection resource using the parameters described in Table 33-1 below.

  3. Click Save.

The MQ connection resource is created. You can use it across proxy and business services that use the MQ transport.

33.8.2.2

The following table lists and describes the connection parameters you can configure when creating an MQ connection resource.

Table 33-1 MQ Connection Parameters

Property To create or edit...

Resource Name

Enter a unique name for this MQ Connection resource.

Follow the Section 2.1.1, "Resource Naming Restrictions" for naming guidance. Do not include spaces in the name.

Resource Description

Enter a description for the MQ Connection resource.

Connection Type

Select one of the following modes for connecting to the MQ queue manager:

  • tcp mode—Use TCP/IP to connect to a queue manager that does not reside on the same computer as Oracle Service Bus.

  • binding mode—Use the bindings mode to connect to a queue manager that is located on the same computer as Oracle Service Bus.

MQ Host Name

For tcp mode connections only:

Enter the host name of the MQ queue manager.

MQ Port Number

For tcp mode connections only:

Enter the port number of the MQ queue manager listener.

MQ Queue Manager Name

Enter the name of the MQ queue manager to which to connect.

Queue Manager CCSID

For tcp mode connections only:

The coded character set identifier (CCSID) to be used when establishing a connection. The CCSID is used mainly for internationalization support.

To learn more, see WebSphere MQ Fundamentals at http://www.redbooks.ibm.com/redbooks/SG247128/wwhelp/wwhimpl/java/html/wwhelp.htm.

MQ Queue Manager Channel Name

For tcp mode connections only:

Enter the queue manager server connection channel name.

SSL Required

For tcp mode connections:

Select the check box to use SSL for sending messages. Only server-side SSL is enabled unless the 2-way SSL Required option is also selected.

Cipher Suite

This option is available only when the SSL Required check box is selected.

Select the Cipher Suite algorithm to be used by SSL.

The Cipher Suite algorithm is used to encrypt and decrypt message communications between the WebSphere MQ server and the WebSphere MQ client. Thus a Cipher Suite algorithm must be specified when using SSL to communicate with a WebSphere MQ server.

2-way SSL Required

This option is available only when the SSL Required check box is selected.

Select the check box to enable both client-side and server-side SSL authentication. Clear the check box for 1-way SSL for only server-side authentication.

Reference to the Service Key Provider

If you selected 2-way SSL Required, you must provide a reference to the service key provider for obtaining the appropriate key store and trust store information. A service key provider contains Public Key Infrastructure (PKI) credentials that proxy services use for decrypting inbound SOAP messages and for outbound authentication and digital signatures.

Enter the path (project/folder) and name of a service key provider, or click Browse to select one from the Select Service Key Provider page.

For more information about using service providers, see "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Reference to the Static Service Account

For tcp mode connections only:

Required for user name and password authentication. Enter the path (project/folder) and name of a static service account, or click Browse to select service accounts from a browser.

WebSphere MQ Version

Select the WebSphere MQ version:

  • 5.3

  • 6.0

  • 7.0

Note: Versions 5.3 and 6.0 are no longer supported by IBM. These versions are deprecated in Oracle Service Bus.

MQ Connection Pool Size

Enter the number of MQ connections to be stored in the connection pool for reuse.

MQ Connection Timeout

Enter the time interval in seconds after which unused connections are destroyed. The default is 1800 seconds.

MQ Connection Max Wait

Enter the maximum amount of time (in milliseconds) to wait for a connection to become available. If a connection is not made within that time interval, Oracle Service Bus throws an exception. The default is 3000 milliseconds.

XA Enabled

Select this option if the transactions handled by this connection are distributed (XA) transactions.

For XA transactions, the MQ queue must be configured for persistence. If you are using version 5.3 or 6.0 (both deprecated), add the com.ibm.mqetclient.jar file to your classpath.


33.8.3 Configuring Proxy Services to Use the MQ Transport

During service configuration, select either Message service or XML service as the service type in the General Configuration page. For more information, see Section 33.3, "Supported Service Types" and Section 4.3, "Proxy Service Configuration."

When you create an MQ service, select the transport protocol as mq and specify the Endpoint URI in the Transport Configuration page. Specify the Endpoint URI in mq://local-queue-name?conn=mq-connection-resource-ref format where:

  • local-queue-name is the name of the local queue configured on the MQ server

  • mq-connection-resource-ref points to the location of the MQ connection resource

For example, if you create a MQ connection resource, mqConnection in the defaultMQ folder and the queue name is testQueue, the URI would be mq://testQueue?conn=defaultMQ/mqConnection

Note:

The Endpoint URI cannot contain spaces, so do not create MQ Connection resources or projects/folders with spaces in the names.

Configure the MQ transport for a proxy service with values as described in the following table:

Table 33-2 MQ Proxy Service Configuration

Option To create or edit...

Is Response Required

Select this option to specify that a response is expected after an outbound message is sent.

Response Correlation Pattern

This option is available only when the Is Response Required check box is selected.

Specify whether the response correlation pattern should be based on MessageID or CorrelationID.

MQ Response URI

This option is available only when the Is Response Required check box is selected.

The destination to which the response should be published. Enter a response URI in the same format as the endpoint URI: mq://<local-queue-name>?conn=<mq-connection-resource-ref>

Response Message Type

This option is available only when the Is Response Required check box is selected.

Select one of the following:

  • Bytes (for a stream of uninterpreted bytes)

  • Text (for text messages)

Transaction Timeout

Enter the amount of time in seconds to wait before timing out an XA transaction initiated by the proxy service. This property only applies to services using an MQ connection resource that is configured for XA transactions (that is, the XA Enabled option is selected for the MQ connection resource).

The default is 300 seconds.

Polling Interval

Enter an interval in milliseconds to wait between polling for messages. The default is 1000.

Poller Dispatch Policy

The dispatch policy to use for the poller threads.

Backout Threshold

Enter a value representing the number of times the pipeline should retry a message before redirecting the message to the queue specified in the Dead Letter URI field.

If you do not specify a value for this field, the message is redirected to the dead letter queue without attempting any retries.

MQ Dead Letter URI

Enter the URI of the dead letter queue to which request messages should be redirected after attempting the number of retries specified in the Backout Threshold field.

If you do not specify a value for this field, the message is returned to the queue and ignored by the MQ transport for each poll after retrying the number of times specified in the Backout Threshold field. The Dead Letter URI uses the same format as the EndPoint URI.

Endpoint URI 'GET' options

Enter the MQ GET message options from among the following:

  • MQC.MQGMO_ACCEPT_TRUNCATED_MSG

  • MQC.MQGMO_ALL_MSGS_AVAILABLE

  • MQC.MQGMO_BROWSE_FIRST

  • MQC.MQGMO_BROWSE_NEXT

  • MQC.MQGMO_COMPLETE_MSG

  • MQC.MQGMO_CONVERT

  • MQC.MQGMO_FAIL_IF_QUIESCING

  • MQC.MQGMO_LOCK

  • MQC.MQGMO_LOGICAL_ORDER

  • MQC.MQGMO_MARK_BROWSE_CO_OP

  • MQC.MQGMO_MARK_SKIP_BACKOUT

  • MQC.MQGMO_NO_SYNCPOINT

  • MQC.MQGMO_NONE

  • MQC.MQGMO_NO_WAIT

  • MQC.MQGMO_SYNCPOINT

  • MQC.MQGMO_SYNCPOINT_IF_PERSISTENT

  • MQC.MQGMO_UNLOCK

  • MQC.MQGMO_UNMARK_BROWSE_CO_OP

  • MQC.MQGMO_UNMARK_BROWSE_HANDLE

  • MQC.MQGMO_UNMARKED_BROWSE_MSG

  • MQC.MQGMO_VERSION_1

  • MQC.MQGMO_VERSION_2

  • MQC.MQGMO_VERSION_3

  • MQC.MQGMO_WAIT

You can use either "|" or "+" to separate multiple options. For example, you can specify the following:

MQC.MQGMO_ACCEPT_TRUNCATED_MSG | MQC.MQGMO_LOCK

The MQ GET message options are applied when reading a message from the inbound queue.

Process RFH2 Headers

Select this option to parse WebSphere MQ RFH2 headers from a message payload and automatically generate an RFH2Headers transport header containing the RFH2 data.

If you do not select this option, the payload is passed through as received.

Ignore Reply To Headers

Select this option to ignore the reply-to headers for the queue manager.

Worker Thread Dispatch Policy

Select the instance of Oracle 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.

For information about Work Managers, see:


For more information about configuring proxy services using MQ transport, see MQ Transport Configuration Page in Section 2.3, "Working with Proxy Services."

33.8.4 Configuring Business Services to Use the MQ Transport

During service configuration, select either Message service or XML service as the service type in the General Configuration page. For more information, see Section 4.2, "Business Service Configuration".

When you create an MQ service, select the transport protocol as mq and specify the Endpoint URI in the Transport Configuration page. Specify the Endpoint URI in mq://local-queue-name?conn=mq-connection-resource-ref format where

local-queue-name is the name of the local queue configured on the MQ server

mq-connection-resource-ref points to the location of the MQ connection resource

For example, if you create a MQ connection resource, mqConnection in the defaultMQ folder and the queue name is testQueue, the URI would be mq://testQueue?conn=defaultMQ/mqConnection.

Note:

The Endpoint URI cannot contain spaces, so do not create MQ Connection resources or projects/folders with spaces in the names.

To configure the MQ transport for a business service, specify the values as described in the following table:

Table 33-3 MQ Business Service Configuration

Option To create or edit...

Message Type

Select one of the following:

  • Bytes (for a stream of uninterpreted bytes)

  • Text (for text messages)

Is Response Required

Select this option to specify that a response is expected after an outbound message is sent.

Response Correlation Pattern

This option is available only when the Is Response Required check box is selected.

Specify whether the response correlation pattern should be based on:

  • MessageID

  • CorrelationID

  • Dynamic Queue – Select this option if your WebSphere MQ implementation uses dynamic queues for response correlation. The MQ transport supports only temporary dynamic queues.

Auto-generate Correlation Value

This option is available only when the Is Response Required check box is selected.

Select this check box to automatically generate a CorrelationID or MessageID.

Model Queue

For Dynamic Queue Response Correlation Pattern only. Enter the name of the model queue used to generate the dynamic queue.

MQ Response URI

This option is available only when the Is Response Required option is selected.

The destination to which the response should be published. Enter a response URI in the same format as the endpoint URI:

mq://local_queue_name?conn=mq_connection_resource

or, if you are using dynamic queues:

mq://dynamic_queue_prefix?conn=mq_connection_resource

The dynamic_queue_prefix, which is limited to 32 characters, is used to create the dynamic queue on the MQ server. The queue name becomes the prefix plus a unique ID. For example, if the dynamic_queue_prefix is example, the dynamic queue would be named something like example123129083821.

You can also use an asterisk (*) as a wildcard in the dynamic queue response URI. For example:

mq://dynamic_queue_prefix*?conn=mq_connection_resource

mq://dynamic_queue_prefix*

mq://*

If you do not provide a dynamic_queue_prefix in the URI, the transport uses the dynamic queue name generated by the MQ server. If you do not provide an explicit mq_connection_resource in the URI (best practice), the transport uses the mq_connection_resource from the endpoint URI.

For more detailed information, see "MQ Transport" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1117.

Response Timeout

This option is available only when the Is Response Required check box is selected.

Enter the number of seconds to wait for a response before dropping the connection. The default is 300.

Polling Interval

This option is available only when the Is Response Required check box is selected.

Enter a polling interval, in milliseconds. The default is 1000.

Poller Dispatch Policy

The dispatch policy to use for the poller threads.

Dynamic Queue Pooling

For Dynamic Queue Response Correlation Pattern only. Select this option if you want the service to use pooled connections to dynamic queues.

To use a separate connection pool for dynamic queues, consider configuring a dedicated MQ Connection resource for the dynamic queues.

Do not select this option to create a new dynamic queue instance on each request (and destroy the queue after the response).

Endpoint URI 'PUT' options

Enter the MQ PUT message options from among the following:

  • MQC.MQPMO_ALTERNATE_USER_AUTHORITY

  • MQC.MQPMO_DEFAULT_CONTEXT

  • MQC.MQPMO_FAIL_IF_QUIESCING

  • MQC.MQPMO_LOGICAL_ORDER

  • MQC.MQPMO_NEW_CORREL_ID

  • MQC.MQPMO_NEW_MSG_ID

  • MQC.MQPMO_NO_CONTEXT

  • MQC.MQPMO_NO_SYNCPOINT

  • MQC.MQPMO_NONE

  • MQC.MQPMO_PASS_ALL_CONTEXT

  • MQC.MQPMO_PASS_IDENTITY_CONTEXT

  • MQC.MQPMO_RESOLVE_LOCAL_Q

  • MQC.MQPMO_SET_ALL_CONTEXT

  • MQC.MQPMO_SET_IDENTITY_CONTEXT

  • MQC.MQPMO_SYNCPOINT

  • MQC.MQPMO_VERSION_1

  • MQC.MQPMO_VERSION_2

You can use either "|" or "+" to separate multiple options. For example, you can specify the following:

MQC.MQPMO_LOGICAL_ORDER | MQC.MQPMO_NEW_MSG_ID

The MQ PUT message options are applied when the message is placed in the outbound queue.

MQ Unrecognized Response URI

Enter the URI representing the queue to which unrecognized response messages should be sent. This setting is enabled only when the Auto-generate Correlation Value check box is selected.

If you do not specify a value for this field, unrecognized response messages are deleted.

Process RFH2 Headers

Select this option to parse WebSphere MQ RFH2 headers from a message payload and automatically generate an RFH2Headers transport header containing the RFH2 data.

If you do not select this option, the payload is passed through as received.

For information about how the MQ transport handles RFH2 headers, see Section 33.8.5.1.1, "About RFH2 Headers."

Worker Thread Dispatch Policy

Select the instance of Oracle 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.

For information about Work Managers, see:


For more information about configuring business services using MQ transport, see MQ Transport Configuration Page in Section 2.2, "Working with Business Services."

33.8.5 Transport Headers

The various headers used by the MQ transport are listed in Table 33-4. Most of the headers are common to both outbound requests and inbound response. The Reply To Queue Name, Reply To Queue Manager Name, User ID and Version headers can be edited only for the inbound response.

When you configure a proxy service, you can use a Transport Header action to set the header values in messages.

Table 33-4 Transport Headers

Header Description Inbound Response /Outbound Request

Accounting Token

Accounting token is part of the identity context of the message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Application ID Data

Application ID data is part of the identity context of the message. This value can be used to provide additional information about the message or its originator.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Application Origin Data

Data about the originating application. This value can be used by the application to provide additional information about the origin of the message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Backout Count

The number of times the message was returned by the MQ Queue, as part of a unit of work, and subsequently backed out.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Character Set

The coded character set identifier of character data in the application message data.

Inbound Transport Action: This field is used by the inbound transport to convert data in a specific representation. For request-response messaging, the characterSet header from the request message is copied to the response. When this header is not configured on the incoming request, default value of the MQC.MQCCSI_Q_MGR field is assumed.

Outbound Transport Action: This header can be set in the pipeline for the outbound transport. If this header value is not set, the default MQC.MQCCSI_Q_MGR value is assumed.

Both

Correlation ID

The correlation-id of the message that should be retrieved.

Inbound Transport Action: For correlationID-based response correlation pattern, the correlationID from the request is echoed on the response. The user can override the correlationID in the response pipeline.

Outbound Transport Action: When the Auto-generate correlationID option is selected during service configuration, the outbound transport will automatically generate a correlationID and overwrite the correlationID from the transport header. If this value is not specified, the correlationID specified in the pipeline is used.

For one-way messaging, the correlationID specified in the pipeline is used in the (outbound) request.

Both

Encoding

The representation used for numeric values in the application message data.

Inbound Transport Action: The inbound transport uses this header to interpret the incoming message data. If this header is not configured in the response pipeline, the default value of MQC.MQENC_NATIVE is used.

Outbound Transport Action: If this header is not set in the pipeline for the outbound transport, the default value of MQC.MQENC_NATIVE is used.

Both

Expiry

The expiry time (in tenths of a second) is set by the application that puts the message. After a message's expiry time has elapsed, it is eligible to be discarded by the queue manager.

Inbound Transport Action: For request-response messaging, the inbound transport copies the expiry header of the request to the response.

Outbound Transport Action: If the corresponding transport header is set in the pipeline, it is copied to the outbound request message.

Note: The report header will always contain the MQC.MQRO_PASS_DISCARD_AND_EXPIRY option (in addition to others). This option is a directive to the receiving client that the expiry time of the original message should be copied to the report or reply message.

Both

Feedback

The nature of the feedback report. This value is used with a message of type MQC.MQMT_REPORT to indicate the nature of the report.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Format

Format name of the message data. The format name is used by the sender of the message to indicate the nature of the data in the message to the receiver.

Inbound Transport Action: When the field is set to MQC.MQFMT_MD_EXTENSION, the inbound transport will read the extended MQMD object.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Group ID

The value that identifies the message group to which the physical message belongs.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Offset

In a segmented message, offset of data in the physical message from the start of the logical message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Original Length

Original length of a segmented message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Message Flags

Flags that control the segmentation and status of a message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Message ID

ID of the message to be retrieved.

Inbound Transport Action: If messageID is not specified in the response pipeline, the messageID header is set to MQC.MQMI_NONE.

For messageID-based correlation, the inbound transport copies the messageID from the request to the correlationID header of the response. MessageID-based correlation is assumed when the report header contains the MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID option.

Outbound Transport Action: When the Auto-generate messageID option is specified during service configuration, the outbound transport automatically generates the messageID and overwrites the messageID from the transport header. If this value is not specified, the messageID transport header is used.

For one-way messaging, the messageID specified in the pipeline is used in the outbound request. If this value is not specified, the messageID is automatically generated by the transport.

Both

Message Sequence Number

Sequence number of a logical message within group.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Message Type

Message type of the message.

Inbound Transport Action: The inbound transport reads and processes messages of any type including MQC.MQMT_REQUEST, MQC.MQMT_DATAGRAM, MQC.MQMT_REPLY and MQC.MQMT_REPORT. The inbound transport does not generate report messages.

Outbound Transport Action: The outbound transport generates messages of any type including MQC.MQMT_DATAGRAM, MQC.MQMT_REQUEST, MQC.MQMT_REPLY and MQC.MQMT_REPORT. When the messageType header is not configured in the pipeline, the transport generates messages of type MQC.MQMT_DATAGRAM when the messaging pattern is one-way and MQC.MQMT_REQUEST when the messaging pattern is request-reply.

Both

Persistence

The message persistence.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Priority

Priority of the message

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Put Application Name

The name of the application that put the message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Put Application Type

The type of the application that put the message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Put Date Time

The time and date when the message was put.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Both

Reply To Queue Name

The name of the queue to which a reply should be sent.

The application that issued the get request for the message can send MQC.MQFMT_REPLY and MQC.MQFMT_REPORT messages to this queue.

Inbound Transport Action: The inbound transport uses the replyToQueueName as the response queue name when this field is set. If this values is not set, the queue name is derived from the default destination URI.

Outbound Transport Action: In request/response message pattern, replyToQueueName set in the message flow is ignored. In one way message pattern, replyToQueueName set in the message flow is used in the outbound messages.

Inbound Response

Reply To Queue Manager Name

The name of the queue manager to which reply or report messages can be sent.

Inbound Transport Action: In request/response message pattern, if the inbound message replyToQueueManager header value does not match the configured value for the queue manager in the response URI, the response message is dropped and a transport error is logged.

Outbound Transport Action: In request/response message pattern, replyToQueueManager set in the message flow is ignored. In one way message pattern, replyToQueueManager set in the message flow is used in the outbound messages.

Inbound Response

Report

A report is a message about another message. This field enables the application sending the original message to specify which report messages are required, whether the application message data is to be included in them, and also how the message and correlation ID in the report or reply are to be set. It comprises one or more constants from the MQC class combined by means of the '+' or '|' operators.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline. For request-response messaging, this header can be configured in the response pipeline.

Outbound Transport Action: The transport always sets a combination of the following options in the report field.

Set MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID if messageID-based correlation pattern is used and MQC.MQRO_PASS_CORREL_ID if correlationID-based correlation pattern is used. Always set MQC.MQRO_PASS_DISCARD_AND_EXPIRY.

Note: These options are set in addition to the options specified on the corresponding transport header in the pipeline.

Both

User ID

It is part of the identity of the message and identifies the user who originated the message.

Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.

Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.

Inbound Response

Version

The version number of the message descriptor.

Inbound Transport Action: The inbound transport supports both version 1 and version 2 message descriptors.

Outbound Transport Action: By default, the outbound transport generates version 2 headers. However, this field can be overridden in the pipeline.

Inbound Response

RFH2Headers

The RFH2 headers in the payload when the Process RFH2 Headers option is set in the transport configuration. The RFH2Headers header is a String.

Inbound Transport Action: RFH2 headers are extracted from the MQ payload to construct the corresponding transport metadata header.

Outbound Transport Action: RFH2Headers data are parsed to extract the RFH2 headers, which are inserted (along with the content length for each header) into the outbound MQ payload.

Both


33.8.5.1 Configuring Transport Headers

You can configure the transport headers for both inbound and outbound requests in the Message Flow. For information about the transport headers related to the MQ transport, see Section 33.8.5, "Transport Headers."

In the message flow, use a Transport Header action to set the header values in messages. For more information, see Section 2.4.32, "Adding and Configuring Transport Headers Actions in Message Flows."

When the transport header is explicitly set in the message flow, this value overrides the header value except in the following scenarios:

  • For the outbound request-response pattern, when the Auto-generate Correlation Value option is selected for a outbound request with a request-response message pattern, the correlation ID is always generated even if this value is set in the message flow.

  • When the report header is set in the message flow, the combination of multiple directives associated with the report header are merged with the default directives.

  • When the replyToQueueManagerName or replyToQueueName headers are set in the message flow for an outbound request with a request/response message pattern, these values are ignored. Instead, these transport header values are derived from the response URI configured for the business service.

  • For the inbound response, when the value in the replyToQueueManagerName header does not match the queue manager name specified in the response URI, an error message is generated and the response message is not sent.

  • The replyToQueueName set in the inbound request header overrides the value configured in the reply to URI for the proxy service.

  • For a one-way business service, when the message type header is configured to be of type request in the message flow, the replyToQueueName header must be specified. If this value is not specified, an error is generated on the MQ server and the message is rolled back.

33.8.5.1.1 About RFH2 Headers

RFH2Header headers can contain multiple <RFH2Header> blocks, each of which can contain multiple folders. The MQ transport consolidates the blocks into a single RFH2 header containing a linear list of folders.

For example, the following blocks are consolidated into a single RFH2 header:

<RFH2Header>
    <mcd><Msd>jms_bytes</Msd></mcd>
</RFH2Header>
<RFH2Header>
    <usr><clientId>DASHBOARD</clientId></usr>
</RFH2Header>

33.8.6 Error Handling

You can configure MQ-transport business services to handle application and communications errors as follows:

33.8.7 Limitations of the MQ Transport

The following are the limitations of the MQ transport:

  • You cannot call a request-response proxy service based on MQ proxy service:

    • From a proxy service that has been configured with a route action or dynamic routing and routing table actions).

      Using the service callout action.

  • You cannot call a proxy service with a service callout where the target is a request-response proxy service based on MQ transport.

  • You cannot use an indirect call to a request-response MQ proxy service in the Oracle Service Bus Test Console.

33.9 Using the WebSphere JMS MQ Interface

The following sections outline how Oracle Service Bus connects to WebSphere MQ and presents an overview of some message types used in communication between WebSphere MQ and Oracle Service Bus.

33.9.1 Using the WebSphere MQ JMS Interface

Oracle Service Bus connects to WebSphere MQ through the WebSphere MQ JMS interface. That is, Oracle Service Bus is a WebSphere MQ JMS client.

The foreign JMS server in WLS specifies the initial context factory, connection factory, and queue to the WebSphere MQ server. For more information, see "Configuring Foreign Server Resources to Access Third-Party JMS Providers" in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

WebSphere MQ JMS supports two transport types:

  • BINDINGS

  • CLIENT

If the WebSphere MQ JMS client is running on the same physical machine as the queue manager, you can set the transport type to BINDINGS. Otherwise, you can use only the CLIENT type.

WebSphere MQ can interface with Oracle Service Bus in two ways:

  • Oracle Service Bus acts as the front-end of WebSphere MQ to accept service requests from other applications and converts them to WebSphere MQ requests. See Figure 33-1.

  • WebSphere MQ sends messages to other applications through Oracle Service Bus. See Figure 33-2.

Figure 33-1 Oracle Service Bus Front End

Description of Figure 33-1 follows
Description of "Figure 33-1 Oracle Service Bus Front End"

Figure 33-2 Messages Sent Through Oracle Service Bus

Description of Figure 33-2 follows
Description of "Figure 33-2 Messages Sent Through Oracle Service Bus"

33.9.2 Messaging Types

Oracle Service Bus supports the following messaging types:

33.9.2.1 Non-Persistent Messaging

If you decide to accept an unreliable delivery, such as some missing requests, you can use non-persistent messages where appropriate. WebSphere MQ logging and WebLogic JMS message persistence are only performed for persistent messages; therefore, the use of non-persistent messages eliminates any related I/O activity.

Note:

Non-persistent message throughput is usually limited by the processor speed of the computer. However, in case of a shortage of physical memory, the server system may consume CPU cycles on a paging I/O.

33.9.2.2 Non-XA Persistent Messaging

WebSphere MQ persistent message throughput is usually limited by the queue manager and the I/O latency writing to the log.

33.9.2.3 XA Messaging

To enable support for transactional (XA) access to queues, use the following:

  • BINDINGS to access the queue manager when Oracle Service Bus is co-located with IBM WebSphere MQ.

  • CLIENT when Oracle Service Bus and IBM WebSphere MQ are on different computers. However, with CLIENT, you need a special version of the IBM WebSphere MQ client that supports XA transactions, called the WebSphere MQ Extended Transaction Client.

    Tip:

    For the deployment descriptors to be set appropriately for XA capable resources (JMS, TUXEDO, EJB), you must set the XA attribute on the referenced connection factory before creating a proxy service.

33.9.3 Tuning WebSphere MQ

The following guidelines help you tune WebSphere MQ when you are working with Oracle Service Bus. For detailed WebSphere MQ information, refer to relevant WebSphere MQ documentation.

  • Use the BINDINGS transport type if Oracle Service Bus and the queue manager are deployed on the same computer.

  • If you need XA for only a small section of application requests, create a separate connection object and disable XA.

  • Distribute active logs across many volumes. If your system is required to handle high persistent message throughput, you must place the log files on a fast Direct Access Storage Device (DASD) with a minimum of contention from other data set usage. Ideally, you can allocate each of the active logs on separate, low-usage volumes.

  • To reduce buffer overflow, tune the buffer pools and pagesets. Buffer overflow results in flushing of the hard disk.

  • To avoid broken Oracle Service Bus JMS connections to MQ queues, increase the number of active channels to more than 100. By default, the number of active channels is 10.