Chapter 21. Configuring Batch Applications
JBoss EAP 7 introduced support for Java batch applications as defined by JSR-352. You can configure an environment for running batch applications and manage batch jobs using the batch-jberet
subsystem.
For information on developing batch applications, see Java Batch Application Development in the JBoss EAP Development Guide.
21.1. Configuring Batch Jobs
You can configure settings for batch jobs using the batch-jberet
subsystem, which is based on the JBeret implementation.
The default batch-jberet
subsystem configuration defines an in-memory job repository and default thread pool settings.
<subsystem xmlns="urn:jboss:domain:batch-jberet:2.0"> <default-job-repository name="in-memory"/> <default-thread-pool name="batch"/> <job-repository name="in-memory"> <in-memory/> </job-repository> <thread-pool name="batch"> <max-threads count="10"/> <keepalive-time time="30" unit="seconds"/> </thread-pool> </subsystem>
By default, any batch jobs stopped during a server suspend will be restarted upon server resume. You can set the restart-jobs-on-resume
property to false
to leave jobs in the STOPPED
state instead.
/subsystem=batch-jberet:write-attribute(name=restart-jobs-on-resume,value=false)
You can also configure the settings for batch job repositories and thread pools.
21.1.1. Configure Batch Job Repositories
This section shows you how to configure in-memory and JDBC job repositories for storing batch job information using the management CLI. You can also configure job repositories using the management console by navigating to the Batch subsystem from the Configuration tab and selecting either In Memory or JDBC from the left-hand menu.
Add an In-memory Job Repository
You can add a job repository that stores batch job information in memory.
/subsystem=batch-jberet/in-memory-job-repository=REPOSITORY_NAME:add
Add a JDBC Job Repository
You can add a job repository that stores batch job information in a database. You must specify the name of the datasource for connecting to the database.
/subsystem=batch-jberet/jdbc-job-repository=REPOSITORY_NAME:add(data-source=DATASOURCE)
Set a Default Job Repository
You can set an in-memory or JDBC job repository as the default job repository for batch applications.
/subsystem=batch-jberet:write-attribute(name=default-job-repository,value=REPOSITORY_NAME)
This will require a server reload.
reload
21.1.2. Configure Batch Thread Pools
This section shows you how to configure thread pools and thread factories to be used for batch jobs using the management CLI. You can also configure thread pools and thread factories using the management console by navigating to the Batch subsystem from the Configuration tab and selecting Thread Pools or Thread Factories from the left-hand menu.
Configure a Thread Pool
When adding a thread pool, you must specify the max-threads
, which should always be greater than 3
as two threads are reserved to ensure partition jobs can execute as expected.
Add a thread pool.
/subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:add(max-threads=10)
If desired, set a
keepalive-time
value./subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:write-attribute(name=keepalive-time,value={time=60,unit=SECONDS})
Use a Thread Factory
Add a thread factory.
/subsystem=batch-jberet/thread-factory=THREAD_FACTORY_NAME:add
Configure the desired attributes for the thread factory.
-
group-name
- The name of a thread group to create for this thread factory. -
priority
- The thread priority of created threads. thread-name-pattern
- The template used to create names for threads. The following patterns may be used:-
%%
- A percent sign -
%t
- The per-factory thread sequence number -
%g
- The global thread sequence number -
%f
- The factory sequence number -
%i
- The thread ID
-
-
Assign the thread factory to a thread pool.
/subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:write-attribute(name=thread-factory,value=THREAD_FACTORY_NAME)
This will require a server reload.
reload
Set a Default Thread Pool
You can set a different thread pool as the default thread pool.
/subsystem=batch-jberet:write-attribute(name=default-thread-pool,value=THREAD_POOL_NAME)
This will require a server reload.
reload
View Thread Pool Statistics
You can view runtime information about a batch thread pool using the read-resource
management CLI operation. You must use the include-runtime=true
parameter in order to see this runtime information.
/subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:read-resource(include-runtime=true) { "outcome" => "success", "result" => { "active-count" => 0, "completed-task-count" => 0L, "current-thread-count" => 0, "keepalive-time" => undefined, "largest-thread-count" => 0, "max-threads" => 15, "name" => "THREAD_POOL_NAME", "queue-size" => 0, "rejected-count" => 0, "task-count" => 0L, "thread-factory" => "THREAD_FACTORY_NAME" } }
You can also view runtime information for batch thread pools using the management console by navigating to the Batch subsystem from the Runtime tab.
21.2. Managing Batch Jobs
The batch-jberet
subsystem resource for deployments allows you to start, stop, restart, and view execution details for batch jobs. Batch jobs can be managed from the management CLI or the management console.
Manage Batch Jobs from the Management CLI
Restart a Batch Job
You can restart a job that is in a STOPPED
or FAILED
state by providing its execution ID and optionally any properties to use when restarting the batch job.
/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:restart-job(execution-id=EXECUTION_ID,properties={PROPERTY=VALUE})
The execution ID must be the most recent execution of the job instance.
Start a Batch Job
You can start a batch job by providing the job XML file and optionally any properties to use when starting the batch job.
/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:start-job(job-xml-name=JOB_XML_NAME,properties={PROPERTY=VALUE})
Stop a Batch Job
You can stop a running batch job by providing its execution ID.
/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:stop-job(execution-id=EXECUTION_ID)
View Batch Job Execution Details
You can view the details of batch job executions. You must use the include-runtime=true
parameter on the read-resource
operation in order to see this runtime information.
/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:read-resource(recursive=true,include-runtime=true)
{
"outcome" => "success",
"result" => {"job" => {"import-file" => {
"instance-count" => 2,
"running-executions" => 0,
"execution" => {
"2" => {
"batch-status" => "COMPLETED",
"create-time" => "2016-04-11T22:03:12.708-0400",
"end-time" => "2016-04-11T22:03:12.718-0400",
"exit-status" => "COMPLETED",
"instance-id" => 58L,
"last-updated-time" => "2016-04-11T22:03:12.719-0400",
"start-time" => "2016-04-11T22:03:12.708-0400"
},
"1" => {
"batch-status" => "FAILED",
"create-time" => "2016-04-11T21:57:17.567-0400",
"end-time" => "2016-04-11T21:57:17.596-0400",
"exit-status" => "Error : org.hibernate.exception.ConstraintViolationException: could not execute statement",
"instance-id" => 15L,
"last-updated-time" => "2016-04-11T21:57:17.597-0400",
"start-time" => "2016-04-11T21:57:17.567-0400"
}
}
}}}
}
Manage Batch Jobs from the Management Console
To manage batch jobs from the management console, navigate to the Runtime tab, select the server, and select Subsystems
Restart a Batch Job
Restart a STOPPED
or FAILED
job by selecting the most recent execution of the job instance in the table and clicking Restart
.
Start a Batch Job
Start a new execution of a batch job by selecting the job from the table and clicking Start
.
Stop a Batch Job
Stop a running batch job by selecting the execution in the table and clicking Stop
.
View Batch Job Execution Details
Details of a job execution are shown in the Job Status section once the execution is selected in the table.
21.3. Configure Security for Batch Jobs
You can configure the batch-jberet
subsystem to run batch jobs with an Elytron security domain. This allows batch jobs to be securely suspended and resumed by the same secured identity. For example, a secured RESTful endpoint is created to initiate batch jobs using the batch-jberet
subsystem. If both the RESTful endpoint and batch-jberet
subsystem were secured using the same security domain, or the batch-jberet
security domain trusted the RESTful endpoint’s security domain, batch jobs initiated in this manner could be securely paused and resumed by the same secured identity.
Use the following management CLI command to update the security-domain
attribute to configure security for batch jobs.
/subsystem=batch-jberet:write-attribute(name=security-domain, value=ExampleDomain) reload
Batch jobs require the org.wildfly.extension.batch.jberet.deployment.BatchPermission
permission. It provides start
, stop
, restart
, abandon
, and read
permissions that align with javax.batch.operations.JobOperator
. The default-permission-mapper
mapper provides the org.wildfly.extension.batch.jberet.deployment.BatchPermission
permission.