4.2.1. Architecture Overview

The Nablarch batch application provides a function to build a batch process that repeatedly executes the process for each data record stored in the DB or file.

The Nablarch batch application is divided into the following two types:

On-demand batch
Launches the process periodically, that is, daily or monthly, and executes the batch process.
Resident batch
The process continues to run and executes batch process at regular intervals. For example, it is used when request data created by online processing is batch-processed periodically.

Important

Even if a resident batch is executed by multi-threading, there is a possibility that a delay may occur in importing the request data as other threads may wait for threads that are processed slowly to end.

For this reason, it is recommended that instead of the resident batch, Messaging Using Tables as Queues, which does not cause the above problems, be used in new development projects.

Also, in existing projects, the resident batch can be operated without any changes, but if there is a possibility for the above problem to occur (if it is already occurring), consider changing to Messaging Using Tables as Queues.

4.2.1.1. Configuration of Nablarch Batch Application

The Nablarch batch application runs as a standalone application launched directly from the java command. Configuration of the Nablarch batch application is shown below.

../../../../_images/application_structure.png
Common Launcher (Main)
Main class is the starting point of Nablarch batch application. Launched directly from the java command, initializes the system repository and log, and executes the handler queue.

4.2.1.2. Specify action and request ID based on request path

In the Nablarch batch application, specify the action to be executed and request ID with the command line argument (-requestPath).

# Format
-requestPath=Action class name/request ID

# Example
-requestPath=com.sample.SampleBatchAction/BATCH0001

The request ID is used as an identifier of each batch process. When multiple processes executing the same business action class are launched, the request ID is used as an identifier.

4.2.1.3. Process flow of Nablarch batch application

The process flow starting from the Nablarch batch application reading the input data to returning the process result is shown below.

../../../../_images/batch-flow.png
  1. The common start-up launcher (Main) executes the handler queue.
  2. DataReader reads the input data and provides the data records one by one.
  3. DispatchHandler configured in the handler queue specifies the action class to be processed based on the request path specified by the command line argument (-requestPath) and adds it to the end of the handler queue.
  4. The action class executes business logic for each data record using a form class and an entity class.
  5. The action class returns Result, which shows the results.
  6. Repeat steps 2-5 until there is no more data to process.
  7. StatusCodeConvertHandler (StatusCodeConvertHandler) set in the handler queue converts the status code of the process result into the process exit code, and the process exit code is returned as the processing result of the batch application.

4.2.1.4. Handlers used in the Nablarch batch application

Nablarch provides several handlers required for building batch applications. Build the handler queue in accordance with the requirements of the project. (a custom handler will have to be created for the project depending on the requirements)

For details of each handler, refer to the links.

Handlers that convert request and response
Handlers that control the execution of the batch
Handlers associated with database
Handler associated with error handling
Others

4.2.1.4.1. Minimum handler configuration for on-demand batch

When building an on-demand batch, the minimum required handler queue is as below:

With this as the base, add standard handlers of Nablarch or custom handlers created in the project according to the project requirements.

If you connect to DB, this is the base.

Minimum handler configuration for on-demand batch (with DB connection)
No. Handler Thread Request process Response process Exception handling
1 Status Code → Process End Code Conversion Handler Main   Converts status code to process exit code.  
2 Global Error Handler Main     Outputs log in the case of a runtime exception or error.
3 Database Connection Management Handler (for initial processing/end processing) Main Gets the DB connection. Releases the DB connection.  
4 Transaction Control Handler (for initial processing/end processing) Main Begins the transaction. Commit the transaction. Roll back a transaction.
5 Request Dispatch Handler Main Determine the action to invoke based on the command line arguments.    
6 Multi-thread Execution Control Handler Main Creates a sub thread and execute the process of the subsequent handler in parallel. Waits for normal termination of all threads. Waits for the current thread to complete and rethrows the cause exception.
7 Database Connection Management Handler (for business process) Sub Gets the DB connection. Releases the DB connection.  
8 Transaction Loop Control Handler Sub Begin a business transaction. Commits the business transaction at each commit interval. The loop is continued if the data to be processed is present in the data reader. Rolls back a business transaction.
9 Data Read Handler Sub Uses a data reader to read records one by one and pass it as an argument of the subsequent handler. Also, the execution ID is numbered.   Outputs the read record as a log, and resends the original exception.

If you don’t connect to DB, you don’t need DB connection-related handlers and you don’t need transaction control in loop control handlers, so this is the base.

Minimum handler configuration for on-demand batch (without DB connection)
No. Handler Thread Request process Response process Exception handling
1 Status Code → Process End Code Conversion Handler Main   Converts status code to process exit code.  
2 Global Error Handler Main     Outputs log in the case of a runtime exception or error.
3 Request Dispatch Handler Main Determine the action to invoke based on the command line arguments.    
4 Multi-thread Execution Control Handler Main Creates a sub thread and execute the process of the subsequent handler in parallel. Waits for normal termination of all threads. Waits for the current thread to complete and rethrows the cause exception.
5 Loop Control Handler Sub   The loop is continued if the data to be processed is present in the data reader.  
6 Data Read Handler Sub Uses a data reader to read records one by one and pass it as an argument of the subsequent handler. Also, the execution ID is numbered.   Outputs the read record as a log, and resends the original exception.

4.2.1.4.2. Minimum handler configuration of resident batch

When building a resident batch, the minimum required handler queue is as below:

With this as the base, add standard handlers of Nablarch or custom handlers created in the project according to the project requirements.

The minimum handler configuration of the resident batch is the same as the on-demand batch excluding the point that the below handlers are added to the main thread.

Minimum handler configuration of resident batch
No. Handler Thread Request process Response process Exception handling
1 Status Code → Process End Code Conversion Handler Main   Converts status code to process exit code.  
2 Thread Context Variable Delete Handler Main   Deletes all the values configured on the thread local with Thread Context Variable Management Handler.  
3 Global Error Handler Main     Outputs log in the case of a runtime exception or error.
4 Thread Context Variable Management Handler Main Initializes thread context variables such as request ID and user ID from command line arguments.    
5 Retry Handler Main     Catches a runtime exception that can be retried, and provided that the retry limit has not been reached, re-executes the subsequent handler.
6 Process Resident Handler Main Executes the subsequent handler repeatedly at each data monitoring interval. Continues the loop Performs log output and if a runtime exception is thrown, wraps to a retryable exception and sent. If an error is sent, it will be rethrow without any change
7 Process Stop Control Handler Main If the process stop flag of the request table is on, a process stop exception ( ProcessStop ) is sent out without performing the subsequent handler process.    
8 Database Connection Management Handler (for initial processing/end processing) Main Gets the DB connection. Releases the DB connection.  
9 Transaction Control Handler (for initial processing/end processing) Main Begins the transaction. Commit the transaction. Roll back a transaction.
10 Request Dispatch Handler Main Determine the action to invoke based on the command line arguments.    
11 Multi-thread Execution Control Handler Main Creates a sub thread and execute the process of the subsequent handler in parallel. Waits for normal termination of all threads. Waits for the current thread to complete and rethrows the cause exception.
12 Database Connection Management Handler (for business process) Sub Gets the DB connection. Releases the DB connection.  
13 Transaction Loop Control Handler Sub Begin a business transaction. Commits the business transaction at each commit interval. The loop is continued if the data to be processed is present in the data reader. Rolls back a business transaction.
14 Data Read Handler Sub Uses a data reader to read records one by one and pass it as an argument of the subsequent handler. Also, the execution ID is numbered.   Outputs the read record as a log, and rethrows the original exception.

4.2.1.5. Data reader used in the Nablarch batch application

Nablarch provides several data readers required for building batch applications. For details of each data reader, refer to the links.

Tip

If the above data readers cannot meet the project requirements, create a class that implements the DataReader interface in the project.

Important

Standard FileDataReader (read file) and ValidatableFileDataReader (read files with validation function) use General Data Format to access data. Do not use these data readers if you use Data Bind to access data.