The User Interface Dialog
- Yeok Hong Ng (Deactivated)
The GUI class is used to collect and display the configuration data required for the agent to operate. The user interface will be implemented in a JPanel that the Workflow Editor will put in a dialog. The Workflow Template automatically adds the OK and Cancel buttons.
You must extend the DRAgentUI class, that in turn extends the JPanel class. The Workflow Template will create an instance of this class when an agent is dropped or loaded into the workflow. The instance will be kept until the agent is deleted or the workflow is re/unloaded.
Defining the User Interface
The first method to call is the constructor. Here it may be suitable to create all the user interface components to be used in the dialog. However, when the GUI class is constructed, all variables that may be useful are not yet available. These include, the agent name and the Workflow Template environment. If this information is required the initialize method must be used.
Initialization and Deinitialization
The initialize method will be called once after the class is constructed. In this method the agent's name and the Workflow Template environment is available.
The deinitialize method is called once prior to the destruction of the class.
Displaying Configuration Data
The displayConfig method is called every time the agent is double-clicked prior to the dialog display. The method is handed a DRStorable configuration object that is either null, if the agent has not yet been configured, or contains data if it has. The data has to be type casted to the appropriate type before usage.
It is important that all components in the user interface are cleared in this method before they get populated with the supplied data. If not, old data may reside in the Java components if they were previously filled and Cancel was pressed.
A hint is to populate, for instance, combo boxes with data in this method, if they contain environmental data such as database names or route names. This will ensure that these will get updated each time the user interface dialog is displayed. If they are only populated in the constructor, the workflow would have to be reloaded, or a new agent would have to be dropped in order to refresh these components.
If the agent supports update of running configurations, it should be considered which fields should be possible to update. Making fields available or not for update is done in the following way. First check if the inherited method isDynamicUpdate returns true. If that is the case the fields that should not be available for update should be disabled. The fields that should be available for update should be enabled or disabled depending on their field instance types. If a field has a field instance type other than final, it should be enabled. If the field instance type of the field is final it should be disabled.
Example - Enabling/disabling a field available for dynamic update
Enabling/disabling a field available for dynamic update depending on its field instance type:
boolean enablePort = !data.getPortFieldInstanceType()
.equals(DRFieldInstanceType.FINAL);
_portFld.setEnabled( enablePort );Collecting Data
The collectConfig method collects the configuration from the user interface when OK is clicked.
Validation of User Data
Data entered in the user interface is validated when OK is clicked. The data gets validated against the validation rules specified in the configuration contract. If a validation error occurs a dialog will be displayed containing the message specified in the contract.
It is important that references to Workflow Template environment entities, such as route names and MIM resources, are also validated. The recommended way of designing, for instance route names selection, is to populate a user interface component in the displayConfig method. That way, the user cannot select one that is invalid. However, when the user interface dialog has been validated and confirmed, the user may change names on routes and on agents invalidating the previous validation. To prevent this, such external entities must be validated again in the Inspectable class.
User Interface for Commands
To create a command to interact with an active workflow, the DRCommandUI class should be extended. The Inspectable class must return the class name in the getCommandUIClassName method.
All methods defined in the User Interface for Commands must be implemented in the same way as the corresponding methods in the DRAgentUI class.