Batch (JSR-352) Subsystem Configuration - Latest WildFly Documentation

Overview

The batch subsystem is used to configure an environment for running batch applications. WildFly uses JBeret for it's batch implementation. Specific information about JBeret can be found in the user guide. The resource path, in CLI notation, for the subsystem is subsystem=batch-jberet.

Default Subsystem Configuration

For up to date information about subsystem configuration options see http://wildscribe.github.io/.

Security

A new security-domain attribute was added to the batch-jberet subsystem to allow batch jobs to be executed under that security domain. Jobs that are stopped as part of a suspend operation will be restarted on execution of a resume with the original user that started job.

There was a org.wildfly.extension.batch.jberet.deployment.BatchPermission added to allow a security restraint to various batch functions. The following functions can be controlled with this permission.

start
stop
restart
abandon
read

The read function allows users to use the getter methods from the javax.batch.operations.JobOperator or read the batch-jberet deployment resource, for example /deployment=my.war/subsystem=batch-jberet:read-resource.

Deployment Descriptors

There are no deployment descriptors for configuring a batch environment defined by the JSR-352 specification. In WildFly you can use a jboss-all.xml deployment descriptor to define aspects of the batch environment for your deployment.

In the jboss-all.xml deployment descriptor you can define a named job repository, a new job repository and/or a named thread pool. A named job repository and named thread pool are resources defined on the batch subsystem. Only a named thread pool is allowed to be defined in the deployment descriptor.

Example Named Job Repository and Thread Pool

<jboss umlns="urn:jboss:1.0">
    <batch xmlns="urn:jboss:batch-jberet:1.0">
      <job-repository>
        <named name="batch-ds"/>
      </job-repository>
      <thread-pool name="deployment-thread-pool"/>
    </batch>
</jboss>

Example new Job Repository

<jboss umlns="urn:jboss:1.0">
    <batch xmlns="urn:jboss:batch-jberet:1.0">
        <job-repository>
            <jdbc jndi-name="java:jboss/datasources/ExampleDS"/>
        </job-repository>
    </batch>
</jboss>

Deployment Resources

Some subsystems in WildFly register runtime resources for deployments. The batch subsystem registers jobs and executions. The jobs are registered using the job name, this is not the job XML name. Executions are registered using the execution id.

Batch application in a standalone server

[standalone@localhost:9990 /] /deployment=batch-jdbc-chunk.war/subsystem=batch-jberet:read-resource(recursive=true,include-runtime=true)
{
    "outcome" => "success",
    "result" => {"job" => {
        "reader-3" => {
            "instance-count" => 1,
            "running-executions" => 0,
            "execution" => {"1" => {
                "batch-status" => "COMPLETED",
                "create-time" => "2015-08-07T15:37:06.416-0700",
                "end-time" => "2015-08-07T15:37:06.519-0700",
                "exit-status" => "COMPLETED",
                "instance-id" => 1L,
                "last-updated-time" => "2015-08-07T15:37:06.519-0700",
                "start-time" => "2015-08-07T15:37:06.425-0700"
            }}
        },
        "reader-5" => {
            "instance-count" => 0,
            "running-executions" => 0,
            "execution" => undefined
        }
    }}
}

The batch subsystem resource on a deployment also has 3 operations to interact with batch jobs on the selected deployment. There is a start-job, stop-job and restart-job operation. The execution resource also has a stop-job and restart-job operation.

Example start-job

[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:start-job(job-xml-name=simple, properties={writer.sleep=5000})
{
    "outcome" => "success",
    "result" => 1L
}

Example stop-job

[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:stop-job(execution-id=2)

Example restart-job

[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:restart-job(execution-id=2)
{
    "outcome" => "success",
    "result" => 3L
}

Result of resource after the 3 executions

[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:read-resource(recursive=true, include-runtime=true)
{
    "outcome" => "success",
    "result" => {"job" => {"chunkPartition" => {
        "instance-count" => 2,
        "running-executions" => 0,
        "execution" => {
            "1" => {
                "batch-status" => "COMPLETED",
                "create-time" => "2015-08-07T15:41:55.504-0700",
                "end-time" => "2015-08-07T15:42:15.513-0700",
                "exit-status" => "COMPLETED",
                "instance-id" => 1L,
                "last-updated-time" => "2015-08-07T15:42:15.513-0700",
                "start-time" => "2015-08-07T15:41:55.504-0700"
            },
            "2" => {
                "batch-status" => "STOPPED",
                "create-time" => "2015-08-07T15:44:39.879-0700",
                "end-time" => "2015-08-07T15:44:54.882-0700",
                "exit-status" => "STOPPED",
                "instance-id" => 2L,
                "last-updated-time" => "2015-08-07T15:44:54.882-0700",
                "start-time" => "2015-08-07T15:44:39.879-0700"
            },
            "3" => {
                "batch-status" => "COMPLETED",
                "create-time" => "2015-08-07T15:45:48.162-0700",
                "end-time" => "2015-08-07T15:45:53.165-0700",
                "exit-status" => "COMPLETED",
                "instance-id" => 2L,
                "last-updated-time" => "2015-08-07T15:45:53.165-0700",
                "start-time" => "2015-08-07T15:45:48.163-0700"
            }
        }
    }}}
}

Pro Tip

You can filter jobs by an attribute on the execution resource with the query operation.

View all stopped jobs

/deployment=batch-chunk.war/subsystem=batch-jberet/job=*/execution=*:query(where=["batch-status", "STOPPED"])

As with all operations you can see details about the operation using the :read-operation-description operation.

Tab completion

Don't forget that CLI has tab completion which will complete operations and attributes (arguments) on operations.

Example start-job operation description

[standalone@localhost:9990 /] /deployment=batch-chunk.war/subsystem=batch-jberet:read-operation-description(name=start-job)
{
    "outcome" => "success",
    "result" => {
        "operation-name" => "start-job",
        "description" => "Starts a batch job.",
        "request-properties" => {
            "job-xml-name" => {
                "type" => STRING,
                "description" => "The name of the job XML file to use when starting the job.",
                "expressions-allowed" => false,
                "required" => true,
                "nillable" => false,
                "min-length" => 1L,
                "max-length" => 2147483647L
            },
            "properties" => {
                "type" => OBJECT,
                "description" => "Optional properties to use when starting the batch job.",
                "expressions-allowed" => false,
                "required" => false,
                "nillable" => true,
                "value-type" => STRING
            }
        },
        "reply-properties" => {"type" => LONG},
        "read-only" => false,
        "runtime-only" => true
    }
}