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.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.
-
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
- Stop the domain server.
- From your WebSphere MQ installation, copy the
com.ibm.mq.jar
file to the Service Bus domain atDOMAIN_HOME
/lib
directory. - Restart the domain server.
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:
-
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.
-
-
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.
-
Click Create or Finish.
The MQ Connection Definition Editor appears.
-
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.
-
-
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.
-
-
To configure SSL support for TCP mode connections, do the following:
-
Select the SSL Required check box to use SSL for sending messages. This enables service-side SSL authentication.
-
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.
-
To enable both client-side and server-side SSL authentication, select the 2-way SSL Required check box.
-
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.
-
-
For the Reference to the Static Service Account field, click the Browse icon to locate and select the service account to use.
-
In the MQ Version field, select the version of MQ server you are using.
-
To configure the MQ connection, do the following:
-
In the MQ Connection Pool Size field, enter the number of connections maintained by the connection pool.
-
In the MQ Connection Timeout field, enter the time interval in seconds after which unused connections are destroyed. The default is 1800 seconds.
-
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
-
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.
-
-
In the toolbar, click Save.
-
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:
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:
- In the Application Navigator or Project Navigator, expand the project and folders containing the MQ connection to delete.
- Right-click the name of the MQ connection, and select Delete.
- 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.
- 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
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-2 Messages Sent Through Service Bus
![Description of Figure 33-2 follows Description of Figure 33-2 follows](img/mq_inbound.gif)
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:
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:
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 |
Polling Interval |
Enter an interval in milliseconds to wait between polling for messages. The default is |
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:
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:
|
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:
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 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 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 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 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:
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 Outbound Transport Action: This header can be set in the pipeline for the outbound transport. If this header value is not set, the default |
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 Outbound Transport Action: If this header is not set in the pipeline for the outbound transport, the default value of |
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 |
Both |
Feedback |
The nature of the feedback report. This value is used with a message of type 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 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 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 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 Outbound Transport Action: The outbound transport generates messages of any type including |
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 ( 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 Inbound Transport Action: The inbound transport uses the Outbound Transport Action: In request/response message pattern, |
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 Outbound Transport Action: In request/response message pattern, |
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 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
orreplyToQueueName
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>