Enabling multiple server support by using the IBM MQ messaging provider
The batch environment can be set up to have servers function as batch dispatchers while other servers function as batch executors. Batch dispatchers accept requests from external clients and make them available to the batch executors. The batch executors receive requests that match its defined capabilities and execute those requests. Batch dispatchers and batch executors communicate by using Java Messaging Service (JMS).
Before you begin
About this task
This task helps you configure the batch dispatch server and the batch executor by using the IBM MQ messaging provider.
Procedure
-
Configure the batch JMS dispatcher.
- Enable JMS support by adding the wmqJmsClient-2.0 feature to the feature manager in your server.xml file. If you are using MQ on z/OS in BINDINGS mode, add the zosTransaction-1.0 feature.
-
Add the batchJmsDispatcher element to your server.xml
file on the server that hosts the batch dispatcher.
<batchJmsDispatcher connectionFactoryRef={reference to a configured JMS connection factory} queueRef={reference to a configured JMS queue} />
Note: If you do not specify theconnectionFactoryRef
andqueueRef
attributes, the default value forconnectionFactoryRef
is batchConnectionFactory and the default value forqueueRef
is batchJobSubmissionQueue. You can specify thebatchJmsDispatcher
element as<batchJmsDispatcher />
. You still must configure the batchConnectionFactory JMS connection factory and the JMS batchJobSubmissionQueue queue in the server.xml file. -
Add the corresponding JMS connection factory and JMS queue to the server configuration. This is
not specific to batch configuration.
The following example illustrates the batch JMS dispatcher configuration and its JMS configuration by using IBM MQ bindings mode.
<batchJmsDispatcher connectionFactoryRef="batchConnectionFactory" queueRef="batchJobSubmissionQueue" /> <!-- wmq resource adapter --> <variable name="wmqJmsClient.rar.location" value="${server.config.dir}/wmq.wlp.rar"/> <!-- nativeLibraryPath is required for BINDINGS mode --> <!-- the startup retry and reconnect retry properties are recommended to ensure robustness of the system.--> <wmqJmsClient nativeLibraryPath="/mqm/jms/java/lib" startupRetryCount=999 startupRetryInterval="1000ms" reconnectionRetryCount=10 reconnectionRetryInterval="5m"> </wmqJmsClient> <authData password="pwd" user="user"> </authData> <jmsConnectionFactory id="batchConnectionFactory"> <properties.wmqJms transportType="BINDINGS" queueManager="WMQX"> </properties.wmqJms> </jmsConnectionFactory> <!-- baseQueueName is the queue defined on WMQ system --> <jmsQueue id="batchJobSubmissionQueue"> <properties.wmqJms baseQueueName="BATCHQ" priority="QDEF" baseQueueManagerName="WMQX"> </properties.wmqJms> </jmsQueue>
The following example illustrates the batch JMS dispatcher configuration and its JMS configuration by using IBM MQ in client mode.
<batchJmsDispatcher connectionFactoryRef="batchConnectionFactory" queueRef="batchJobSubmissionQueue" /> <!-- wmq resource adapter --> <variable name="wmqJmsClient.rar.location" value="${server.config.dir}/wmq.wlp.rar"/> <!-- the startup retry and reconnect retry properties are recommended to ensure robustness of the system.--> <wmqJmsClient startupRetryCount=999 startupRetryInterval="1000ms" reconnectionRetryCount=10 reconnectionRetryInterval="5m"> </wmqJmsClient> <authData password="pwd" user="user"> </authData> <jmsConnectionFactory id="batchConnectionFactory"> <properties.wmqJms hostName="webs24.pok.stglabs.ibm.com" transportType="CLIENT" channel="WAS.JMS.SVRCONN" port="1414" queueManager="WMQX"/>> </properties.wmqJms> </jmsConnectionFactory> <!-- baseQueueName is the queue defined on WMQ system --> <jmsQueue id="batchJobSubmissionQueue"> <properties.wmqJms baseQueueName="BATCHQ" priority="QDEF" baseQueueManagerName="WMQX"> </properties.wmqJms> </jmsQueue>
Note: Ensure that you are referencing ajmsConnectionFactory
element, as shown in the example, and not ajmsQueueConnectionFactory
element. Using ajmsQueueConnectionFactory
element does not work. Your configuration must include both ajmsConnectionFactory
element and ajmsQueue
element, but not ajmsQueueConnectionFactory
element.
-
Configure the batch JMS executor.
- Enable JMS support by adding the wmqJmsClient-2.0 feature to the feature manager in your server.xml file.
-
Add the batchJmsExecutor element to your server.xml
file on the server that hosts the batch executor.
<batchJmsExecutor activationSpecRef={configured activation specification} queueRef={reference to the configured JMS queue} />
Note: If you do not specify theactivationSpecRef
andqueueRef
attributes, the default value foractivationSpecRef
is batchActivationSpec and the default value forqueueRef
is batchJobSubmissionQueue. You can specify thebatchJmsExecutor
element as<batchJmsExecutor />
. You still must configure the JMS activation specification forbatchActivationSpec
and thebatchJobSubmissionQueue
JMS queue in the server.xml file. - Add the corresponding JMS activation specification and JMS queue to the server configuration. This is not specific to batch configuration.
- Optional:
If you want batch group security enforcement, add the corresponding operation group name
stanzas to the
batchJmsExecutor
element as shown in the following example.<batchJmsExecutor activationSpecRef={configured activation specification} queueRef={reference to the configured JMS queue} > <operationGroup>GroupA</operationGroup> </batchJmsExecutor>
Note: You must configure the security registry to support the previously listed group names. - Define batch executor server capabilities by including a JMS message selector in the
activation specification.
- Filtering based on system defined properties:
There is a set of batch dispatcher properties available on the batch JMS message that the batch executor can use to filter for inbound messages.
- com_ibm_ws_batch_applicationName: the name of the batch application for the job request
- com_ibm_ws_batch_moduleName: the module name of the batch application for the job request
- com_ibm_ws_batch_componentName: the component name of the batch application for the job request
Note: It is recommended that a message selector is specified with at least the com_ibm_ws_batch_applicationName property to ensure that the executor receives only jobs that it can process.The following example indicates the messageSelector attribute for the executor to accept a job for the applicationSimpleBatchJob
andBonusPayout
.messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayout'">
The following example indicates the messageSelector attribute for the executor to accept a job for the applicationSimpleBatchJob
.messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob'">
- Filtering based on user-defined properties:
The batch dispatcher sets all job parameters that conform to the proper JMS message property on the batch dispatcher request message. These properties can also be used by the message selector to add extra filtering to the message selector. The property name, or identifier, must conform to JMS message property constraints. For example, the property is an unlimited length sequence of letters and digits, the first of which must be a letter. A letter is any character for which the method Character.isJavaLetter returns
true
, and includes '_' and '$'. A letter or digit is any character for which the method Character.isJavaLetterOrDigit returnstrue
. Check JMS Javadoc for more information on JMS message selectors.The following example illustrates a possible message selector by using the com_ibm_ws_batch_applicationName property and a job parameter specialCapability.messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' AND specialCapability = 'superCapability'">
The following example illustrates the batch JMS executor that is configured with an operation group and its JMS configuration by using the IBM® MQ bindings mode.<batchJmsExecutor activationSpecRef="batchActivationSpec" queueRef="batchJobSubmissionQueue"/> <operationGroup>GroupA</operationGroup> </batchJmsExecutor> <!-- wmq resource adapter --> <variable name="wmqJmsClient.rar.location" value="${server.config.dir}/wmq.wlp.rar"/> <!-- nativeLibraryPath is required for BINDINGS mode --> <!-- the startup retry and reconnect retry properties are recommended to ensure robustness of the system.--> <wmqJmsClient nativeLibraryPath="/mqm/jms/java/lib" startupRetryCount=999 startupRetryInterval="1000ms" reconnectionRetryCount=10 reconnectionRetryInterval="5m"> </wmqJmsClient> <authData password="pwd" user="user"> </authData> <jmsActivationSpec id="batchActivationSpec" > <properties.wmqJms destinationRef="batchJobSubmissionQueue" destinationType="javax.jms.Queue" messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayout'" transportType="BINDINGS" queueManager="WMQX"> </properties.wmqJms> </jmsActivationSpec> <!-- baseQueueName is the queue defined on WMQ system --> <jmsQueue id="batchJobSubmissionQueue"> <properties.wmqJms baseQueueName="BATCHQ" priority="QDEF" baseQueueManagerName="WMQX"> </properties.wmqJms> </jmsQueue>
The following example illustrates the batch JMS executor that is configured with an operation group and its JMS configurations by using the IBM MQ client mode.<batchJmsExecutor activationSpecRef="batchActivationSpec" queueRef="batchJobSubmissionQueue"/> <operationGroup>GroupA</operationGroup> </batchJmsExecutor> <!-- wmq resource adapter --> <variable name="wmqJmsClient.rar.location" value="${server.config.dir}/wmq.wlp.rar"/> <!-- the startup retry and reconnect retry properties are recommended to ensure robustness of the system.--> <wmqJmsClient startupRetryCount=999 startupRetryInterval="1000ms" reconnectionRetryCount=10 reconnectionRetryInterval="5m"> </wmqJmsClient> <authData password="pwd" user="user"> </authData> <jmsActivationSpec id="batchActivationSpec" > <properties.wmqJms destinationRef="batchJobSubmissionQueue" messageSelector="com_ibm_ws_batch_applicationName = SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayout'" transportType="CLIENT" channel="WAS.JMS.SVRCONN" destinationType="javax.jms.Queue" queueManager="WMQX" hostName="webs24.pok.stglabs.ibm.com" port="1414"> </properties.wmqJms> </jmsActivationSpec> <!-- baseQueueName is the queue defined on WMQ system --> <jmsQueue id="batchJobSubmissionQueue"> <properties.wmqJms baseQueueName="BATCHQ" baseQueueManagerName="WMQX"> </properties.wmqJms> </jmsQueue>
- Filtering based on system defined properties:
-
Install your batch application on the server. For more information, see Deploying applications in Liberty.
Note: To delay delivery of job messages, submit the job specifying a job parameter of com_ibm_ws_batch_message_deliveryDelay that is set to the number of milliseconds to delay delivery of the message to an executor server. For IBM MQ to delay delivery of messages, the SYSTEM.DDELAY.LOCAL.QUEUE must be defined by the CSQ4INSG IBM MQ installation job. If the queue is not defined, an MQRC_UNKNOWN_OBJECT_NAME error is displayed.
To alter the priority of the job message, submit the job specifying a job parameter of com_ibm_ws_batch_message_priority that is set to a valid JMS Message priority (0-9). The JMS specification defines the default message priority as '4' with zero as the lowest priority and nine as the highest. For priority settings to take effect, the priority setting in the properties.wmqJms configuration must be set to APP instead of QDEF. A value of QDEF causes the default priority of the queue definition to be used. The queue definition itself must have MsgDeliverySequence set to MQMDS_PRIORITY.
Restarting a failed job uses the same delay and priority as the original job unless a different value is specified as a job parameter on restart. Priority is propagated to messages for multi-server partitions, but the delivery delay is not propagated.