DRBatchAgent(3.3)

Owned by Jenni Wallin
Oct 02, 2023
4 min read

The batch agent adds transaction points to a DRAgent. It is the super class for all batch agents. The following methods are defined:

  • initialize
    The initialize (DRStorable, DRInputStream) method is called during startup to give the agent its configuration and optionally a stream, where the state is read from. The config argument is the agent configuration class, populated with the configuration saved in the user interface. The state argument is an input stream that, if not null, must be read in the same order as written in the writeState method.

  • beginBatch
    This method is called at the beginning of a batch and it is fed the transaction id. Agents must prepare themselves to be fed with data at this point.

  • endBatch
    This method is called when all data for the current batch has been processed by the workflow. Agents must be prepared for a commit of the current transaction at this point.

  • writeState
    This method is invoked after endBatch and allows the agent to persist transaction specific information. In case of a crash during commit/rollback, the state will be used at startup to apply the correct logic for commit/rollback of the transaction.

  • rollback
    Called if the current transaction should be rolled back, that is, removed. This method is only called after initialization in case of a previous crash.

  • commit
    Called when the current transaction should be committed. The transaction is closed at this point and the produced data is considered safe.

  • cancelBatch
    Invoked when a batch is being canceled. A Collection agent should route the incoming file to the error service. Other agents should make sure temporary data that has been persisted in interfaced systems is removed.

  • getTransactionResources
    If the agent depends on resources that must take an active part of the workflow transaction in terms of prepare/rollback/commit, it must return a reference to these resources in this method. These resources must be defined in the initialize method. For example, return the DRECSBatchServiceExec if it is dependent on the transaction.

Transaction Order

An important feature of a mediation system is transaction safety.  provides a two-phase commit transaction model, with the possibility to save a transaction state with the current transaction. The Collection agent controls a transaction, since it feeds the incoming batches.

The DTK defines a method that can be called to hint the Collection agent to close a transaction. This method is called hintEndBatch and is defined in DRBatchServerEnv. The collector may choose to ignore this call.

The following examples shows possible method invocation orders for Processor agents.

Example

A batch is successfully processed. The Collector agent begins the batch, feeds the data into the workflow, and then ends the batch.

Invocation order:

The flag isRecover to commit will be false.

* The consume method can be called several times.

Example

A batch is committed at startup. The commit invocation started the last time the workflow was running. Before the commit was finished, the workflow aborted.

Invocation order:

The state passed to initialize is the state written in writeState just before the workflow aborted. Since one or more agents may already have received commit before the crash, an agent must always be prepared to receive more than one invocation to this method.

The flag isRecover to commit will be true. This indicates that the method may have been invoked earlier with the same transactionID.

Example

A batch is rolled back at startup. The commit invocation never started the last time the workflow was running. Before reaching commit, the workflow aborted.

Invocation order:

The state passed to initialize is the state written in writeState during the last successfully committed batch.

Note!

If there was no successful batch processed before the workflow aborted, the state will be null.

The flag isRecover to rollback will be true. This indicates that the method may have been invoked earlier with the same transactionID.

Example

A batch is canceled. It can happen at any time after beginBatch and before endBatch.

Invocation order:

A canceled batch is still treated as a processed batch and therefore the transaction will be committed.

Any Processor agent may call cancelBatch in the environment during an invocation of consume. The thread will eventually be unwound and call execute on the Collector agent again. An agent calling DRObjectRouter.consume must ensure that its internal state is not corrupted when the thread is unwound. Note that cancelBatch, writeState, and commit may be called before the thread is unwound.

Any Processor agent may also call cancelBatch in the environment during an invocation of drain.

* The consume method can be called several times.