At a high level, programmers need to do two things when adding new event actions to IBM Director Server:
The IBM Director Event Manager (or simply referred to as Event Manager) is a subcomponent of the IBM Director Server that handles all event traffic. It manages the repository of event related objects like: events, event filters, event actions, and event action plans. In addition, it is the control point for the execution of all event actions contained in event action plans on the server.
The Event Manager discovers each of the available event actions during server startup. Although some event actions are loaded explicitly (because they are known to exist as part of Director), others are loaded indirectly through knowledge gained by the event action extension files. These files explicitly name Java classes that have implemented the TWGEventHandler or the TWGRefreshableEventHandler interface. Either way, a single instance of each class that has implemented one of these interfaces is created.
From this point forward, an instance of a class known to have implemented the TWGEventHandler or the TWGRefreshableEventHandler interface will be referred to as the Event Handler. Many of the discussions that follow use this term in describing the interactions between the Event Manager and the individual instances of the classes that have implemented this interface. When used in conjunction with the Director console, event action is still a widely used term.
During discovery, the Event Manager uses the GetInfo method to query information about the event handler. This information includes things like: what function it performs (title) and what input parameters are needed to configure it. Each input parameter contains information describing its purpose, style of GUI component (eg. text box or spinner), and any default values. Finally, event handlers are given an opportunity to specify whether they should remain resident at all times or have an instance created for each invocation.
The Event Manager uses the information gathered during the discovery process to create the list of available event actions shown in the Event Action Plan Builder. If an action is customizable (ie. it has one or more parameters), the Event Action Editor creates a dialog based on the sum of the input parameters (defined during the GetInfo processing). When the user selects "Save" or "Save As" toolbar icons, the user provided data is imbedded into the appropriate parameter object and passed to the event handler via the ValidateParm method. The ValidateParm method is called once for every parameter defined by the action. This mechanism allows the event handler to respond with a unique error message for each invalid input it receives. If all inputs are deemed valid by the event handler, this set of input parameter's is saved by the event manager and made available for association with event action plans. Please note: now that a given event action has multiple representations in the Event Action Plan Builder, only one instance of the event handler class exists at any one given time in the server.
With the customized event actions safely stored on the server, event handlers do not get called again until some event triggers and an associated event action plan dictates that it should. When this occurs, the event manager calls the event handler's ProcessEvent method passing both the customized parameter list and the event that triggered. The event handler is then required to process the data as quickly as possible and return. This process is repeated for every event that triggers.
Please note: The first time an event action's title and list of parameters are discovered, they are stored as persistent data in a file called, TWGACTION.INI, located in the classes\data subdirectory. Should the programmer change any of the data associated with these items, a simple restart of the Director Server will not alter this information. The TWGACTION.INI must be deleted and the server restarted for changes to be effective.
Event data substitution refers to the replacement of specifically defined keywords within user text imbedded in TWGActionParmTextBox and TWGActionParmTextArea objects. When utilized, event data such as type, text, and severity are extracted from the event that triggered this action and inserted into text where appropriate as part of the action. Event Handlers that wish to support this feature should use the TWGEvent.expandString method.
An event action extension file is a property file that must reside in the classes\extensions subdirectory relative to where the IBM Director Server was installed. Event action extension files might be identified by their unique ALTExt file extension. Within the property file, use the following keywords to describe the action (event handler).
Property Name | Property Value |
---|---|
event.action.classname | A string that identifies the name of the class that implements the TWGEventHandler or the TWGRefreshableEventHandler interface. The name specified should be fully qualified (including package name) and relative to the Director classes directory or updated classpath. Refer to the sample event action extension file, SMTP.ALTExt illustrated below. |
event.action.iconname | A string that identifies the name of the GIF file that contains the 16-pixel image to be used as the action's icon on the IBM Director console. The name specified should be fully qualified and relative to the Director classes directory. At load time, the name given for this property will be suffixed with 16.gif. |
event.action.helpfilename | A string that identifies the name of the html file that contains the help text for the action. Help text should primarily focus on describing the function provided by the action as well as a complete description of each input parameter presented on the user interface. The english version of the html file must be placed into the classes\doc\tivoli\events subdirectory relative to where IBM Director Server is installed. National languages versions of the file might also be created and placed into the appropriate language subdirectory relative to where is installed: classes\doc\lang\tivoli\events, where lang corresponds the two-letter language prefix (eg. gr = german). |
# Event Action extension definition file # event.action.classname=com.tivoli.twg.itech.TWGSMTPActionHandler event.action.iconname=com.tivoli.twg.itech.images.semail event.action.helpfilename=dlg_cstmz_actn_snd_email.html
Event action history is the primary mechanism for providing feedback to users about the success or failure of an action. Event actions support event action history in two ways. The first addresses launch time status and is a product of the boolean returned on the ProcessEvent call. The second is designed for asynchronous updates that occur long after ProcessEvent has returned. For this, event handlers should utilize the TWGActionLogManager and TWGActionEndInfo classes. Each time an event handler's ProcessEvent method is called, a unique key is assigned by the event manager and placed into the TWGActionInfo object. This key is then used by the event handler to post success or failure messages into the action history log. A free text area is available for any additional information the handler wishes to convey.
Each event action within IBM Director Server has a corresponding html file that describes its purpose and individual action parameters. Refer to the event.action.helpfile property of the event action extension file for more information.
All of the classes described in this section utilize a similar strategy for supporting national language translatables. Each attribute of the event action including the title, parameter labels and sublabels, help files, and messages have been encoded to provide a Java style of national language support. Each string might be coded as a resource bundle and keyword pair. This allows the event manager to load at run-time the appropriate string relative to the desired locale.
In addition, the Customize Action dialog supports the setting of a preferred language. The motivation for which is to allow user's to indicate what language is preferred at the ultimate target of the action. This setting might be determined using the TWGActionInfo.getTargetLocale() method.