Package com.groiss.wf.batch

The batch package contains the classes which support long running tasks (batch jobs) in @enterprise.

See: Description

Interface Summary

Interface	Description
BatchAdapter	Interface BatchAdapter allows an instance to be notified by the BatchManager of execution events of a BatchJob.
ExceptionBatchAdapter

Class Summary

Class	Description
BatchJob	Captures state information about batch jobs.
BatchManager	Starts and completes BatchJobs.
ExceptionHandlingCompletedHandler
NullAdapter	Poor mans implementation of BatchAdapter.

Package com.groiss.wf.batch Description

The batch package contains the classes which support long running tasks (batch jobs) in @enterprise.

System steps (specified via system <methodname>) in WDL are for the automatic execution of methods. They are executed within the current thread and within the current transaction context. So the duration of a user initiated finish action of an interactive step is prolonged by the duration of the following system steps (and the duration of the preprocessing method of the next interactive step). As a consequence, system steps should be rather lightweight in terms of execution time.

Package Overview

This package provides support for long running automatic tasks (batch jobs) in @enterprise.

Batch jobs are created in the process definition via the batch statement in WDL or in the process editor.

A timer activated BatchManager is responsible for starting batch jobs and for finishing and continuing the execution of the process instance after a batch job has completed. after the batch job has completed.

Batch jobs are instances of BatchJob. State information about batch jobs is maintained persistently in the database and updated throughout the lifecyle of the job. Each job follows a lifecycle which is normally a sequence of the four states CREATED, STARTED, FINISHED and COMPLETED.

Created means entered into the database but not (yet) started. Started means that the Batchjob is currently running. Finished batch jobs have terminated their execution, but the corresponding process step where the batch job originated is still not finished. After the originating stepinstance is finished, the job is said to be completed.

Lifecyle events can be captured by means of implementing the BatchAdapter interface.

Specification of a Batch Job in the Process Definiton

Batch jobs are incorporated into the process definition by the batch statement in WDL.

batch <batchAdapterClassname>([stringparam]) { startnow | newthread | retrystart | autofinish | pollfinish | gobackonerror }

e.g.: batch com.groiss.demo.DemoBatchAdapter("p1") startnow gobackonerror;

An appropriate BatchAdapter must be stated, one constant parameter can be given and the behaviour can be modified in six ways via flagging

Lifecycle of a BatchJob

The following paragraphs describe the default lifecycle of a batchjob. There are variations in the lifecycle, if behaviour modifications are activated at batch job creation via flagging

Creation and afterCreation

When the originating step is started, the engine calls the BatchManager.submitJob method and thereby persistently creates a new instance of BatchJob. The string parameter given in the process definition is available via bj.getParams, the ActivityInstance can be accessed via bj.getContext If an exception occurs during the creation of the batch job, the action (the previously issued finish) is rolled back and no traces remain in the database.

After creation of the batch job, afterCreation is called. This method can be used to prepare the start of the batch job e.g. by transferring values from forms to some appropriate locations. If some fields of the batch job instance are updated, then the update call for the batchjob in the database is the responsibility of afterCreation. The call of afterCreation takes place in the same thread and transactional context as the previous finish. Exceptions thrown by afterCreation cause rollback of the transaction.

Start and doStart

When a BatchJob is started, the state transition is persisted to the database and doStart is called.

If an exception is thrown in doStart, the batch system issues an rollback (since @enterprise version 9.0) and the state of the BatchJob is changed to STARTERROR.

Finish and markJobFinished

To mark a batch job as finished, an external entity can call one of the variants of BatchManager.markJobFinished.

When the BatchManager detects such jobs during its next timer controlled run, it completes them.

beforeCompletion, Completion and afterCompletion

Completion of a batch job triggers to events in the BatchAdapter and also finishes the task of the process instance where the batch job originated.

First, the beforeCompletion method is called.

If there is an exception, the job is placed in state FINISHERROR. No further action is taken by the batch system.

If all went well in beforeCompletion, the originating task of the process instance is finished and the job is placed in state COMPLETED.

If there is an exception during the finish, the job is placed in state FINISHERROR and no further action is taken by the batch system.

After this, the afterCompletion method is called with a boolean parameter which indicates if the job is now in state COMPLETED (commit = true) or in state FINISHERROR (commit = false). Exceptions thrown by afterCompletion trigger a rollback (since @enterprise version 9.0).

Compensation and doCompensate

When a job is compensated because of a goBack action, then the doCompensate is called.

Aborting and reactivating processes with batch steps

If a process instance which is currently in a batch step is aborted, the batch job is also marked as being in state ABORTED. No further action on this batch job will take place automatically.

If such a process is reactivated later on, no changes are made to the state of the batch job. The administrator will have to make the appropriate adjustments to the batch job manually via the link in the process history (e.g. setting the state to STARTED or to FINISHED and to adjust the associated time stamps).

Behaviour Variations

The lifecycle of a batchjob can be modified by appropriate flagging with respect to three areas, which can be combined arbitrarily in an almost fully orthogonal way Flagging can occur either using the methods BatchJob.setStartnow(boolean), BatchJob.setNewthread(boolean), BatchJob.setRetryStart(boolean), BatchJob.setAutofinish(boolean), com.groiss.wf.batch.BatchJob#setPollfinish and BatchJob.setGoBackOnError(boolean) or in the third parameter of BatchManager.submitJob.

• A batch job where startnow is set is started immediately after successful completion of the transaction which called the BatchManager.submitJob method and not during the next timer triggered run of the BatchManager.
• By specifying newthread, the start of the job takes place in a newly created thread. The original thread creates the batch job and calls afterCreation, but the start of the job is done in the new thread. This feature could be used when the start of the batch job itself takes significant time.
• By setting retrystart to true, exceptions during doStart() are handled differently. An exception would lead to no change of the state of the batch job, it stays in CREATED. During the next run of the executing timer, a new start attempt will take place. The code in doStart() can also use one of the following methods to prevent further start attempts:
  • BatchManager.markJobError(): the job is placed in state STARTERROR.
  • BatchManager.markJobSuspendRetry(): the job is still in state CREATED, but no further start attempts are being made. Using BatchManager.markJobRetry(), further start attempts can be activated again.
• Setting autofinish to true means that immediately after the doStart Method has terminated, (and the job is still in state STARTED ), the job is marked as finished and then completed by the system itself.
• Setting pollfinish to true means that the executing timer will call the doPoll() method of the BatchAdapter to determine if the job is finished. If doPoll()
  • just returns, the batch jobs state will remain unchanged.
  • throws an Exception, the batch jobs state will remain unchanged.
  • calls BatchManager.markJobFinished(), the batchJobs state is FINISHED and the batchjob and will be completed by the executing thread.
  • calls BatchManager.markJobError(), the batchJos state is FINISHERROR.
  • calls BatchManager.markJobSuspendPoll(), the state remains unchanged, and further poll attempts will be suspended. The poll attempts can be activated again by calling BatchManager.markJobPoll().
• Setting gobackonerror to true means that in case of an unhandled exception during execution of the doStart method, the engine tries to goBack to the last interactive step.

The defaults for the lifecycle are startnow=false, newthread=false, retrystart=false, autofinish=false, pollfinish=false and gobackonerror=false. Using startnow=true, newthread=false, retrystart=false, autofinish=true, pollfinish=false, and gobackonerror=true, we approach the semantics of the system steps.