Administering Batch Jobs

This chapter provides procedures for administering batch jobs in the Payara Server environment by using the asadmin command-line utility.

Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.

About Batch Jobs

Payara Server provides a batch runtime for the scheduling and execution of batch jobs. Batch jobs are typically long-running, bulk-oriented tasks that contain a series of steps and can be executed without user interaction. Examples include billing, report generation, data format conversion, and image processing.

Batch applications submit jobs to the batch runtime and provide instructions about how and when to execute the steps. The batch runtime processes the steps as directed by job XML documents packaged with the applications and stores information about jobs in a job repository. In Payara Server, the job repository is a database.

For detailed information about batch jobs, batch processing, and the batch processing framework, see "Batch Processing" in The Jakarta Batch specifications. The specification defines the programming model for batch applications and the runtime for scheduling and executing batch jobs.

Viewing Batch Jobs

You can view detailed information about batch jobs, executions, and steps. Users who log in to the asadmin utility or to the Administration Console as administrator are the only users who can view details for all batch jobs submitted by all applications in the Payara Server environment.

To List Batch Jobs

Use the list-batch-jobs subcommand in remote mode to list batch jobs and job details.

  1. Ensure that the server is running.
    Remote subcommands require a running server.

  2. List batch jobs by using the list-batch-jobs subcommand.

To List Batch Jobs

This example lists batch jobs for the default server instance, server. Use list-batch-jobs -l to list additional details.

asadmin> list-batch-jobs
JOBNAME  INSTANCECOUNT
payroll  9
bonus    6
Command list-batch-jobs executed successfully.

You can also view the full syntax and options of the subcommand by typing asadmin help list-batch-jobs at the command line.

To List Batch Job Executions

When the batch runtime executes a job, the execution is given a unique execution ID. An execution ID is similar to a process ID. A new execution is created the first time a job is started and every time the existing execution is restarted.

Use the list-batch-job-executions subcommand in remote mode to list batch job executions and execution details.

  1. Ensure that the server is running. Remote subcommands require a running server.

  2. List batch job executions by using the list-batch-job-executions subcommand.

To List Batch Jobs Executions

This example lists batch job executions for the default server instance, server, and displays specific details. Use list-batch-job-executions -l to list additional details.

asadmin> list-batch-job-executions -o=jobname,executionid,batchstatus,exitstatus
JOBNAME  EXECUTIONID  BATCHSTATUS  EXITSTATUS
payroll  9            COMPLETED    COMPLETED
bonus    6            FAILED       FAILED
Command list-batch-job-executions executed successfully.

You can also view the full syntax and options of the subcommand by typing asadmin help list-batch-job-executions at the command line.

To List Batch Job Steps

A batch job consists of one or more steps. A step is an independent and sequential phase of a batch job.

Use the list-batch-job-steps subcommand in remote mode to list steps and step details for a specific batch job execution.

  1. Ensure that the server is running. Remote subcommands require a running server.

  2. List the execution ID of an execution by using the list-batch-job-executions subcommand.

  3. List steps for a specific batch job execution by using the list-batch-job-steps subcommand.

To List Batch Jobs Steps

This example lists batch job steps and specific step details for a job execution with the execution ID of 7. The target is the default server instance, server. Use list-batch-job-steps -l to list additional details.

Some lines of output are omitted from this example for readability.

asadmin> list-batch-job-steps o=stepname,stepid,batchstatus,stepmetrics 7
STEPNAME   STEPID   BATCHSTATUS   STEPMETRICS
prepare    7        COMPLETED     METRICNAME          VALUE
                                  READ_COUNT          8
                                  WRITE_COUNT         8
                                  PROCESS_SKIP_COUNT  0
process    8        COMPLETED     METRICNAME          VALUE
                                  READ_COUNT          8
                                  WRITE_COUNT         8
                                  PROCESS_SKIP_COUNT  0
...
Command list-batch-job-steps executed successfully.

You can also view the full syntax and options of the subcommand by typing asadmin help list-batch-job-steps at the command line.

Configuring the Batch Runtime

The batch runtime uses a data source and a managed executor service to execute batch jobs. The data source stores information about current and past jobs, and the managed executor service provides threads to jobs. Batch runtime configuration data is stored in the config element in domain.xml.

Payara Server provides a default data source and managed executor service for the execution of batch jobs. For the domain administration server (DAS), the default data source is jdbc/TimerPool and the default managed executor service is concurrent/defaultManagedExecutorService. If you create a standalone server instance or a standalone cluster, the default data source is jdbc/__default. You can configure the batch runtime to use different resources.

For more information about data sources, see Administering Database Connectivity. For more information about managed executor services, see Configuring Managed Executor Services.

To List the Batch Runtime Configuration

Use the list-batch-runtime-configuration subcommand in remote mode to display the configuration of the batch runtime.

  1. Ensure that the server is running. Remote subcommands require a running server.

  2. Display the configuration of the batch runtime by using the list-batch-runtime-configuration subcommand.

  3. If desired, use the get subcommand to view the attributes of the data source and managed executor service resources. For example (output omitted):

asdmin> get resources.jdbc-resource.jdbc/__TimerPool.*
...
asdmin> get resources.managed-executor-service.concurrent/__defaultManagedExecutorService.*
...

To List the Batch Job Runtime Configuration

This example lists the configuration of the batch runtime for the default server instance, server.

asadmin> list-batch-runtime-configuration
DATASOURCELOOKUPNAME     EXECUTORSERVICELOOKUPNAME
jdbc/__TimerPool         concurrent/__defaultManagedExecutorService
Command list-batch-runtime-configuration executed successfully.

You can also view the full syntax and options of the subcommand by typing asadmin help list-batch-runtime-configuration at the command line.

To Configure the Batch Runtime

Use the set-batch-runtime-configuration subcommand in remote mode to configure the batch runtime.

Do not change the data source after the first batch job has been submitted to the batch runtime for execution. If the data source must be changed, stop and restart the domain and then make the change before any jobs are started or restarted. However, once the data source has been changed, information stored in the previous data source becomes inaccessible.
The managed executor service can be changed after a batch job has been submitted to the batch runtime without affecting execution of the job.

  1. Ensure that the server is running.
    Remote subcommands require a running server.

  2. Configure the batch runtime by using the set-batch-runtime-configuration subcommand.

To Set Batch Runtime Configuration

This example configures the batch runtime for the default server instance, server, to use an existing managed executor service named concurrent/Executor1.

asadmin> set-batch-runtime-configuration --executorservicelookupname concurrent/Executor1
Command set-batch-runtime-configuration executed successfully.

You can also view the full syntax and options of the subcommand by typing asadmin help set-batch-runtime-configuration at the command line.

Defining a Schema name

Payara Server allows the ability to define the name of the database schema that will hold all batch job tables. This can be set via the Admin Console or using Asadmin CLI commands.

Defining a Schema name through the Admin Console

  1. Click on the instance or cluster to move to its configuration page.

  2. Select the Batch tab, and from there click on the Configuration sub-tab.

  3. Enter your desired value in the Database Schema Name field.

  4. Save your changes

Defining a Schema name using the Asadmin CLI

It’s possible to set the schema using the set-batch-runtime-configuration command.

The command requires you to specify the Executor or DataSource lookup name, which you can do with the -x or -d options respectively.

The command defaults to targeting the Admin Server instance (server), to target a different instance or cluster, use the --target option.

To specify the schema name, use the --schemaName option, or its shortcut -n.

An example can be seen below:

asadmin set-batch-runtime-configuration -d jdbc/__default --target cluster1 -n test

Specifying a Blank Schema Name

If you specify a blank schema name, then the schema name will depend on what database vendor is being used:

  • On MySQL, the test schema will be used

  • On H2, Derby, Oracle, DB2 and PostgreSQL the schema name will be the username of the JDBC connection pool resource associated with the JDBC resource to which JBatch is configured to use.

This behavior only applies if you explicitly specify the schema name as blank; the schema name will still default to APP if not overwritten.

Setting a Table Prefix and/or Suffix

Payara Server allows you to set the prefix and/or the suffix of the batch table name. This can be set via the Admin Console, or using Asadmin CLI commands.

The table prefix and suffix settings may be ignored by non-RDBMS based datastores.

Setting a Table Prefix and/or Suffix on the Admin Console

  1. Click on the instance or cluster to move to its configuration page.

  2. Select the Batch tab, and the Configuration sub-tab should load.

  3. Enter your desired values in the Table Prefix and Table Suffix fields.

  4. Save your changes

Setting a Table Prefix and/or Suffix using the Asadmin CLI

It’s possible to set the table prefix and/or suffix is set using the set-batch-runtime-configuration command. The command requires you to specify the Executor or DataSource lookup name, which you can do with the -x or -d options respectively.

The command defaults to targeting the Admin Server instance (server), to target a different instance or cluster, use the --target option.

  • To specify the prefix, use the --tablePrefix option.

  • To specify the table suffix, use the --tableSuffix option.

An example can be seen below:

asadmin set-batch-runtime-configuration -d jdbc/__default --target cluster1 --tablePrefix PRE --tableSuffix SFX

Database Support

You can configure any of the following RDBMS engines in the same way that you would configure it to use H2 (the default database engine used to manage the JBatch data sources):

  • MySQL

  • PostgreSQL

  • Oracle

  • IBM DB2

Configuration

On the Admin console:

  1. Create a Connection Pool:

    1. Navigate to Resources → JDBC → JDBC Connection Pools and click on New…​

    2. Give it a name in the Pool Name field, select the resource type from the Resource Type drop-down, and choose the Database Driver Vendor as either DB2, MySQL, Oracle, or PostgreSQL from the Database Driver Vendor menu.

    3. Set any further configuration options on the next page.

    4. Click Finish

  2. Create a JDBC Resource:

    1. Navigate to Resources → JDBC → JDBC Resources and click on New…​

    2. Give it a name in the JNDI Name field, and select the data source you just created from the Pool Name drop-down.

    3. Add any additional properties and select the targets for it to be enabled on.

    4. Click OK.

  3. Navigate to the Batch configuration page of the instance or cluster:

  4. Click on the instance or cluster to move to its configuration page.

  5. Select the Batch tab, and the Configuration sub-tab should load.

  6. Select the new data source from the Data Source Lookup Name drop-down menu.

  7. Save the changes.

Usage Restrictions

The Jakarta Batch runtime will not create internally more than one set of JBatch tables per schema. So in your schema if there exists a set of JBatch tables with prefixes and suffixes in the table names and then specify in the JBatch configuration for the same schema above that you wish to use JBatch tables under a different name (for example no table prefix and suffix) then during the JBatch initialization phase, JBatch will attempt to create these tables since they do not exist.

However since the table constraint names already exist for the existing JBatch tables in the same schema, table creation will fail. One can of course run a_SQL_ script to create the relevant JBatch schema objects under different names.

MySQL Specifics

For MySQL (5/8) database use, it is recommended the following additional property be set:

Name Value Description

zeroDateTimeBehavior

convertToNull

Action for DATETIME values that are composed entirely of zeros (used by MySQL to represent invalid dates)
Depending on the version of MySQL you may also need to set the server property sql_mode to blank as JBatch uses null and zero dates.