Parallel job manager application programming interfaces (APIs)

Parallel job manager (PJM) SPIs in previous releases are now APIs. They are packaged as part of an application.

Parameterizer API

The Parameterizer API divides the top-level job into multiple subordinate jobs, also known as sub jobs. The Parameterizer API determines the number of subordinate jobs to create and the input properties that are passed to each subordinate job. Typically, the input properties contain information for which data chunks process a particular subordinate job. Implementation of the Parameterizer API is mandatory.

A default Parameterizer API implementation provides the basic functions of the generic Parameterizer API. To invoke this implementation, set the com.ibm.websphere.batch.parallel.parameterizer property to a value of com.ibm.ws.batch.parallel.BuiltInParameterizer in the XML Job Control Language (xJCL) file. To specify the number of subordinate jobs, set the com.ibm.wsspi.batch.parallel.jobs input property to N, where N is the number of the subordinate job. To specify a unique property to a specific subordinate job instance, use the property, com.ibm.wsspi.batch.parallel.prop.<property_name>.<subordinate_job>=<value>, where subordinate_job is the subordinate job instance, 1<= subordinate job < N. All other properties in the <property_name>= <value> format are visible to all subordinate jobs.

Synchronization API

The Synchronization API gives you control during the various lifecycle stages of the logical transaction. Access these lifecycle stages through the following methods: begin(), beforeCompletion(), and afterCompletion(), which the batch container calls in that order when a top-level job and all of its subordinate jobs complete successfully. If a failure occurs in a subordinate job or the top-level job, the logical transaction is rolled back. You can force a logical transaction rollback by throwing the RollbackLogicalTXException exception out of your beforeCompletion() implementation.

In a logical transaction rollback scenario, the rollBack() method is called. In the context of a logical transaction, rollback does not imply a rollback of updates to the managed resources of a global transaction. Rather, rollback is an opportunity for your application to perform application-specific cleanup on its own. You can also customize the restart behavior of the subordinate jobs when the top-level job is restarted.

SubJobCollector API

The SubJobCollector API collects information related to a subordinate job execution. In a typical implementation, progress information about a subordinate job is stored as an externalizable object within the subordinate job context. When the batch container starts the collector API, the information previously stored within the subordinate job context is returned.

SubJobAnalyzer API

The SubJobAnalyzer API is used to analyze information collected previously by using the SubJobCollector API. In a typical implementation, the SubJobAnalyzer API is used to aggregate information obtained from all subordinate jobs to determine the consolidated return code for the top-level job. The SubJobAnalyzer API is called during checkpoint processing and on job completion.

Context objects

The batch runtime environment provides context objects that offer a common work area among APIs and batch application programming model artifacts. A context object allows user code to save and retrieve a Java™ Object and share it within the context scope. The batch runtime environment ensures appropriate cleanup of context objects and end of scope. There are two context object types:
  • ParallelJobManagerContext: Exists in the scope of a parallel job. The Parameterizer, SubJobAnalyzer, and Synchronization APIs all have access to this context for a given parallel job instance.
  • SubJobContext: Exists in the scope of a subordinate job. The SubJobCollector, and batch application programming model artifacts, BatchDataStream, BatchJobStepInterface, CheckpointPolicyAlgorithm, and ResultsAlgorithm all have access to this context for a given subordinate job instance.