33 Using the MQ Transport

This chapter provides an overview of the MQ transport and describes how to use and configure it in your services. The MQ transport provides access to IBM WebSphere MQ and supports both inbound and outbound connectivity.

This chapter includes the following sections:

33.1 Introduction to the MQ Transport

The MQ transport provides native connectivity between Service Bus components and IBM WebSphere MQ.

MQ proxy services can receive messages from WebSphere MQ and MQ business services can route messages to WebSphere MQ.

To learn more about WebSphere MQ fundamentals, Refer to the IBM WebSphere MQ documentation.

33.1.1 MQ Transport Features

The MQ transport provides Service Bus with the following features:

  • 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 How to Add MQ Client Libraries to Your Environment.

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

  • Processing of all the MQ message descriptor (MQMD) 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, see MQ Transport Headers.

  • TCP/IP and bindings mode for connecting to queue managers. TCP/IP mode connects to remote WebSphere MQ servers; bindings mode connects to a local WebSphere MQ.

  • One-way and two-way SSL on inbound and outbound transport (only when a TCP/IP connection is used).

33.1.2 MQ Transport Advantages

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.

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

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

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

33.1.3 Messaging Patterns

The MQ transport supports one-way and request-response messaging patterns for both inbound and outbound connectivity. The default pattern is one-way messaging. 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 MQ Transport Headers.

The outbound transport provides an option to auto-generate the correlation ID and messageID or to use the one specified by you in the pipeline. Select the Auto-generate Correlation Value option to indicate that the correlation ID and message ID should be auto-generated by the transport. When this option is not selected, Service Bus uses the value specified by you in the pipeline. If you use dynamic queues in your MQ implementation, you can use dynamic queues for response correlation in the outbound transport.

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 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 Configuring Proxy Services to Use the MQ Transport and Configuring Business Services to Use the MQ Transport.

33.1.4 MQ Connection Resources

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. You must create and configure an MQ connection resource in order to create an MQ-based proxy or business service. For more information, see Working with MQ Connections.

33.1.5 Quality of Service

When the inbound transport is MQ and the Quality of Service (QoS) on the outbound transport is exactly-once, the resulting QoS is 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 Adding Error Handlers in JDeveloper and Adding Error Handlers in the Console.

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 Service Bus messaging, see Quality of Service..

33.1.6 Multi-instance Queue Manager Support

The MQ Transport has been updated with Multi-instance Queue Manager support.

Introduced in IBM MQ 7, this feature allows the Queue Manager to use two hosts: the primary and a warn standby. If the primary host fails, the multi-instance queue manager restarts automatically on the standby server. The MQ transport tries to connect to Queue Manager on message arrival. At that moment, if the primary MQ instance is down, it checks for the next available instance and makes a fresh connection to the standby instance. As the storage is shared between the primary and all standby servers, messages are moved to the new, active instance. After the primary MQ server fails over to standby server, the standby server assumes the role of primary server.

See How to Create MQ Connections to create an MQ connection with Multi-instance Queue Manager support enabled.

33.1.7 MQ Clusters and the MQ Transport

Cluster support in WebSphere MQ is store-and-forward messaging and not 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.1.8 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 Service Bus Test Console.

33.1.9 Large Payload Rejection with the MQ Transport

Large messages over the default of 10 MB will be rejected for both inbound and outbound responses in a Reference Configuration domain. The default is valid for both XA and non-XA configurations.

If the threshold is exceeded in a Reference Configuration domain, the large payload is processed as follows:
  • Inbound: If the dead-letter queue is configured in the proxy service, the message is rejected and redirected to the given queue. If the dead-letter queue is not configured, the message is rejected and saved to disk in the $DOMAIN_HOME/mq/rejectedMessages/ folder.
  • Outbound response: The message is rejected and saved to disk in the $DOMAIN_HOME/mq/rejectedMessages/ folder.

The rejection limit is controlled by the -Dsoa.payload.threshold.kb parameter. The default is 10 MB.

33.2 Setting Up the Environment for the MQ Transport

Service Bus is a client for IBM WebSphere MQ, and although Service Bus supports runtime server compatibility for supported versions of WebSphere MQ, these MQ libraries are not installed with Service Bus.

The following libraries must be added to the domain library directory:
  • com.ibm.mq.commonservices.jar

  • com.ibm.mq.jar

  • com.ibm.mq.pcf.jar

  • com.ibm.mq.headers.jar

  • com.ibm.mq.jmqi.jar

  • com.ibm.mqjms.jar

Note:

If you upgrade from MQ 7.5 to MQ8 or MQ9, you must add the compatible client libraries to the domain library.

For WebSphere MQ version support with Service Bus, see Interoperability Scenarios and Considerationsin Administering Oracle Service Bus. For information about the system requirements for WebSphere MQ, see http://www-306.ibm.com/software/integration/wmq/requirements/index.html.

33.2.1 How to Add 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 Service Bus domain at DOMAIN_HOME/lib directory.
  3. Restart the domain server.

33.2.2 How to Configure Environment Variables

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

33.3 Working with MQ Connections

Before you can configure a proxy or business service to use the MQ transport, you need to create an MQ connection resource that defines the connection to the MQ server. MQ connections are sharable resources that can be reused across multiple MQ proxy and business services.

MQ proxy and business services must connect to an MQ queue manager before accessing an MQ queue. MQ connection resources provide the connection parameters required for connecting to an MQ queue manager.

Each MQ Connection resource has a connection pool. Every business or proxy service that uses the same MQ connection resource to get a connection to a queue manager uses the same connection pool that was created for that resource. Thus, multiple business services and proxy services can use the same queue manager and share a connection pool.

Some best practices to consider when using MQ connections:

  • A minimum of two different queue manager connections are needed for a global transaction.

  • With a large payload under an XA transaction, the MQ transport may have XA Exceptions with error code 106 or and MQ exception with error code 2102. If MQ messages are persistent, then increase the queue manager primary and secondary logs to a higher value.

33.3.1 How to Create MQ Connections

The option to create an MQ connection in Oracle Service Bus Console is only available after the MQ client library is added to the domain. In JDeveloper, you can create the connection without the libraries, but you need to libraries for the runtime.

Before you begin:

Follow the instructions under "Setting Up the Environment for the MQ Transport" to make the MQ client library available.

Make sure you have created any of the following resources you will need to create the MQ connection:

  • Service account

  • Service key provider

To create an MQ connection:

  1. Do one of the following:

    • For JDeveloper: In the Application Navigator, right-click the project or folder to contain the new MQ connection, point to New, and select MQ Connection.

    • For Oracle Service Bus Console: In the Project Navigator, right-click the project or folder to contain the new MQ connection, point to Create, and select Resources. Click Miscellaneous, click MQ Connection, and then click OK.

  2. Enter a unique name for this MQ connection, and an optional description.

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

  3. Click Create or Finish.

    The MQ Connection Definition Editor appears.

  4. In the Connection Type field, select one of the following modes for connecting to the MQ queue manager:

    • mqTcpModeType: Use TCP/IP to connect to a queue manager that does not reside on the same machine as Service Bus.

    • mqBindingModeType: Use the bindings mode to connect to a queue manager that is located on the same machine as Service Bus.

    The fields on the editor change based on your selection.

  5. Configure the following information about the MQ server:

    • Multi-instance Queue Manager Enabled: Select to enable multi-instance Queue Manager support. This is used for TCP mode connections only.

    • MQ Connection List: This field accepts a list of comma-separated MQ connections in the following format: host1:port1,host2:port2. This field is available only when the Multi-instance Queue Manager Enabled option is selected.

    • MQ Host Name: The host name of the MQ queue manager. This is used for TCP mode connections only. This field is available only when the Multi-instance Queue Manager Enabled option is not selected.

    • MQ Port Number: The port number of the MQ queue manager listener. This is used for TCP mode connections only. This field is available only when the Multi-instance Queue Manager Enabled option is not selected.

    • MQ Queue Manager Name: Enter the name of the MQ queue manager to which to connect.

    • MQ Queue Manager Channel Name: Enter the name of the queue manager server connection channel. This is used for TCP mode connections only.

    • XA Enabled: Select this option to enable XA support for the connection.

    • Queue Manager CCSID: The coded character set identifier (CCSID) to be used when establishing a connection. This is used for TCP mode connections only, and is mainly for internationalization support.

  6. To configure SSL support for TCP mode connections, do the following:

    1. Select the SSL Required check box to use SSL for sending messages. This enables service-side SSL authentication.

    2. In the Cipher Suite field, select the cipher suite algorithm to be used by SSL.

      The Cipher Suite algorithm is used to encrypt and decrypt message communications between the server and client.

    3. To enable both client-side and server-side SSL authentication, select the 2-way SSL Required check box.

    4. If you selected 2-way SSL, for the Reference to the Service Key Provider field, click the Browse icon to locate and select the service key provider to use.

  7. For the Reference to the Static Service Account field, click the Browse icon to locate and select the service account to use.

  8. In the MQ Version field, select the version of MQ server you are using.

  9. To configure the MQ connection, do the following:

    1. In the MQ Connection Pool Size field, enter the number of connections maintained by the connection pool.

    2. In the MQ Connection Timeout field, enter the time interval in seconds after which unused connections are destroyed. The default is 1800 seconds.

    3. In the MQ Connection Max Wait field, 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, Service Bus throws an exception. The default is 3000 milliseconds

    4. If the transactions handled by this connection are distributed (XA) transactions, select XA Enabled.

      Note that the 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.

  10. In the toolbar, click Save.

  11. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

33.3.2 How to Edit MQ Connections

Once you create an MQ connection, you can reconfigure its information.

To edit an MQ connection:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the MQ connection to edit.
  2. Right-click the MQ connection name, and select Open.
  3. Modify any of the fields described in How to Create MQ Connections. The online help provides more detailed descriptions.

    Note:

    If the MQ client library is version 8 or version 9, a change in XA functionality for any activated MQ connection that is associated with a running MQ service is not allowed. You must create a new MQ connection and associate the MQ service to it.

  4. When you are done making changes, click Save in the toolbar.
  5. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

33.3.3 How to Delete MQ Connections

Before you delete an MQ connection, make sure it is not currently being used by an MQ transport. If it is being used, remove it from the proxy or business service configuration before deleting it. You can delete the MQ connection even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

You can check for references and dependencies in both the console and JDeveloper. In the Oracle Service Bus Console, open the MQ connection in the MQ Connection Definition Editor and click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the MQ connection and select Explore Dependencies.

To delete an MQ connection:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the MQ connection to delete.
  2. Right-click the name of the MQ connection, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the MQ connection. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

33.3.4 How to Monitor an MQ Connection Pool

The MQ Transport connection pool has several parameters that you can configure to tune the pool performance. To determine the optimal pool settings, you can monitor the pool statistics.

You can enable a JMX MBean interface to monitor the following statistics for a connection pool:

  • ConnectionsInUseCount: Connections in use

  • ConnectionsInUseHighCount: Connections in use high

  • ConnectionUnavailableCount: Connection unavailable

  • MaxConnections: Max Connections

  • MaxIdleConnections: Max Idle Connections

  • PooledConnectionsCount: Pooled Connection

  • PooledConnectionsHighCount: Pooled Connections high

  • ResourceName: Resource name

  • WaitingForConnectionCount: Waiting for connection

  • WaitingForConnectionHighCount: Waiting for connection high

To enable the monitoring feature for MQ Connection resources using MQConnectionResourceRuntimeMBean:
  • Turn on the following flag in setDomainEnv.sh:
    "-Dalsb.transports.mq.connectionStatsEnabled=true"

You can then monitor the status of the MQ connections through the EM Console or a WLST scripting tool.

33.3.5 Improve Activation Performance

You can enable a system variable to improve activation performance.

In the setDomainEnv.sh file, enable the variable with this statement.

-Doracle.osb.mq.connection.xa.check.cache=on

If the MQ client library version is 8 or above, then be aware that a change in XA functionality for any activated MQ connection associated with a running MQ service is not allowed. You must create a new MQ connection and associate the MQ service to it. By default, there is a UI validation if the MQ client library version in 8 or version 9 for any change in XA functionality in MQ Connection.

33.4 MQ Transport Error Handling

You can configure MQ-transport business services to handle application and communications errors as described in this section.

  • Application errors: You can specify whether or not to retry business service endpoint URIs when application errors occur. For more information, see the online help provided for the Business Service Definition Editor for the Retry Application Errors field.

  • Communication errors: You can configure business service URIs to be taken offline when communication errors occur. For more information, see Managing and Monitoring Endpoint URIs for Business Servicesin Administering Oracle Service Bus.

33.5 Using the WebSphere JMS MQ Interface

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

33.5.1 Using the WebSphere MQ JMS Interface

Service Bus connects to WebSphere MQ through the WebSphere MQ JMS interface. That is, Service Bus is a WebSphere MQ JMS client. The foreign JMS server in Oracle WebLogic Server 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 Administering JMS Resources 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, set the transport type to BINDINGS. Otherwise, you can use only the CLIENT type.

WebSphere MQ can interface with Service Bus in two ways:

  • 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 Service Bus. See Figure 33-2.

Figure 33-1 Service Bus Front End

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

Figure 33-2 Messages Sent Through Service Bus

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

33.5.2 MQ Messaging Types

Service Bus supports the following messaging types:

33.5.2.1 Non-Persistent Messaging

If you choose 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 machine. However, in case of a shortage of physical memory, the server system may consume CPU cycles on a paging I/O.

Note:

If the MQ client library is version 8 or version 9, and you want non-persistent messages to persist or be rolled back for any issue, you can set an environmental variable in bin/setDomainEnv.sh as follows:

EXTRA_JAVA_PROPERTIES="${EXTRA_JAVA_PROPERTIES}
-Doracle.osb.mq.persistence.override=off"
export EXTRA_JAVA_PROPERTIES

Setting this variable tells Oracle Service Bus not to override the persistence value of the message and to always send the default JMS persistence value as 1 (persistent). Therefore, for any issue in message deilvery, an exception is thrown and the message is rolled back.

33.5.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.5.2.3 XA Messaging

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

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

  • CLIENT when Service Bus and IBM WebSphere MQ are on different machines. 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.5.3 Tuning WebSphere MQ

The following guidelines help you tune WebSphere MQ when you are working with Service Bus. For information specific to WebSphere MQ, see the relevant WebSphere MQ documentation.

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

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

33.6 MQ Transport Configuration Reference

Use the MQ transport in proxy services to retrieve messages from WebSphere MQ. Use the MQ transport in business services to send messages to WebSphere MQ.

This section describes how to add WebSphere MQ to your Service Bus environment, characteristics of the Service Bus MQ transport, and how to configure MQ proxy and business services.

33.6.1 MQ Transport Endpoint URIs

When you create an MQ proxy or business service, specify the endpoint URI in the in the following format:

mq://local-queue-name?conn=mq-connection-resource-ref

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 an MQ connection resource named 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, projects, or folders with spaces in the names.

Note:

All endpoint URIs must be either XA or non-XA. A combination of both is not allowed.

33.6.2 Configuring Proxy Services to Use the MQ Transport

Before you can configure a proxy service for the MQ Transport, you need to create the MQ Connection, as noted in How to Create MQ Connections. During service configuration, select either Message or Any XML as the service type. For more information, see Creating and Configuring Proxy Services.

Note:

A new validation has been added and this may cause the auto-generated pipeline to fail if a request only proxy service has been updated to request-response. You may need to update the configuration in the respective sbconfig.jar file accordingly.

The following table describes the properties you use to configure an MQ transport for a proxy service.

Table 33-1 MQ Transport Properties for Proxy Services

Property Description

Is Response Required

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

Response Correlation Pattern

Select either MessageID or CorrelationID to specify which ID the response correlation pattern should be based on.

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

MQ Response URI

Enter 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

Where:

  • local-queue-name is the name of the MQ queue where responses will be sent.

  • mq-connection-resource-ref is the path (project/folder) and name of the MQ connection resource; for example, default/my_MQconnection.

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

Note:

If the MQ client library version is 8 or version 9 with XA support and a response is required, then the endpoint URI and the response URI should both be either XA or non-XA. A combination of both is not allowed.

Response Message Type

Select the message type for the response from one of the following:

  • Bytes (for a stream of uninterpreted bytes)

  • Text (for text messages)

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

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

Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for the poller threads. The default Work Manager is used if no other Work Manager exists.

For information about Work Managers, see:

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

Note:

This option is not available when the MQ library is version 8 or version 9 with XA support.

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.

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

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 About RFH2 Headers".

Ignore Reply-To Headers

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

Dynamic Reply-To Headers

Select this option to use the reply-to headers from the request message in the response message as well.

When this property is set to true and the Ignore Reply-To Headers property is set to false, if the static reply-to queue manager (defined in proxy service's response URI) is not the same as the queue manager specified in the request message, the message is sent to the queue manager specified in the request message.

Worker Thread 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.

For information about Work Managers, see:

33.6.3 Configuring Business Services to Use the MQ Transport

Before you can configure a business service for the MQ Transport, you need to create the MQ Connection, as noted in How to Create MQ Connections. During service configuration, select either Message or Any XML as the service type. For more information, see Creating and Configuring Business Services.

Note:

A new validation has been added and this may cause the auto-generated pipeline to fail if a request only proxy service has been updated to request-response. You may need to update the configuration in the respective sbconfig.jar file accordingly.

The following table describes the properties you use to configure an MQ transport for a proxy service.

Table 33-2 MQ Transport Properties for Business Services

Option To create or edit...

Message Type

Select one of the following message types for the messages processed by the service:

  • 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

Specify one of the following options to base the response correlation pattern should 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.

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

Auto-generate Correlation Value

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

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

Model Queue

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

MQ Response URI

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

mq://local-queue-name?conn=mq-connection-resource

If you are using dynamic queues, enter the URI in the following format:

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*
mq://*

If you do not provide a dynamic_queue_name 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.

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

Note:

If the MQ library is version 8 or version 9 with XA support, and a response is required, then the endpoint URI and the response URI should both be either XA or non-XA. A combination of both is not allowed.

Response Timeout

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

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

Polling Interval

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

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

Poller Dispatch Policy

Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for the poller threads. The default Work Manager is used if no other Work Manager exists.

For information about Work Managers, see:

Dynamic Queue Pooling

Select this option to specify that the server use pooled connections to dynamic queues (for the dynamic queue response correlation pattern only).If you want 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 if you want to create a new dynamic queue instance on each request (and destroy the queue after the response).

Note:

This option is not available when the MQ library is version 8 or version 9 with XA support. Dynamic queue pooling is not allowed. The user is validated if response pooling is checked with MQ XA Response URI/Endpoint URI.

Endpoint URI 'PUT' options

Note:

This option is not available when the MQ library is version 8 or version 9 with XA support.

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.

Endpoint URI ‘GET’ options

Not supported when MQ transport is configured for a business service.

MQ Unrecognized Response URI

Enter the URI representing the queue to which unrecognized response messages should be sent. Note that 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.

Note:

When the MQ library is version 8 or version 9 with XA support, ECIDContext is only added to RF2 messages if this option is selected and DMS is enabled.

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

Worker Thread Dispatch Policy

Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for the worker threads. The default Work Manager is used if no other Work Manager exists.

For information about Work Managers, see:

33.6.4 MQ Transport 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 "Customizing Oracle Service Bus Environments" in Administering Oracle Service Bus.

The following table describes the environment values supported by the MQ transport and MQ connection resources. The values you specify for these variables override the properties configured for specific MQ proxy and business services. Services based on the MQ transport also support the Work Manager environment value.

Table 33-3 MQ Transport and Connection Resource Environment Values

Value Description

MQ Connection Pool Size

The number of connections maintained by the MQ connection pool.

MQ Connection Timeout

The time interval in seconds after which unused connections are destroyed.

MQ Dead Letter URI

The URI of the dead letter queue to which request messages should be redirected after attempting the specified number of retries.

MQ Host Name

The host name of the MQ queue manager, for TCP mode connections only.

MQ Port Number

The port number of the MQ queue manager, for TCP mode connections only.

MQ Queue Manager Channel Name

The name of the queue manager server connection channel, for TCP mode connections only.

MQ Queue Manager Name

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

MQ Response URI

The URI of the destination to which the response should be published when a response is required.

MQ Unrecognized Response URI

The URI representing the queue to which unrecognized response messages should be sent when the correlation value is automatically generated.

MQ Version

The version of WebSphere MQ being used.

MQ XA Enabled

An indicator of whether transactions handled by this connection are distributed (XA) transactions.

33.7 MQ Transport Headers

This section lists the headers used by the MQ transport. 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 pipeline, you can use a Transport Header action to set the header values in messages.

Table 33-4 MQ 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. This is specified in simple date format (yyyy-MM-dd HH:mm:ss.SSS). For example: 2014-03-18 05:17:20.123.

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. To override this logic, set the Dynamic Reply-To Headers property to true and the Ignore Reply-To Headers property to false in the proxy service. Then, if the headers values do not match, the message is sent to the queue manager specified in the request message.

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.7.1 Configuring Transport Headers

You can configure the transport headers for both inbound and outbound requests in the pipeline using a Transport Header action to set the header values in messages. For more information, see Adding Transport Header Actions in the Console.

When the transport header is explicitly set in the pipeline, 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.7.2 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>