4.6 Services

Plugin agents may utilize built-in services for various purposes. Some services come with separate user interfaces in order to be configurable. Services with a graphical user interface are added as an extra tab in the agent's configuration. To use a service, the Inspectable class name of the service must be returned by the getServices method in the Inspectable class of the agent.

At runtime, the agent executable must gather the service's executable, using the getService method in either DRBatchServerEnv or DRRealtimeServerEnv, depending on the type of workflow. The getService method takes the service Inspectable name as argument and returns the Executable for the service. During runtime, each service Executable acts differently, that is, the Executable for the specific service must be examined.

Filename Template

The Filename Template service is a service that file based Forwarding agents may use. It is a service with a user interface where the user can define how to build the file name, based on MIM or user defined values with the possibility to pad, align etc.

To use this service, the DRFNTServiceInsp class name must be returned in the agent's Inspectable classe. The Filename Template executable is called DRFNTServiceExec and it provides one method to get the generated filename. Since the service may depend upon MIM values published in drain, this method must be invoked at endBatch to get the generated filename.

Filename Sequence

This service allows the user to define a part of a filename to contain a sequence. This is a service with a user interface that is also possible to turn off. The service keeps track of what the next sequence number is. It is also possible to change what the next sequence number will be in its user interface. The Executable class is called DRFNSServiceExec.

At runtime the agent will check whether the service is enabled before invoking methods on it (except for the state handling). The service Executable, defines a method called isServiceConfigured that returns information regarding whether it has been configured or not. The agent must manage the state of this service as well as saving the result from the getSequenceNoChk and getNextSequenceNo methods.

The isSequenceNoChangedByGUI must be invoked at startup to find out if the user has changed the next sequence number. The arguments supplied to the method are the ones saved with the state, that is, the ones returned by getSequenceNoChk and getNextSequenceNo. If the result is true, the agent must consider an update to its state.

To find out if the next file(s) to collect have correct sequence numbers, the isNextFileToRetrieve or getConsecutiveSequenceNumbers are used. The isNextFileToRetrieve returns true if the given file has the next sequence number. The getConsecutiveSequenceNumbers method takes a list of filenames and returns them, sorted according to the sequence number. If there is a gap in the sequence, an error is returned.

The agent must manually tell the service to update the sequence number, since services are not part of the transaction. This must be done prior to calling endBatch.

Sort Order

This is a service with a user interface that could be used by Collection agents. The Sort Order service allows the user to define the order of how files will be collected. The user may define sorting based on a segment of the filename, or by using a regular expression. This service may also be turned off. An agent that uses both the Filename Sequence service and this service must make sure that not both services are turned on at the same time.

At runtime, the Executable of the agent must check whether the service is configured, using the isServiceConfigured method. The service defines two methods for sorting the files and the agent may use either, based on an array of strings, or based on a list of strings.

File Sort Order

This service adds the option to sort on file modification time, on top of the functionality of the Sort Order service previously described. The only difference is that the sort methods operate on the Java File object instead of String.

ECS Batch

To support cancellation of batches in batch based collectors, an ECS Batch service must be used. If the workflow has been configured to abort immediately, the chosen service manages this by ignoring calls, which means that the agent does not need to consider ECS.

There are two ECS Batch services:

  • DRECSBatchServiceExec - This service uses temporary files for sending data to ECS.

  • DRECSStreamBatchServiceExec - This service sends a stream to ECS, without creating temporary files.


Note!

Using DRECSStreamBatchServiceExec will result in less I/O overhead since it does not make use of a cache.

DRECSBatchServiceExec

By using this ECS Batch service, raw data will be written to a temporary file and sent to ECS when the agent receives a cancelBatch call. Since services are not aware of the transaction state, the agent must call the methods on the batch service according to the transaction state.

When starting collection of a new batch, the begin method must be called. For every block routed into the workflow, the consume method must be called with the same data. If the file has been correctly processed by the workflow, i e the agent goes to commit, the cancel method must be called on the service. This removes the temporary file from the file system.

If the workflow goes to cancelBatch, the commit method must be called. In case of a failure, i e neither commit nor cancel has been called on the service, it is recommended to call cancel in the deinitialize method as well.

DRECSStreamBatchServiceExec

This service does not make use of a cache during the batch workflow routing. No temporary files are created which results in less I/O overhead. When the batch workflow is cancelled through a cancelBatch call, the service takes a java.io InputStream and sends it to ECS through its insertBatch method.

Note!

The insertBatch method can only be called from the agent's cancelBatch method, otherwise an exception will be thrown.