You can set up the batch environment to have servers function as batch dispatchers, while
other servers function as batch executors.
Before you begin
- Determine where the embedded messaging 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
messaging engine server in its configuration.
- To configure the messaging engine:
- Add the wasJmsServer-1.0 feature to the
server.xml.
- Define the messaging engine by adding the messagingEngine element. Define
the queue that is used for the batch dispatcher and batch executor. The following example
illustrates the messaging engine configuration in your server.xml
file:
<!-specify the ports for the messaging 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>
Important: Each dispatcher server and executor must be configured to use the same,
database-backed
job repository.
About this task
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. If the job is configured to run partitions, the batch executors make them available
to the other executors to run. The batch executors communicate with each other by using Java
Messaging Service (JMS). This task helps you configure the batch dispatch server and the batch
executor by using the Liberty embedded
messaging provider.
The following procedure describes how to separately configure one executor that runs only jobs
and another executor that runs only partitions. You can also configure an executor that runs both
jobs and partitions, but this procedure describes the more specialized, fine-grained configuration
that is required to configure the executors separately.
Procedure
-
Configure the batch JMS dispatcher.
-
Enable JMS support by adding the wasJmsClient-2.0 feature to the feature
manager in your server.xml file.
-
Add the batchJmsDispatcher element to your server.xml
file on the server that hosts the batch dispatcher; for example:
<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 messaging engine.
<batchJmsDispatcher connectionFactoryRef="batchConnectionFactory"
queueRef="batchJobSubmissionQueue" />
<jmsConnectionFactory id="batchConnectionFactory">
<properties.wasJms remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsConnectionFactory>
<jmsQueue id="batchJobSubmissionQueue">
<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 for executing batch jobs and the dispatcher for dispatching
partitions.
-
Enable JMS support by adding the wasJmsClient-2.0 feature to the feature
manager in your server.xml file.
-
Add the batchJmsDispatcher element to your server.xml
file on the server that hosts the batch executor.
<batchJmsDispatcher connectionFactoryRef={reference to a configured JMS connection factory}
queueRef={reference to a configured JMS queue} />
Note: If you do not add the batchJmsDispatcher element to your
server.xml file, the server will not dispatch partitions to run on multiple
servers and will run the partitions locally.
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
batchJobSubmissionQueue
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 messaging
engine.
<batchJmsDispatcher connectionFactoryRef="batchConnectionFactory"
queueRef="batchJobSubmissionQueue" />
<jmsConnectionFactory id="batchConnectionFactory">
<properties.wasJms remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsConnectionFactory>
<jmsQueue id='batchJobSubmissionQueue">
<properties.wasJms deliveryMode="Persistent"
queuename="batchLibertyQueue">
</properties.wasJms>
</jmsQueue>
-
Add the batchJmsExecutor element to your server.xml
on the server that hosts the batch executor; for example:
<batchJmsExecutor activationSpecRef={configured activation specification}
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 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.
-
Define batch executor server capabilities by including a JMS message selector in the activation
specification.
- Filter based on system-defined properties:
The following batch dispatcher properties are
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
- com_ibm_ws_batch_work_type: the work type : "Job"
Note: Specify a message selector 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 only batch jobs for the
application
SimpleBatchJob
:
messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' AND com_ibm_ws_batch_work_type = 'Job'">
- 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 the
JMS API documentation for more information on JMS message selectory.
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 configuration and its JMS
configuration:
<batchJmsExecutor activationSpecRef="batchActivationSpec"
queueRef="batchJobSubmissionQueue"/>
<jmsActivationSpec id="batchActivationSpec" >
<properties.wasJms destinationRef="batchJobSubmissionQueue"
messageSelector="(com_ibm_ws_batch_applicationName = 'SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayoutCDI') AND com_ibm_ws_batch_work_type='Job'"
destinationType="javax.jms.Queue"
remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsActivationSpec>
<jmsQueue id="batchJobSubmissionQueue">
<properties.wasJms deliveryMode="Persistent"
queueName="batchLibertyQueue">
</properties.wasJms>
</jmsQueue>
-
Configure the batch JMS executor for executing only partitions.
-
Enable JMS support by adding the wasJmsClient-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 that is running batch jobs.
<batchJmsExecutor activationSpecRef={configured activation specification}
queueRef={reference to the configured JMS queue}
replyConnectionFactoryRef={reference to the configured JMS connection factory} />
The following table lists the default values for the
activationSpecRef,
queueRef, and
replyConnectionFactoryRef attributes. If you do not specify any one of these
attributes, its default value is applied.
Table 1. Default attribute values for the
Batch JMS executor
Attribute |
Default value |
activationSpecRef |
batchActivationSpec |
queueRef |
batchJobSubmissionQueue |
replyConnectionFactoryRef |
batchConnectionFactory |
If you do not specify any of these attributes, you can specify the
batchJmsExecutor element as <batchJmsExecutor/>
. However,
if you use the default values for these attributes, you must configure the JMS activation
specification for the batchActivationSpec
value, the
batchJobSubmissionQueue
queue, and the JMS connection factory for the
batchConnectionFactory
value 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.
-
Define batch executor server capabilities by including a JMS message selector in the activation
specification.
- Filter based on system-defined properties:
The following batch dispatcher properties are
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
- com_ibm_ws_batch_work_type: the work type : "Partition"
- com_ibm_ws_batch_partitionNum(Type=Integer): the partition number of the
partition that is being dispatched
- com_ibm_ws_batch_stepName: the name of the step as defined in the JSL
Note: Specify a message selector 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 only partitions for the
application
SimpleBatchJob
:
messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' AND com_ibm_ws_batch_work_type = 'Partition'">
The following example indicates the
messageSelector attribute for the
executor to accept only partitions for the application
SimpleBatchJob
:
messageSelector="com_ibm_ws_batch_applicationName = 'SimpleBatchJob' AND com_ibm_ws_batch_work_type = 'Partition' AND com_ibm_ws_batch_stepName = 'step1'">
- 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 the
JMS API documentation for more information on JMS message selectory.
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 configuration and its JMS
configuration:
<jmsConnectionFactory id="batchConnectionFactory"/>
<batchJmsExecutor activationSpecRef="batchActivationSpec"
queueRef="batchJobSubmissionQueue"/>
replyConnectionFactoryRef="batchConnectionFactory"/>
<jmsActivationSpec id="batchActivationSpec" >
<properties.wasJms destinationRef="batchJobSubmissionQueue"
messageSelector="(com_ibm_ws_batch_applicationName = 'SimpleBatchJob' OR com_ibm_ws_batch_applicationName = 'BonusPayoutCDI') AND com_ibm_ws_batch_work_type='Partition'"
destinationRef="batchJobSubmissionQueue"
destinationType="javax.jms.Queue"
remoteServerAddress="host:7280:BootstrapBasicMessaging">
</properties.wasJms>
</jmsActivationSpec>
<jmsQueue id="batchJobSubmissionQueue">
<properties.wasJms deliveryMode="Persistent"
queueName="batchLibertyQueue">
</properties.wasJms>
</jmsQueue>
-
Install your batch application on the server. For more information, see Deploying applications in Liberty.
Note: If you configure multiple server partition support for your server, but want to disable
multiple server partition execution for an individual job, you can set the
com.ibm.websphere.batch.partition.multiJVM
job property to
false in your
JSL Job XML file. The following example illustrates a JSL job to disable multiple server
partitions:
<job id="SimpleBonusPayoutJob" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/jobXML_1_0.xsd" version="1.0">
<properties>
<property name="com.ibm.websphere.batch.partition.multiJVM" value="false"/>
</properties>
Note: In versions 20.0.0.7 and earlier, if you are running a partition on a remote executor, no job
logs are created for that partition.
In versions 20.0.0.8 and later, job
logs are created for partitions that run on a remote executor.