docs/administration-guide/src/main/jbake/content/batch.adoc

type=page
status=published
title=Administering Batch Jobs
next=part-res-and-svcs-admin.html
prev=lifecycle-modules.html
~~~~~~
Administering Batch Jobs
========================

[[GSADG1077]][[sthref66]]


[[administering-batch-jobs]]
10 Administering Batch Jobs
---------------------------

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

The following topics are addressed here:

* link:#BABCHGJJ[About Batch Jobs]
* link:#BABIHIGA[Viewing Batch Jobs]
* link:#BABBFFIG[Configuring the Batch Runtime]

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

[[BABCHGJJ]][[GSADG1078]][[about-batch-jobs]]

About Batch Jobs
~~~~~~~~~~~~~~~~

GlassFish 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
GlassFish Server, the job repository is a database

For detailed information about batch jobs, batch processing, and the
batch processing framework, see
"https://javaee.github.io/tutorial/batch-processing.html[Batch
Processing]" in The Java EE 8 Tutorial. Also see
http://jcp.org/en/jsr/detail?id=352[Java Specification Request 352:
Batch Applications for the Java Platform]
(`http://jcp.org/en/jsr/detail?id=352`). The specification defines the
programming model for batch applications and the runtime for scheduling
and executing batch jobs.

[[BABIHIGA]][[GSADG1079]][[viewing-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
GlassFish Server environment.

The following tasks are used to view information about batch jobs:

* link:#BABIBFDJ[To List Batch Jobs]
* link:#BABFBGJB[To List Batch Job Executions]
* link:#BABGJIDD[To List Batch Job Steps]

[[BABIBFDJ]][[GSADG1080]][[to-list-batch-jobs]]

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 link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-jobs`]
subcommand.

[[GSADG1081]][[sthref67]]


Example 10-1 Listing Batch Jobs

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

[source,oac_no_warn]
----
asadmin> list-batch-jobs
JOBNAME  INSTANCECOUNT 
payroll  9
bonus    6
Command list-batch-jobs executed successfully.
----

[[GSADG1082]]

See Also

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

[[BABFBGJB]][[GSADG1083]][[to-list-batch-job-executions]]

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
link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-job-executions`] subcommand.

[[GSADG1084]][[sthref68]]


Example 10-2 Listing Batch Job 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.

[source,oac_no_warn]
----
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.
----

[[GSADG1085]]

See Also

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

[[BABGJIDD]][[GSADG1086]][[to-list-batch-job-steps]]

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
link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-job-steps`] subcommand.

[[GSADG1087]][[sthref69]]


Example 10-3 Listing Batch Job 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.

[source,oac_no_warn]
----
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.
----

[[GSADG1088]]

See Also

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

[[BABBFFIG]][[GSADG1089]][[configuring-the-batch-runtime]]

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`.

GlassFish 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
link:jdbc.html#ablih[Administering Database Connectivity]. For more
information about managed executor services, see
link:concurrent.html#DAFBHEDI[Configuring Managed Executor Services].

The following tasks are used to view and configure the batch runtime:

* link:#BABBGHCJ[To List the Batch Runtime Configuration]
* link:#BABFEJAD[To Configure the Batch Runtime]

[[BABBGHCJ]][[GSADG1090]][[to-list-the-batch-runtime-configuration]]

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
link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`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): +
[source,oac_no_warn]
----
asdmin> get resources.jdbc-resource.jdbc/__TimerPool.*
...
asdmin> get resources.managed-executor-service.concurrent/__defaultManagedExecutorService.*
...
----

[[GSADG1091]][[sthref70]]


Example 10-4 Listing the Batch Runtime Configuration

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

[source,oac_no_warn]
----
asadmin> list-batch-runtime-configuration
DATASOURCELOOKUPNAME     EXECUTORSERVICELOOKUPNAME
jdbc/__TimerPool         concurrent/__defaultManagedExecutorService
Command list-batch-runtime-configuration executed successfully.
----

[[GSADG1092]]

See Also

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

[[BABFEJAD]][[GSADG1093]][[to-configure-the-batch-runtime]]

To Configure the Batch Runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


[NOTE]
=======================================================================

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
link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`set-batch-runtime-configuration`] subcommand.

[[GSADG1094]][[sthref71]]


Example 10-5 Configuring the Batch Runtime

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

[source,oac_no_warn]
----
asadmin> set-batch-runtime-configuration --executorservicelookupname concurrent/Executor1
Command set-batch-runtime-configuration executed successfully.
----

[[GSADG1095]]

See Also

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