Environment Interfaces(4.3)
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
andDRBatchWorkflowEnv
Client interfaces, including
DRUIEnvironment
,DRWfUIEnvironment
Server interfaces, including
DRServerExecEnv
,DRRealtimeServerEnv
andDRBatchServerEnv
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.
Note!
It extends both the DRBatchWorkflowEnv
, DRRealtimeWorkflowEnv
and DRWfUIEnvironment
classes. Given an agent name, the method readState
returns the agent's last saved state (if any). This method is only applicable for batch workflows.
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
andDRBatchWorkflowEnv
Client interfaces, including
DRUIEnvironment
,DRWfUIEnvironment
Server interfaces, including
DRServerExecEnv
,DRRealtimeServerEnv
andDRBatchServerEnv
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.
Note!
It extends both the DRBatchWorkflowEnv
, DRRealtimeWorkflowEnv
and DRWfUIEnvironment
classes. Given an agent name, the method readState
returns the agent's last saved state (if any). This method is only applicable for batch workflows.
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.