Java EE 7 SDK

Samples Main Page

# The Payroll Batch Sample Application

This sample demonstrates how to use the `javax.batch.operations.JobOperator` interface to submit batch jobs.

## Description

This sample application demonstrates how to use the Batch Processing API (JSR 352) to submit batch jobs. A batch job is typically a long-running process that involves a sequence of steps. This sample processes a simple payroll by submitting a `payroll` job to the batch runtime using the `JobOperator.start()` method. This sample also demonstrates how to use the `ItemReader`, `ItemProcessor`, and `ItemWriter` interfaces.

The sample contains a singleton EJB that holds payroll records for a set of employees for three months. The singleton bean also holds the processed payroll records.

The job XML file for this sample specifies the `process` step with three batch artifacts:

- `SimpleItemReader` is an `ItemReader` implementation that reads input records. The batch runtime calls the `ItemReader.readItem()` method to read input records. `ItemReader` implementations can read input records from a variety of sources like databases, text files, other Java EE components, etc. The batch runtime hands each record read in an `ItemReader` to an `ItemProcessor`.

  In this sample, `SimpleItemReader` reads `PayrollInputRecord` objects from a singleton bean.

- `SimpleItemProcessor` is an `ItemProcessor` implementation that processes an input record and returns an output record. The batch runtime calls the `ItemProcessor.processItem()` method to process the records from the `ItemReader`.

  In this sample, `SimpleItemProcessor` receives `PayrollInputRecord` objects from the batch runtime, computes the net pay, and returns a `PayrollRecord` to the batch runtime. The batch runtime then uses an `ItemWriter` to store the results.

- `SimpleItemWriter` is an `ItemWriter` implementation that writes the output record to some data storage resource such as a database, a text file, or another Java EE component. The batch runtime calls the `ItemWriter.writeItems()` method to write the records processed by the `ItemWriter`.

  In this sample, `SimpleItemWriter` stores the processed `PayrollRecord` objects in a singleton bean.

This sample application uses the embedded JavaDB database service included with the Glassfish server.

The following is a list of servlets included in this sample:

URI pattern | Description
--- | ---
`/payroll/JobSubmitterServlet` | Displays payroll input records and allows starting a payroll processing job.

The application is built and deployed as a WAR file.

## Key Features

This sample application demonstrates the following key features:

- Defining a batch job using a job XML file. The batch job processes payroll records.
- Using the `ItemReader`, `ItemProcessor`, and `ItemWriter` interfaces describe the logic of a steps in the payroll job.
- Injecting `EJBs` and `JobContext` into implementations of the `ItemReader` and `ItemWriter` interfaces.
- Using the `JobOperator.start()` method to start a batch job.

## Building, Deploying, and Running the Application

Perform the following steps to build, deploy, and run the application:

1. Set up your build environment and configure the application server with which the build system has to work by following the common build instructions.
2. `samples_install_dir` is the sample application base directory. Go to: `samples_install_dir/javaee7/batch/payroll`.
3. Build the sample application by running the `mvn package` command from a command line terminal.
4. Deploy the sample application by running the `asadmin deploy --force target/payroll.war` command from a command line terminal.
5. The front page of this sample is at `http://localhost:8080/payroll/JobSubmitterServlet`.
   (The port number might vary.)
6. Use the `mvn clean` command from a command line terminal to clean up the target directory.
7. Undeploy the sample application by running the `asadmin undeploy payroll` command from a command line terminal.

## Troubleshooting

If you have problems when running the application, refer to the troubleshooting document.

Copyright © 1997-2013 Oracle and/or its affiliates. All rights reserved.