type=page
status=published
title=Batch Processing in Java EE
next=batch-processing003.html
prev=batch-processing001.html
~~~~~~
= Batch Processing in Java EE


[[BCGGIBHA]]

[[batch-processing-in-java-ee]]
Batch Processing in Java EE
---------------------------

This section lists the components of the batch processing framework in
Java EE and provides an overview of the steps you have to follow to
create a batch application.

The following topics are addressed here:

* link:#BABEAFJI[The Batch Processing Framework]
* link:#BABCGDHJ[Creating Batch Applications]
* link:#BABDGDJB[Elements of a Batch Job]
* link:#BABHJEJC[Properties and Parameters]
* link:#BABHJGDH[Job Instances and Job Executions]
* link:#BABBFGEF[Batch and Exit Status]

[[BABEAFJI]]

[[the-batch-processing-framework]]
The Batch Processing Framework
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Java EE includes a batch processing framework that consists of the
following elements:

* A batch runtime that manages the execution of jobs
* A job specification language based on XML
* A Java API to interact with the batch runtime
* A Java API to implement steps, decision elements, and other batch
artifacts

Batch applications in Java EE contain XML files and Java classes. The
XML files define the structure of a job in terms of batch artifacts and
the relationships between them. (A batch artifact is a part of a
chunk-oriented step, a task-oriented step, a decision element, or
another component of a batch application). The Java classes implement
the application logic of the batch artifacts defined in the XML files.
The batch runtime parses the XML files and loads the batch artifacts as
Java classes to run the jobs in a batch application.

[[BABCGDHJ]]

[[creating-batch-applications]]
Creating Batch Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The process for creating a batch application in Java EE is the
following.

1.  Design the batch application.
1.  Identify the input sources, the format of the input data, the
desired final result, and the required processing phases.
2.  Organize the application as a job with chunk-oriented steps,
task-oriented steps, and decision elements. Determine the dependencies
between them.
3.  Determine the order of execution in terms of transitions between
steps.
4.  Identify steps that can run in parallel and steps that can run in
more than one thread.
2.  Create the batch artifacts as Java classes by implementing the
interfaces specified by the framework for steps, decision elements, and
so on. These Java classes contain the code to read data from input
sources, format items, process items, and store results. Batch artifacts
can access context objects from the batch runtime using dependency
injection.
3.  Define jobs, steps, and their execution flow in XML files using the
Job Specification Language. The elements in the XML files reference
batch artifacts implemented as Java classes. The batch artifacts can
access properties declared in the XML files, such as names of files and
databases.
4.  Use the Java API provided by the batch runtime to launch the batch
application.

The following sections describe in detail how to use the components of
the batch processing framework in Java EE to create batch applications.

[[BABDGDJB]]

[[elements-of-a-batch-job]]
Elements of a Batch Job
~~~~~~~~~~~~~~~~~~~~~~~

A batch job can contain one or more of the following elements:

* Steps
* Flows
* Splits
* Decision elements

Steps are described in
link:batch-processing001.html#BCGJDEEH[Introduction to Batch Processing],
and can be chunk-oriented or task-oriented. Chunk-oriented steps can be
partitioned steps. In a partitioned chunk step, the processing of one
item does not depend on other items, so these steps can run in more than
one thread.

A flow is a sequence of steps that execute as a unit. A sequence of
related steps can be grouped together into a flow. The steps in a flow
cannot transition to steps outside the flow. The flow transitions to the
next element when its last step completes.

A split is a set of flows that execute in parallel; each flow runs on a
separate thread. The split transitions to the next element when all its
flows complete.

Decision elements use the exit status of the previous step to determine
the next step or to terminate the batch job.

[[BABHJEJC]]

[[properties-and-parameters]]
Properties and Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~

Jobs and steps can have a number of properties associated with them. You
define properties in the job definition file, and batch artifacts access
these properties using context objects from the batch runtime. Using
properties in this manner enables you to decouple static parameters of
the job from the business logic and to reuse batch artifacts in
different job definition files.

Specifying properties is described in
link:batch-processing004.html#BCGDDBBG[Using the Job Specification
Language], and accessing properties in batch artifacts is described in
link:batch-processing005.html#BCGHDHGH[Creating Batch Artifacts].

Java EE applications can also pass parameters to a job when they submit
it to the batch runtime. This enables you to specify dynamic parameters
that are only known at runtime. Parameters are also necessary for
partitioned steps, since each partition needs to know, for example, what
range of items to process.

Specifying parameters when submitting jobs is described in
link:batch-processing006.html#BCGCAHCB[Submitting Jobs to the Batch
Runtime]. Specifying parameters for partitioned steps and accessing them
in batch artifacts is demonstrated in
link:batch-processing009.html#BCGFCACD[The phonebilling Example
Application].

[[BABHJGDH]]

[[job-instances-and-job-executions]]
Job Instances and Job Executions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A job definition can have multiple instances, each with different
parameters. A job execution is an attempt to run a job instance. The
batch runtime maintains information about job instances and job
executions, as described in
link:batch-processing006.html#BCGIBGFC[Checking the Status of a Job].

[[BABBFGEF]]

[[batch-and-exit-status]]
Batch and Exit Status
~~~~~~~~~~~~~~~~~~~~~

The state of jobs, steps, splits, and flows is represented in the batch
runtime as a batch status value. Batch status values are listed
link:#BCGJBGDF[Table 58-1]. They are represented as strings.

[[sthref267]][[BCGJBGDF]]


*Table 58-1 Batch Status Values*

[width="50%",cols="15%,35%"]
|============================================================
|*Value* |*Description*
|`STARTING` |The job has been submitted to the batch runtime.
|`STARTED` |The job is running.
|`STOPPING` |The job has been requested to stop.
|`STOPPED` |The job has stopped.
|`FAILED` |The job finished executing because of an error.
|`COMPLETED` |The job finished executing successfully.
|`ABANDONED` |The job was marked abandoned.
|============================================================


Java EE applications can submit jobs and access the batch status of a
job using the `JobOperator` interface, as described in
link:batch-processing006.html#BCGCAHCB[Submitting Jobs to the Batch
Runtime]. Job definition files can refer to batch status values using
the Job Specification Language (JSL), as described in
link:batch-processing004.html#BCGDDBBG[Using the Job Specification
Language]. Batch artifacts can access batch status values using context
objects, as described in link:batch-processing005.html#BCGCJEEF[Using the
Context Objects from the Batch Runtime].

For flows, the batch status is that of its last step. For splits, the
batch status is the following:

* `COMPLETED`: If all its flows have a batch status of `COMPLETED`
* `FAILED`: If any flow has a batch status of `FAILED`
* `STOPPED`: If any flow has a batch status of `STOPPED`, and no flows
have a batch status of `FAILED`

The batch status for jobs, steps, splits, and flows is set by the batch
runtime. Jobs, steps, splits, and flows also have an exit status, which
is a user-defined value based on the batch status. You can set the exit
status inside batch artifacts or in the job definition file. You can
access the exit status in the same manner as the batch status, described
above. The default value for the exit status is the same as the batch
status.
