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
Determine where the embedded message engine is hosted. It can be hosted on the batch dispatch
server, the batch executor server, or on a separate server. This server must be configured before
you complete this task. The JMS connection factory and activation specification references the
message engine server in its configuration. To configure the message engine:
- Add the wasJmsServer-1.0 feature to the
server.xml.
- Define the message engine by adding the messageEngine element. Define the
queue that is used for the batch dispatcher and batch executor. The following example illustrates
the message engine configuration in your server.xml.
<!-specify the ports for the message engine.
The ports in this example are the default ports.
This element is not needed when the default ports are used. -->
<wasJmsEndpoint host="*"
wasJmsPort="7280"
wasJmsSSLPort="7290"
enabled="true">
</wasJmsEndpoint>
<messagingEngine>
<!- queue for batch jms message. -->
<queue id="batchLibertyQueue"
forceReliability="ReliablePersistent"
receiveAllowed="true"/>
</messagingEngine>
About this task
This task helps you configure the batch dispatch server and the batch executor by using the Liberty embedded messaging provider.
Procedure
To configure batch dispatcher and executor that uses the Liberty embedded messaging
provider:
- Configure the batch JMS dispatcher.
- Enable JMS support by adding the wasJmsClient-2.0 feature to the feature
manager in your server.xml.
- Add the batchJmsDispatcher element to your server.xml
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 the connectionFactoryRef and queueRef
attributes, the default value for connectionFactoryRef is
batchConnectionFactory and the default value for queueRef is
batchJobSubmissionQueue. You can specify the
batchJmsDispatcher 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.
Note: The remoteServerAddress attribute points to the
host:port of the server that is hosting the Liberty message engine.
<batchJmsDispatcher connectionFactoryRef="batchConnectionFactory"
queueRef="batchJobSubmissionQueue" />
<jmsConnectionFactory id="batchConnectionFactory"
jndiName="jms/batch/connectionFactory">
<properties.wasJms remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsConnectionFactory>
<jmsQueue id="batchJobSubmissionQueue"
jndiName="jms/batch/jobSubmissionQueue">
<properties.wasJms deliveryMode="Persistent"
queuename="batchLibertyQueue">
</properties.wasJms>
</jmsQueue>
Note: Ensure that you are referencing a jmsConnectionFactory
element, as shown in the example, and not a jmsQueueConnectionFactory element.
Using a jmsQueueConnectionFactory element will not work. Your configuration should
include both a jmsConnectionFactory element and a jmsQueue
element, but not a jmsQueueConnectionFactory element.
- Configure the batch JMS executor.
- Enable JMS support by adding the wasJmsClient-2.0 feature to the feature
manager in your server.xml.
- Add the batchJmsExecutor element to your server.xml
file on the server that hosts the batch executor.
<batchJmsExecutor activationSpecRef={configured activation specification or batch executor}
queueRef={reference to the configured JMS queue} />
Note: If you do not specify the activationSpecRef and queueRef
attributes, the default value for activationSpecRef is
batchActivationSpec and the default value for queueRef is
batchJobSubmissionQueue. You can specify the batchJmsExecutor
element as <batchJmsExecutor />. You still must configure the JMS activation
specification for batchActivationSpec and the
batchJobSubmissionQueue JMS queue in the server.xml
file.
![[18.0.0.1 and later]](../ng_v18001plus.gif)
If you want batch group security enforcement, enable the
Liberty security by adding the
app-Security-2.0 feature to the feature manager in your
server.xml file. Also, add the
batchOperationGroupRef
attribute to the
batchJmsExecutor element as shown in the following
example.
<batchJmsExecutor activationSpecRef={configured activation specification or batch executor}
queueRef={reference to the configured JMS queue} />
- 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 or batch executor}
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 only
receives jobs that it can process.
The following example indicates the
messageSelector attribute for the executor to accept a job for the application
SimpleBatchJob and
BonusPayout.
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 application
SimpleBatchJob.
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 returns true. Check JMS
Javadoc for more information on JMS message selector.
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'">
![[18.0.0.1 and later]](../ng_v18001plus.gif)
The following example illustrates the batch JMS executor
that is configured with an operation group and its JMS configuration by using the
IBM MQ binding
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 BINDING 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.wasJms destinationRef="batchJobSubmissionQueue"
messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayoutCDI'"
destinationType="javax.jms.Queue"
remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsActivationSpec>
<!-- baseQueueName is the queue defined on WMQ system -->
<jmsQueue id="batchJobSubmissionQueue"
jndiName="jms/batch/jobSubmissionQueue">
<properties.wmqJms baseQueueName="BATCHQ"
priority="QDEF"
baseQueueManagerName="WMQX">
</properties.wmqJms>
</jmsQueue>
![[18.0.0.1 and later]](../ng_v18001plus.gif)
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"
jndiName="jms/batch/jobSubmissionQueue">
<properties.wmqJms baseQueueName="BATCHQ"
baseQueueManagerName="WMQX">
</properties.wmqJms>
</jmsQueue>
- Install your batch application on the server. For more information, see Deploying applications in Liberty.
![[17.0.0.3 and later]](../ng_v17003plus.gif)
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.
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.
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.