You can use the MQ transport to enable MQ proxy services to get messages from WebSphere MQ and MQ business services to send messages to WebSphere MQ. For inbound and outbound connectively to WebSphere MQ 5.3 and 6.0 to be available, ensure that the MQ client libraries are available in your ALSB environment. For more information, see Adding MQ Client Libraries to Your Environment.
When you configure a proxy service, you can use a Transport Header action to set the header values in messages. For more information, see Transport Headers.
Adding MQ Client Libraries to Your Environment
ALSB is a client for WebSphere MQ and although ALSB supports run-time server compatibility for both MQ 5.3 and 6.0, these MQ libraries are not bundled with the ALSB installer. You need to ensure that the MQ 6.0 client library, com.ibm.mq.jar, is available in your environment.
Copy the com.ibm.mq.jar file to the BEA_HOME\user_projects\domains\<domain_name>\lib directory.
BEA_HOME is the ALSB installation directory. Replace <domain_name> with the actual name of your domain.
Restart the domain server.
If you use bindings mode to connect MQ Queue Manager located on the same machine as ALSB, add <MQ_install_directory>/bin and <MQ_install_directory>/java/lib to the PATH environment variable.
MQ Connection Resources
MQ connections are sharable resources that can be reused across multiple MQ proxy and business services. MQ proxy and business services must connect to a MQ queue manager before accessing the MQ queue. MQ connection resources provide the connection parameters required for connecting to a MQ queue manager.
Each MQ connection resource has a connection pool. Multiple business services and proxy services using the same queue manager share a connection pool. Any business or proxy service using a given MQ connection resource to connect to a given queue manager uses the same connection pool that was created for that MQ connection resource.
For information about managing MQ connection resources, see MQ Connections in Using the AquaLogic Service Bus Console.
Creating an MQ Connection Resource
To create an MQ connection resource:
In the Project Explorer, select MQ Connection as the resource type. The Create a New MQ Connection Resource page appears.
Enter the name and description of the resource.
Select the connection type as tcp mode or bindings mode.
Use the tcp mode when the MQ Queue Manager is not available on the same machine as ALSB. Use bindings to connect MQ Queue Manager located on the same machine as ALSB.
If the connection type is bindings mode, enter the name of the MQ Queue Manager.
If the connection type is tcp mode,
Enter the host name of the MQ Queue Manager.
Enter the port number of the MQ Queue Manager Listener.
Enter the name of the MQ Queue Manager.
Enter the coded character set identifier (CCSID) to be used for connecting to the MQ Queue Manager for client connection mode.
Enter the Queue Manager server connection channel name.
Select the SSL option, if required, to use HTTPS protocol for sending the messages.
After you select this option, select the 2-way SSL Required option to enable 2-way SSL for both client-side and server-side authentication. Clear the 2-way SSL Required option for 1-way SSL for only server-side authentication.
Note:
When you select 2-way SSL, you need to provide a reference to a service key provider. A service key provider contains Public Key Infrastructure (PKI) credentials that proxy services use for decrypting inbound SOAP messages and for outbound authentication and digital signatures. For more information about using service providers, see Service Key Providers in Using the AquaLogic Service Bus Console.
Specify the static service account.
A service account provides a user name and password that proxy services and business services use for outbound authentication or authentication to a local or remote resource. For more information about using service accounts, see Service Accounts in Using the AquaLogic Service Bus Console.
Select the version of WebSphere MQ as 5.3 or 6.0.
Enter the size of the MQ connection pool. Default is 10.
Enter the duration after which a connection must timeout. Default is 30 seconds.
Click Save.
The MQ connection resource is created. You can use it across proxy and business services that use the MQ transport.
Configuring Proxy Services to Use the MQ Transport
When you create a proxy service in ALSB Console, select the transport protocol as mq and specify the endpoint configuration for a proxy service that uses the MQ transport in the Transport Configuration page. Specify the URI in mq://local-queue-name?conn=mq-connection-resource-ref format where, local-queue-name is the name of the local queue configured on the MQ server, mq-connection-resource-ref points to the location of the MQ connection resource. For example, if you create a MQ connection resource, mqConnection in the defaultMQ folder and the queue name is testQueue, the URI would be mq://testQueue?conn=defaultMQ/mqConnection
Note:
During service configuration, select either Message service or XML service as the service type in the General Configuration page. For more information, see Supported Service Types and Proxy Services: Creating and Managing in Using the AquaLogic Service Bus Console.
Configure the MQ transport for a proxy service with values as described in the following table:
Table 1-1 MQ Proxy Service Configuration
Field
Description
Polling Interval
Time in milliseconds after which the MQ Queue is polled for new messages. Default is 1000 milliseconds.
Is Response Required
Select this option if a response needs to be published to the specified destination.
Response Correlation Pattern
Specify if the response correlation pattern should be based on message ID or correlation ID.
MQ Response URL
The destination to which the response should be published. Specify the URI in mq://local-queue-name?conn=mq-connection-resource-ref format.
Note:
If the replyToQueueName and replyToQueueManagerName MQMD headers are not set on the incoming request, this response URI is used as the default response destination. However, if a response URI is set in the headers, ALSB connects to the queue manager specified in replyToQueueManagerName and sends the response to the response queue specified in replyToQueueName.
Response Message Type
The message type of the response can be bytes or text.
Client Response Timeout
The duration to wait for the response to be published before closing the connection.
Note:
You can specify the Response Correlation Pattern, MQ Response URL, Response Message Type, and Client Response Timeout values only if a response is required.
Dispatch Policy
Select a dispatch policy for this endpoint.
Dispatch policy refers to the instance of WLS Work Manager that you want to use for the service endpoint. For information about work managers, see Using Work Managers to Optimize Scheduled Work and Create Work Manager in the WebLogic Server Administration Console Online Help.
For more information about configuring proxy services using MQ transport, see MQ Transport Configuration Page in Proxy Services: Creating and Managing in Using the AquaLogic Service Bus Console.
Transport Headers
The various headers used by the MQ transport are listed in Table 1-2. 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.
Table 1-2 Transport Headers
Header
Description
Inbound Response / Outbound Request
Accounting Token
Accounting token is part of the identity context of the message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Application ID Data
Application ID data is part of the identity context of the message. This value can be used to provide additional information about the message or its originator.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Application Origin Data
Data about the originating application. This value can be used by the application to provide additional information about the origin of the message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Backout Count
The number of times the message was returned by the MQ Queue, as part of a unit of work, and subsequently backed out.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Character Set
The coded character set identifier of character data in the application message data.
Inbound Transport Action: This field is used by the inbound transport to convert data in a specific representation. For request-response messaging, the characterSet header from the request message is copied to the response. When this header is not configured on the incoming request, default value of the MQC.MQCCSI_Q_MGR field is assumed.
Outbound Transport Action: This header can be set in the pipeline for the outbound transport. If this header value is not set, the default MQC.MQCCSI_Q_MGR value is assumed.
Both
Correlation ID
The correlation-id of the message that should be retrieved.
Inbound Transport Action: For correlationID-based response correlation pattern, the correlationID from the request is echoed on the response. The user can override the correlationID in the response pipeline.
Outbound Transport Action: When the Auto-generate correlationID option is selected during service configuration, the outbound transport will automatically generate a correlationID and overwrite the correlationID from the transport header. If this value is not specified, the correlationID specified in the pipeline is used.
For one-way messaging, the correlationID specified in the pipeline is used in the (outbound) request.
Both
Encoding
The representation used for numeric values in the application message data.
Inbound Transport Action: The inbound transport uses this header to interpret the incoming message data. If this header is not configured in the response pipeline, the default value of MQC.MQENC_NATIVE is used.
Outbound Transport Action: If this header is not set in the pipeline for the outbound transport, the default value of MQC.MQENC_NATIVE is used.
Both
Expiry
The expiry time (in tenths of a second) is set by the application that puts the message. After a message’s expiry time has elapsed, it is eligible to be discarded by the queue manager.
Inbound Transport Action: For request-response messaging, the inbound transport copies the expiry header of the request to the response.
Outbound Transport Action: If the corresponding transport header is set in the pipeline, it is copied to the outbound request message.
Note:
The report header will always contain the MQC.MQRO_PASS_DISCARD_AND_EXPIRY option (in addition to others). This option is a directive to the receiving client that the expiry time of the original message should be copied to the report or reply message.
Both
Feedback
The nature of the feedback report. This value is used with a message of type MQC.MQMT_REPORT to indicate the nature of the report.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Format
Format name of the message data. The format name is used by the sender of the message to indicate the nature of the data in the message to the receiver.
Inbound Transport Action: When the field is set to MQC.MQFMT_MD_EXTENSION, the inbound transport will read the extended MQMD object.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Group ID
The value that identifies the message group to which the physical message belongs.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Offset
In a segmented message, offset of data in the physical message from the start of the logical message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Original Length
Original length of a segmented message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Message Flags
Flags that control the segmentation and status of a message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Message ID
ID of the message to be retrieved.
Inbound Transport Action: If messageID is not specified in the response pipeline, the messageID header is set to MQC.MQMI_NONE.
For messageID-based correlation, the inbound transport copies the messageID from the request to the correlationID header of the response. MessageID-based correlation is assumed when the report header contains the MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID option.
Outbound Transport Action: When the Auto-generate messageID option is specified during service configuration, the outbound transport automatically generates the messageID and overwrites the messageID from the transport header. If this value is not specified, the messageID transport header is used.
For one-way messaging, the messageID specified in the pipeline is used in the outbound request. If this value is not specified, the messageID is automatically generated by the transport.
Both
Message Sequence Number
Sequence number of a logical message within group.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Message Type
Message type of the message.
Inbound Transport Action: The inbound transport reads and processes messages of any type including MQC.MQMT_REQUEST, MQC.MQMT_DATAGRAM, MQC.MQMT_REPLY and MQC.MQMT_REPORT. The inbound transport does not generate report messages.
Outbound Transport Action: The outbound transport generates messages of any type including MQC.MQMT_DATAGRAM, MQC.MQMT_REQUEST, MQC.MQMT_REPLY and MQC.MQMT_REPORT. When the messageType header is not configured in the pipeline, the transport generates messages of type MQC.MQMT_DATAGRAM when the messaging pattern is one-way and MQC.MQMT_REQUEST when the messaging pattern is request-reply.
Both
Persistence
The message persistence.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Priority
Priority of the message
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Put Application Name
The name of the application that put the message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Put Application Type
The type of the application that put the message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Put Date Time
The time and date when the message was put.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Both
Reply To Queue Name
The name of the queue to which a reply should be sent.
The application that issued the get request for the message can send MQC.MQFMT_REPLY and MQC.MQFMT_REPORT messages to this queue.
Inbound Transport Action: The inbound transport uses the replyToQueueName as the response queue name when this field is set. If this values is not set, the queue name is derived from the default destination URI.
Outbound Transport Action: In request/response message pattern, replyToQueueName set in the message flow is ignored. In one way message pattern, replyToQueueName set in the message flow is used in the outbound messages.
Inbound Response
Reply To Queue Manager Name
The name of the queue manager to which reply or report messages can be sent.
Inbound Transport Action: In request/response message pattern, if the inbound message replyToQueuManager header value not match the configured value for the queue manager in the response URI, the response message is dropped and a transport error is logged.
Outbound Transport Action: In request/response message pattern, replyToQueueManager set in the message flow is ignored. In one way message pattern, replyToQueueManager set in the message flow is used in the outbound messages.
Inbound Response
Report
A report is a message about another message. This field enables the application sending the original message to specify which report messages are required, whether the application message data is to be included in them, and also how the message and correlation ID in the report or reply are to be set. It comprises one or more constants from the MQC class combined by means of the '+' or '|' operators.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline. For request-response messaging, this header can be configured in the response pipeline.
Outbound Transport Action: The transport always sets a combination of the following options in the report field.
Set MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID if messageID-based correlation pattern is used and MQC.MQRO_PASS_CORREL_ID if correlationID-based correlation pattern is used. Always set MQC.MQRO_PASS_DISCARD_AND_EXPIRY.
Note:
These options are set in addition to the options specified on the corresponding transport header in the pipeline.
Both
User ID
It is part of the identity of the message and identifies the user who originated the message.
Inbound Transport Action: No explicit processing is done by the transport. The header is copied to the transport header in the pipeline.
Outbound Transport Action: No explicit processing is done by the transport. If the corresponding transport header is set in the pipeline, it is copied to the request message.
Inbound Response
Version
The version number of the message descriptor.
Inbound Transport Action: The inbound transport supports both version 1 and version 2 message descriptors.
Outbound Transport Action: By default, the outbound transport generates version 2 headers. However, this field can be overridden in the pipeline.
Inbound Response
Configuring Transport Headers
You can configure the transport headers for both inbound and outbound requests in the Message Flow. For information about the transport headers related to the MQ transport, see Transport Headers.
In the message flow, use a Transport Header action to set the header values in messages. For more information, see Adding Transport Header Actions in Using the AquaLogic Service Bus Console.
When the transport header is explicitly set in the message flow, this value overrides the header value except in the following scenarios:
For the outbound request-response pattern, when the Auto-generate Correlation Value option is selected for a outbound request with a request-response message pattern, the correlation ID is always generated even if this value is set in the message flow.
When the report header is set in the message flow, the combination of multiple directives associated with the report header are merged with the default directives.
When the replyToQueueManagerName or replyToQueueName headers are set in the message flow for an outbound request with a request/response message pattern, these values are ignored. Instead, these transport header values are derived from the response URI configured for the business service.
For the inbound response, when the value in the replyToQueueManagerName header does not match the queue manager name specified in the response URI, an error message is generated and the response message is not sent.
The replyToQueueName set in the inbound request header overrides the value configured in the reply to URI for the proxy service.
For a one-way business service, when the message type header is configured to be of type request in the message flow, the replyToQueueName header must be specified. If this value is not specified, an error is generated on the MQ server and the message is rolled back.
Configuring Business Services to Use the MQ Transport
When you create a business service from ALSB Console, select the transport protocol as mq and specify the endpoint URI in the Transport Configuration page. Specify the URI in mq://local-queue-name?conn=mq-connection-resource-ref format where, local-queue-name is the name of the local queue configured on the MQ server, mq-connection-resource-ref points to the location of the MQ connection resource. For example, if you create a MQ connection resource, mqConnection in the defaultMQ folder and the queue name is testQueue, the URI would be mq://testQueue?conn=defaultMQ/mqConnection
Note:
Since the only service types that are supported for the MQ transport are Message and XML ensure that you select either Message service or XML service, when you select the service type in the General Configuration page. For more information, see in Business Services: Creating and Managing in Using the AquaLogic Service Bus Console.
To configure the MQ transport for a business service, specify the values as described in the following table:
Field
Description
Is Response Required
Select this option if a response needs to be published to the specified destination.
Polling Interval
Time in seconds after which the MQ Queue is polled for new messages. The default value is 1000 seconds.
Message Type
The message type of the response can be bytes or text.
Response Correlation Pattern
Specify if the response correlation pattern should be based on message ID or correlation ID.
Auto-generate Correlation Value
Select this option to automatically generate the correlation value.
MQ Response URL
The destination to which the response should be published. Specify the URI in mq://local-queue-name?conn=mq-connection-resource-ref format.
Response Timeout
The duration to wait for the response to be published.
Dispatch Policy
Select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy.
Dispatch policy refers to the instance of WLS Work Manager that you want to use for the service endpoint. For information about work managers, see Using Work Managers to Optimize Scheduled Work and Create Work Manager in the WebLogic Server Administration Console Online Help.
For more information about configuring business services using MQ transport, see MQ Transport Configuration Page in Business Services: Creating and Managing in Using the AquaLogic Service Bus Console.
Error Handling
You can configure MQ-transport business services to handle application and communications errors as follows:
Application errors – You can specify whether or not to retry business service endpoint URIs when application errors occur. For more information, see Retry Application Errors in “Creating and Configuring Business Services - Transport Configuration page” in Using the AquaLogic Service Bus Console.
