4.1.1. Architecture Overview¶

Table of contents

Configuration of batch application
Batch type
Process flow of batch application
Listener used in the batch application
Minimum listener configuration
How to specify a listener

4.1.1.1. Configuration of batch application ¶

JSR352(external site) is required for the execution of a batch application compliant with JSR352(external site). The implementation will mainly be selected from the following two, the use of jBeret(external site) is recommended due to the extensive documentation and ease with which libraries can be obtained from Maven Central.

The configuration is shown below.

../../../../_images/jsr352-configuration-diagram.png

Important

Since using the temporary area of JobContext and StepContext (TransientUserData) is the same as storing the value in the global area, the temporary area must not be used on the application side.

Since the temporary area of StepContext is used to share values in the steps with StepScoped, the temporary area of StepContext cannot be used on the application side.

Tip

Since the architecture of JSR352-compliant Batch Application conforms to the configuration defined by JSR352(external site), the architecture is different from the handler-based architecture, as described in the Architecture .

In JSR352-compliant Batch Application, traverse processing such as those performed by the handler (log output and transaction control, etc.) is realized by using a listener defined by JSR352(external site)

However, the listener is started at a predetermined timing, and is different from the handler in that it does not directly process the input and output. Therefore, the listener cannot filter and convert input values, such as those realized by the handler.

4.1.1.2. Batch type ¶

There are two types of batch implementation methods in JSR352(external site), Batchlet and Chunk. The type of implementation that is appropriate to use should be determined for each batch with reference to the following.

Batchlet

Implements batchlet type in the case of task oriented batches.

For example, processes that fetch files from an external system or completes processing with 1 SQL statement.

Chunk: Implements chunk-type batch to execute processes that read records from input data sources such as files and databases and executes business processes.

4.1.1.3. Process flow of batch application ¶

4.1.1.3.1. Batchlet ¶

The process flow of Batchlet type batch application is shown below.

Batch Runtime of JSR352 calls NablarchStepListenerExecutor as the callback process before execution of batchlet step.
Sequentially executes the listener before executing the batchlet step.
Batchlet is executed from the Batch Runtime of JSR352.
Batchlet executes business logic is executed. (For the responsibility assignment of Batchlet, refer to the Batchlet responsibility assignment).
Batch Runtime of JSR352 calls NablarchStepListenerExecutor as the callback process after execution of batchlet step.
Sequentially executes the listener after executing the batchlet step. (Executes in the reverse order of No 2)

4.1.1.3.2. Chunk ¶

The process flow of Chunk type batch application is shown below.

Batch Runtime in JSR352 calls NablarchStepListenerExecutor as the callback process before execution of chunk step.
Sequentially executes the listener before executing the chunk step.
ItemReader of chunk step is executed from the Batch Runtime of JSR352.|br| ItemReader reads data from the input data source.
ItemProcessor of chunk step is executed from the Batch Runtime of JSR352.|br|
ItemProcessor executes the business logic using Form and Entity.|br| * Writing and updating of data to the database are not performed in this step.
Batch Runtime of JSR352 calls NablarchItemWriteListenerExecutor as the callback process before execution of the ItemWriter.
Sequentially executes the listener before executing the ItemWriter.
ItemWriter of chunk step is executed from the Batch Runtime of JSR352.|br| ItemWriter performs results reflection processing, such as registering (updating, deleting) to a table and file output processing.
Batch Runtime of JSR352 calls NablarchItemWriteListenerExecutor as the callback process after execution of ItemWriter.
Sequentially executes the listener after executing the ItemWriter. (Execute in the reverse order of No 7).
Batch Runtime of JSR352 calls NablarchStepListenerExecutor as the callback process after execution of chunk step.
Sequentially executes the listener after executing the Chunk step. (Executes in the reverse order of No 2)

No 3 to No 10 are executed repeatedly until the data of the input data source is finished.

For the responsibility assignment of chunk step, see responsibility assignment of Chunk

4.1.1.3.3. Process flow when an exception (including error) occurs ¶

If an exception occurs during batch execution, Nablarch does not catch the exception and exception handling is performed on the implementation side of JSR352. Note that this is a specific behavior for JSR352-compliant batch application and is different from other platforms (Web application and Nablarch Batch Application, etc.).

Tip

The reason why JSR352-compliant batch application adopted such an architecture is as follows.

JSR352-compliant batch applications provide only components for using Nablarch in JSR352, and execution control is carried out by JSR352 implementation. For this reason, it is not possible to catch and handle all exceptions with Nablarch, and this policy is adopted to avoid complex designs that will be required if exception control is distributed between Nablarch and JSR352.

4.1.1.3.3.1. Batch status when an exception occurs ¶

As described above, all controls when an exception occurs are performed by the implementation of JSR352. Refer to the specification of JSR352(external site) for the batch status (batch status and exit status) when an exception occurs. Retry and continuation status according to the exception type are operations in accordance with the job definition. For details of the job definition, refer to the specification of JSR352(external site).

For the return code that is returned by the Java process after the exception, see Fault monitoring.

4.1.1.3.3.2. Log output ¶

The information of the exception caught by JSR352 implementation is output as a log by JSR352 implementation. Configure (configuration such as format and output destination) the log by referring to the logging framework manual used by JSR352 implementation.

Error logs, etc. explicitly output by the application can be output to the same log file as that of JSR352 by unifying JSR352 implementation and logging framework using log Adapter.

4.1.1.4. Listener used in the batch application ¶

The batch application compliant with JSR352(external site) implements the equivalent of Nablarch handler using the listener defined in the JSR352(external site) specification.

The following listeners are provided as standard.

Job level listener

Listener that is called back immediately before starting and ending the job

Step level listener

Listener that is called back before and after executing the step

Listener of ItemWriter level

Listener that is called back before and after executing the`ItemWriter`

Listener to output the progress log of chunk (deprecated) (output progress log using Contents output in the progress log)
Listener that performs transaction control

Tip

The specification that the execution order for the listeners specified in JSR352(external site) is not guaranteed when multiple listeners are configured. For this reason, Nablarch supports the execution of listeners in the specified order by performing the following actions.

For each level of listener, configure only listeners for which the execution order of listeners is guaranteed
Fetches the listener list from the System Repository for which the execution order of the listeners is guaranteed and executes the listener in the order defined.

For information on how to define the listeners, see How to specify a listener.

4.1.1.5. Minimum listener configuration ¶

The minimum listener configuration is described below. If the project requirements cannot be met with this configuration, take measures such as adding listeners.

Minimum listener configuration of job level¶
No.	Listener	Process immediately before starting a job	Process immediately before finishing a job
1	Listener that outputs the launch and end logs of the job	Outputs the job name that is to be started to the log.	Outputs the job name and batch status to the log.

Minimum listener configuration of step level¶
No.	Listener	Process before step execution	Process after step execution
1	Listener that outputs the start and end logs of the job	Outputs the name of the executed step to the log.	Outputs the step name and step status to the log.
2	Listener that connects to the database	Gets the DB connection.	Releases the DB connection.
3	Listener that performs transaction control	Begins the transaction.	Ends (commits or rollbacks) the transaction.

ItemWriter level minimum listener configuration¶
No.	Listener	Process before execution of ItemWriter	Process after execution of ItemWriter
1	Listener that performs transaction control [1]		Ends (commits or rollbacks) the transaction.

[1]	Transaction control performed by the ItemWriter level listener is performed for the transaction started at the step level.

4.1.1.6. How to specify a listener ¶

This section describes how to define a listener list for each level.

The steps required to define a listener list are as follows:

Configure the listeners for which the execution order of the listeners is guaranteed in the xml file that represents the job definition specified in JSR352(external site).
Configure the listener list in the component configuration file.

Configure in the job definition file

<job id="chunk-integration-test" xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="1.0">
  <listeners>
    <!-- Job-level listener -->
    <listener ref="nablarchJobListenerExecutor" />
  </listeners>

  <step id="myStep">
    <listeners>
      <!-- Step-level listener -->
      <listener ref="nablarchStepListenerExecutor" />
      <!-- ItemWriter level listener-->
      <listener ref="nablarchItemWriteListenerExecutor" />
    </listeners>

    <chunk item-count="10">
      <reader ref="stringReader">
        <properties>
          <property name="max" value="25" />
        </properties>
      </reader>
      <processor ref="createEntityProcessor" />
      <writer ref="batchOutputWriter" />
    </chunk>
  </step>
</job>

Configure in the component configuration file

<!-- Default job-level listener list -->
<list name="jobListeners">
  <component class="nablarch.fw.batch.ee.listener.job.JobProgressLogListener" />
  <component class="nablarch.fw.batch.ee.listener.job.DuplicateJobRunningCheckListener">
    <property name="duplicateProcessChecker" ref="duplicateProcessChecker" />
  </component>
</list>

<!-- Default step-level listener list -->
<list name="stepListeners">
  <component class="nablarch.fw.batch.ee.listener.step.StepProgressLogListener" />
  <component class="nablarch.fw.batch.ee.listener.step.DbConnectionManagementListener">
    <property name="dbConnectionManagementHandler">
      <component class="nablarch.common.handler.DbConnectionManagementHandler" />
    </property>
  </component>
  <component class="nablarch.fw.batch.ee.listener.step.StepTransactionManagementListener" />
</list>

<!-- Default ItemWriter level listener list -->
<list name="itemWriteListeners">
  <component
      class="nablarch.fw.batch.ee.listener.chunk.ChunkProgressLogListener" />
  <component
      class="nablarch.fw.batch.ee.listener.chunk.ItemWriteTransactionManagementListener" />
</list>

<!-- Overwriting the default job-level listener list -->
<list name="sample-job.jobListeners">
  <component class="nablarch.fw.batch.ee.listener.job.JobProgressLogListener" />
</list>

<!-- Overwriting the default step-level listener list -->
<!-- This configuration is applied when executing the "sample-step" -->
<list name="sample-job.sample-step.stepListeners">
  <component class="nablarch.fw.batch.ee.listener.step.StepProgressLogListener" />
</list>

Points

Set the component name for the listener list of the default job level as jobListeners.
Set the component name for the listener list of the default step-level as stepListeners.
Set the component name for the listener list of the default ItemWriter level as itemWriteListeners.
When overwriting the definition of the default listener list, set the component name to “job name + ”.” + component name to be overwritten”.
For example, when overwriting the definition of job-level with “sample-job”, define a listener list with the component name as sample-job.jobListeners.
To overwrite the default listener list definition in a specific step, set the component name to “job name + ”.” + step name + ”.” + component name to be overwritten”.
For example, to overwrite the default listener list definition of the step-level with the “sample-step” defined in the “sample-job”, define the listener list with the component name as sample-job.sample-step.stepListeners.
The listener list that can be overwritten in a specific step are only the listener lists of the step level and ItemWriter level.