Many DTK classes hold various types of "environment" objects. These objects contain useful information and utilities related to the whereabouts of the class and are used by the plugins to communicate with the  system. For instance, agent related classes have access to the workflow environment where other workflow configurations may be obtained. There are also environment objects referencing data in the  system.

The environment classes can be divided into three interface categories:

• Common interfaces, including DREnvironment, DRWorkflowEnv, DRRealtimeWorkflowEnv and DRBatchWorkflowEnv

• Client interfaces, including DRUIEnvironment, DRWfUIEnvironment

• Server interfaces, including DRServerExecEnv, DRRealtimeServerEnv and DRBatchServerEnv

Common interfaces are utilized both in client and server side code and are mainly superinterfaces for the other interfaces. Client interfaces are utilized in code related to the  user interface. Server interfaces are utilized in code related to the execution of workflows.

The following figure illustrates the relationship and inheritance between all environment interfaces:

Environment overview

The coming sections describe each interface.

DREnvironment

This is the base interface for all other environments. It contains various methods to obtain system data. The method getDatabases returns a list of all database configurations that have been defined in the system. If a database configuration key is provided, the method getDatabaseProfile returns a DRDBProfile object, holding information about the specific database.

A list of all UDR types created in the Ultra Format Editor or created using the DTK, is available through the getDRUDRDescs method. There are various other methods that return UDR descriptions for given UDR type names etc.

The  system name is obtained with the getSystemName method, property values are obtained with the getProperty method, and events can be dispatched to the Event Server using the dispatchEvent method.

DRUIEnvironment

This interface is available in all user interface related DTK code.

The method reportException can be used to display the built-in exception viewer. If special user interface coding is desired, the Java JDesktopPane can be obtained with the getDesktopPane method.

DRWorkflowEnv

Utilities from this interface are available in agent development.

The current workflow name is returned by the getWorkflowName method. The isRealtime method checks if the current workflow is a realtime or batch workflow. The getNodeOfType method returns a list of agent names of either all collection or processing agents available in the workflow. The getMIMTree method returns all MIM resources currently published in the workflow. This tree may be used within configuration components or for validation purposes.

Given an agent name, the getInputNodeNames and getOutputNodeNames methods return a list of agent names that are connected to, or from, the agent, and the getInputTypes and getOutputTypes methods return the data types that the agent is configured to receive or forward. In case of output, a route name has to be specified as well. Also, given an agent name, the getRouteNames method returns a list of outgoing route names.

The getExecutionHosts method allows you to retrieve the execution hosts that the workflow has been scheduled to execute on (if any). The isStandalone method checks if the current workflow is a standalone workflow. Only realtime workflows can be standalone.

DRRealtimeWorkflowEnv

This interface is available in realtime workflows. Currently there are no additional methods available in this interface.

DRBatchWorkflowEnv

This interface is available in batch workflows.

The method getCancelBatchBehaviour returns how a Cancel Batch directive will be treated by the workflow. For further information about Cancel Batch behaviors, see the /wiki/spaces/MD/pages/3214541.

DRWfUIEnvironment

This interface is available when coding agent user interfaces.

DRServerExecEnv

This interface is available in all server related DTK code.

Agent message events may be sent to the event server using the method dispatchMessage, which comes in two versions where one offers the possibility of both setting a agent message and a type. Agent failure events may be sent to the event server using the logException method. However, this method must only be used if the agent wants the exception to be silently logged, not causing the agent to abort.

The execute method allows an agent to execute a Runnable in a new thread. This method must be used when an agent wants to add a thread to the workflow. The workflow will be running until all collection agents and all threads added through this method are finished. The agent that creates the Runnable is also responsible for stopping it when the workflow is stopped.

The method isDebugEnabled states if debugging has been enabled for the workflow. To send a debug event, the dispatchDebug should be used. A debug event will only be sent if isDebugEnabled is true.

DRRealtimeServerEnv

This interface is available when coding realtime agents.

The interface includes methods for invoking and controlling simultaneously executing tasks.

It is also possible to control the internal workflow queue which distributes work to the workflow threads. The queue has a soft limit which is set in the configuration. By calling the getQueueLimit method, the current limit can be inspected. The limit can be changed by calling the setQueueLimit method from the agent's initialize method.

To check the current size of the queue during run time, the getQueueSize method should be used.

If the agent implements the DRRealtimeAsyncRouter class, the callback on changes in the queue size can be controlled by using the setNotificationStep method. This method can only be used in the agent's initialize method.

The current notification step can be inspected with the getNotificationStep method.

DRBatchServerEnv

This interface is available when coding batch agents.

The method cancelBatch allows processing agents to cancel the batch if necessary. If the workflow is not configured to abort, this will send the currently processed batch to ECS. Based on the workflow configuration, the workflow may continue with the next batch or abort.

If a Processing agent requires the currently processed batch to be split, for some reason, it may hint the collector to do so using the hintEndBatch method. If the collector supports splitting batches, it will immediately end the current batch and start a new one. If not, it will return an unsupported exception, causing the workflow to abort. The following collectors support this operation: Disk, FTP, Database and ECS.

Each batch is assigned a unique transaction ID that may be obtained using the getCurrentTxnID method.

Many DTK classes hold various types of "environment" objects. These objects contain useful information and utilities related to the whereabouts of the class and are used by the plugins to communicate with the  system. For instance, agent related classes have access to the workflow environment where other workflow configurations may be obtained. There are also environment objects referencing data in the  system.

The environment classes can be divided into three interface categories:

• Common interfaces, including DREnvironment, DRWorkflowEnv, DRRealtimeWorkflowEnv and DRBatchWorkflowEnv

• Client interfaces, including DRUIEnvironment, DRWfUIEnvironment

• Server interfaces, including DRServerExecEnv, DRRealtimeServerEnv and DRBatchServerEnv

Common interfaces are utilized both in client and server side code and are mainly superinterfaces for the other interfaces. Client interfaces are utilized in code related to the  user interface. Server interfaces are utilized in code related to the execution of workflows.

The following figure illustrates the relationship and inheritance between all environment interfaces:

Environment overview

The coming sections describe each interface.

DREnvironment

This is the base interface for all other environments. It contains various methods to obtain system data. The method getDatabases returns a list of all database configurations that have been defined in the system. If a database configuration key is provided, the method getDatabaseProfile returns a DRDBProfile object, holding information about the specific database.

A list of all UDR types created in the Ultra Format Editor or created using the DTK, is available through the getDRUDRDescs method. There are various other methods that return UDR descriptions for given UDR type names etc.

The  system name is obtained with the getSystemName method, property values are obtained with the getProperty method, and events can be dispatched to the Event Server using the dispatchEvent method.

DRUIEnvironment

This interface is available in all user interface related DTK code.

The method reportException can be used to display the built-in exception viewer. If special user interface coding is desired, the Java JDesktopPane can be obtained with the getDesktopPane method.

DRWorkflowEnv

Utilities from this interface are available in agent development.

The current workflow name is returned by the getWorkflowName method. The isRealtime method checks if the current workflow is a realtime or batch workflow. The getNodeOfType method returns a list of agent names of either all collection or processing agents available in the workflow. The getMIMTree method returns all MIM resources currently published in the workflow. This tree may be used within configuration components or for validation purposes.

Given an agent name, the getInputNodeNames and getOutputNodeNames methods return a list of agent names that are connected to, or from, the agent, and the getInputTypes and getOutputTypes methods return the data types that the agent is configured to receive or forward. In case of output, a route name has to be specified as well. Also, given an agent name, the getRouteNames method returns a list of outgoing route names.

The getExecutionHosts method allows you to retrieve the execution hosts that the workflow has been scheduled to execute on (if any). The isStandalone method checks if the current workflow is a standalone workflow. Only realtime workflows can be standalone.

DRRealtimeWorkflowEnv

This interface is available in realtime workflows. Currently there are no additional methods available in this interface.

DRBatchWorkflowEnv

This interface is available in batch workflows.

The method getCancelBatchBehaviour returns how a Cancel Batch directive will be treated by the workflow. For further information about Cancel Batch behaviors, see the /wiki/spaces/MD/pages/3214541.

DRWfUIEnvironment

This interface is available when coding agent user interfaces.

DRServerExecEnv

This interface is available in all server related DTK code.

Agent message events may be sent to the event server using the method dispatchMessage, which comes in two versions where one offers the possibility of both setting a agent message and a type. Agent failure events may be sent to the event server using the logException method. However, this method must only be used if the agent wants the exception to be silently logged, not causing the agent to abort.

The execute method allows an agent to execute a Runnable in a new thread. This method must be used when an agent wants to add a thread to the workflow. The workflow will be running until all collection agents and all threads added through this method are finished. The agent that creates the Runnable is also responsible for stopping it when the workflow is stopped.

The method isDebugEnabled states if debugging has been enabled for the workflow. To send a debug event, the dispatchDebug should be used. A debug event will only be sent if isDebugEnabled is true.

DRRealtimeServerEnv

This interface is available when coding realtime agents.

The interface includes methods for invoking and controlling simultaneously executing tasks.

It is also possible to control the internal workflow queue which distributes work to the workflow threads. The queue has a soft limit which is set in the configuration. By calling the getQueueLimit method, the current limit can be inspected. The limit can be changed by calling the setQueueLimit method from the agent's initialize method.

To check the current size of the queue during run time, the getQueueSize method should be used.

If the agent implements the DRRealtimeAsyncRouter class, the callback on changes in the queue size can be controlled by using the setNotificationStep method. This method can only be used in the agent's initialize method.

The current notification step can be inspected with the getNotificationStep method.

DRBatchServerEnv

This interface is available when coding batch agents.

The method cancelBatch allows processing agents to cancel the batch if necessary. If the workflow is not configured to abort, this will send the currently processed batch to ECS. Based on the workflow configuration, the workflow may continue with the next batch or abort.

If a Processing agent requires the currently processed batch to be split, for some reason, it may hint the collector to do so using the hintEndBatch method. If the collector supports splitting batches, it will immediately end the current batch and start a new one. If not, it will return an unsupported exception, causing the workflow to abort. The following collectors support this operation: Disk, FTP, Database and ECS.

Each batch is assigned a unique transaction ID that may be obtained using the getCurrentTxnID method.