This topic describes programming concepts and requirements to extend IBM Director to include user-defined console task extensions.
Subtopics
Related information
Related sample code
As described in Understanding IBM Director tasks,
IBM Director uses the concept of tasks as one if its primary extension points. Your
organization might want to customize IBM Director with your own tasks, one or more
of which might require interaction with the IBM Director administrators.
While not all tasks
require interaction with an IBM Director administrator, many do.
To provide GUI interaction with a task extension, you must understand
how IBM Director implements its interface to allow your organization to display
information on the IBM Director console.
The GUIs associated with tasks are referred to as Console Extensions.
Console Extensions are expected to subclass TWGTaskFrame. The TWGTaskFrame
super class provides a number of services to the Console Extension.
The IBM Director Management Console is written entirely in Java therefore you must use Java to extend the IBM Director interface.
If your task has an interactive component, you need to specify the
interface to IBM Director in your Task Properties
file.
In the Task Properties
file, the GUI property contains a class attribute. You should set
this attribute to the class name of the GUI you want to open.
The class specified must extend
TWGTaskFrame
as is done in the console sample program.
NOTE: In this release of IBM Director, implementing TWGTaskFrameImplementor is
no longer supported and GUIs must be
created by extending TWGTaskFrame.
TWGTaskFrame
is the base abstract class for all IBM Director top-level task frames.
It provides the base implementation of the
TWGTaskFrameImplementor
interface for activating
and deactivating a task frame. Your task console will look and act like the
IBM Director product when you use TWGTaskFrame:
-
You can automatically add a status panel to your frame.
-
Your base color information is
set up according to the user preferences currently in use.
-
IBM Director
provides default implementations for all of the methods, thus you only
have to override the ones that are important to your application.
-
IBM Director automatically caches away the size and position of the
task frame so that the next time you open the frame, it is restored to
its previous location and dimension.
-
A help context is automatically created for you if the mapping
attribute of a help topic is specified in the property file of your task .
Each IBM Director task extension will design a unique image to represent its
task. From this image an image set containing, at minimum, 16-point and 32-point
gif files can be generated. If the task is to be displayed on a toolbar, a 24-point
image and a 24-point rollover image will also be required. The images will be
made available where appropriate to identify this task on the Console Extension
frame, the main console, and/or in the help.
Panels displayed in the client area of this TWGTaskFrame must be
constructed so that their presence in the product is both aesthetically and
functionally seamless. Panels should have a clean, polished appearance and
behave appropriately. See IBM Director Programming:
Best Practices for more details on the layout of GUI Panels.
TWGTaskFrame provides many services:
- provides access to a TWGHelpContext object, which facilitates the
use of context help
- provides automatic creation of a ServiceNode object, used to
communicate with the server and/or agents
- positions task frames and saves the window's size and location
- participates in window management - TWGTaskFrames are displayed in the
console window list and can be arranged on screen in a number of ways or
brought to the front from the console:
Figure 1. The IBM Director Console showing the Window menu. TWGTaskFrame
provides a window management service. For more information about the IBM Director
Console see the help topic on the Primary
Console Window.
TWGTaskFrame objects will be notified when console preferences have been
changed by the user, allowing the frame's components to update accordingly.
Panels might be shadowed, colored or both:

Figure 2. Example of a TWGTaskFrame that has been notified to update after a
user-preference change.
In creating an IBM Director Console Extension you are required to:
- use super( true) in the constructor if a status
bar is required, super( false ) otherwise. Use appropriate methods to
set status bar text and manipulate its status indicator. Status indicator widgets are available for use in dialogs and are
packaged in a DirUIL.jar file for applications that must also run
stand-alone.
- override the buildView method to provide the panel
that is to be displayed in the task frame.
- if required, build toolbars that resemble the one
used by the main console. There are widgets for this in the DirUIL.jar file in the event that the
application must also run stand-alone. Refer
to sections 2.1 and 2.2, and to the SDK.
- arrange for the default view of the window (after
install) to make a good initial appearance. Important factors in the initial
appearance are: an appropriate size and the absence of scroll-bars
(wherever possible).
- set the frame icon to match the icon shown in the Task pane of the main console. All
dialogs, option panes and child windows should use the same icon.
- set the title to reflect the name of the task and,
if applicable, the systems or group against which the task was opened
- use, and refrain from interfering with, IBM
Director’s "Look and Feel".
- make sure keyboard navigation works correctly (see Keyboard
Manipulation).
- use common labels and their associated mnemonics
and accelerators where applicable (see Appendix C) and follow guidelines for
selecting mnemonics and accelerators in Menu
Mnemonics.
- use common icons where applicable (see Common
Icons)
-
check that the finished GUI meets all
accessibility requirements – refer to Code
Considerations for Accessibility.
- provide HTML help, see Integrating on-line help
and IBM Director Help.
- set context help where applicable
- provide National Language Support (NLS) see NLS
for Console Extensions.
- provide a help pull-down on the menu with access
to help for the extension and optionally the IBM Director index (labeled
“Index”). All menu bar help pull-downs used in IBM Director Console extension windows must be consistent.
At the very least they should include help for the immediate window
and an “Index” entry that opens the IBM Director index.
- override the windowAttributesChanged function so
that the console extension will respond to user preference changes. Note
that you must call super.windowAttributesChanged() so that TWGTaskFrame can
update the status bar.
- optionally override verifyOnClose if you want the console
extension to prevent the window from closing if some criteria
meaningful to the extension has not been met
- override the pCleanUp method so that the console
extension can remove listeners and clean up all panels and widgets that it
constructs and uses when the task ends (note that super.pCleanUp() should
be called so that TWGTaskFrame can clean up). This is important to prevent memory leaks as the console
might be left open by a user for extended periods of time. See Preventing
Consol Memory Leaks for guidelines on GUI cleanup.
- If data is required from the server or the agent during construction of
the client panel in the buildView function, an asynchronous command
should be issued to procure it. The window should construct
its widgets and become visible as it awaits update with the data. If the
user sees window construction begin, the status indicator running and an
informative status message (such as "Loading…"), the user will
be comfortable that the task has started and that window content will be
forthcoming.
- Keep in mind that when a TWGTaskFrame is visible, GUI objects in
its client area should only be updated on the Event Dispatch Thread using
the invoke methods provided by javax.swing.SwingUtilities.
- If an asynchronous command for data that is to be processed and displayed
in the TWGTaskFrame client has been issued, developers need to be
cognizant of the fact that the data will probably not be returned on the
Event Dispatch Thread.
- Do NOT block the Event Dispatch Thread. If the Event Dispatch Thread is
blocked, events such as: paint events, window events, mouse events, will not be
addressed. Symptoms include windows that ignore user input, status
indicators that stop moving, and window real estate that becomes gray and
will not refresh. The Event Dispatch Thread can become blocked by a
synchronous SendCommand that takes a long time to return, by
excessive processing of data to ready it for the GUI and so on. If there is ever
a question as to whether processing is being done on the Event
Dispatch Thread, use javax.swing.SwingUtilities.isEventDispatchThread()
to check.
- Do NOT monopolize the Event Dispatch Thread. If the data to be loaded is
extensive, as in the case of the CIM Browser where some CIM classes contain
a large number of instances, it might be necessary to update the GUI in
installments, yielding interim updates so that other GUI processing (for
example, the status indicator, user input requests, window refreshes,
and so on), can
continue .
- For more information about the Event Dispatch Thread, see:
http://www.javaworld.com/javaworld/jw-06-2003/jw-0606-swingworker.html
The Inventory Query Browser in Figure 3 is an example of a TWGTaskFrame
object. Note that:
- the title bar contains the task name followed by the group or system to
which it has been applied
- the menu bar and tool bar are identical to those of the console. It uses a
colorful, animated icon for its toolbar
- the "Help" option on the menu bar contains a menu item for help
for the Inventory Query Browser and a menu item for the IBM Director Index
- the status bar is identical to that of the console. The Inventory Query
Browser used the super( true ) constructor to cause TWGTaskFrame
to construct a status bar and use the setStatusText() method to have
the status bar indicate that the Inventory Query Browser is ready to service
requests
- the Inventory Query Browser will use startStatusIndicator() and stopStatusIndicator()
to start and stop the status indicator whenever it processes requests
- the Inventory Query Browser has overridden windowAttributesChanged
so that it responds to user preference changes (see Figure 2)

Figure 3. Inventory Query Browser as an example of a TWGTaskFrame.
Some of the benefits of using
TWGTaskFrame
have been explained in the preceding section; this section focuses on the use of
the
TWGTaskFrame
class. You do not need to deal with the complexities
of integrating your GUI with the implementation of the interface; you
need only to provide a few simple methods to hook in your GUI code. This section describes those basic methods.
Refer to
com.tivoli.twg.console.TWGTaskFrame
for complete information on all of the methods provided.
- TWGTaskFrame()
-
There are two constructors provided for this class.
When the constructor runs, a JFrame is created and all of the
default color information is set up for this frame.
The main constructor takes a boolean as a parameter.
If true, the task frame is automatically created with a status panel.
The status panel, by default, contains a status indicator as its
left pane and a status text field as the right pane.
If false, the task frame does not have a status panel.
Note: The default constructor calls the main constructor with
the createStatusPanel parameter set to false.
The syntax of the constructors is:
public TWGTaskFrame()
public TWGTaskFrame( boolean createStatusPanel )
-
pInit()
-
This method is called after your class is constructed.
Implement your initialization routine for setting up non-GUI items here.
Derived classes override this method to perform their initialization.
If you need any information relating to this specific task activation,
just call getTaskActivator to get the
TWGTaskActivator
object containing all of the information about the task
activation related to this task frame.
Return true to have the frame continue initialization and be displayed.
Return false to prevent the frame from displaying and to end the
task console (for instance, if initialization fails).
The syntax of the pInit() method is:
public boolean pInit()
-
buildView()
-
This method is called just before the frame is sized, positioned, and shown.
Use this method to implement the GUI logic for the client area of your frame.
Derived classes override this method and build their client window and all of
the user interface controls (for example, entry fields, listboxes, buttons, and
so on)
required by their task's design.
Return the top-level panel for your GUI which is then
inserted into the client area of the frame.
The syntax of the buildView() method is:
public Container buildView()
Example:
public Container buildView()
{
// Construct the top level client pane that all gui panes are
// placed into. Add a border and set the layout.
JPanel clientPanel = new JPanel();
clientPanel.setBorder( new EmptyBorder( 10, 10, 10, 10 ) );
clientPanel.setLayout( new BorderLayout( 0, 10 ) );
// Create a prompt and an entry field and add to client pane.
JLabel prompt = new JLabel ( "Name:" );
JTextField nameField = new JTextField( "", 24 );
clientPanel.add( nameField, BorderLayout.CENTER );
clientPanel.add( prompt, BorderLayout.WEST );
return ( clientPanel );
}
-
getFrameSize()
-
This method is called by
TWGTaskFrame
to determine the initial size of the frame.
You should override this method to provide a task frame size that is appropriate
to your task console.
The initial position is centered by default.
Note: This method is only called the first time the task console is
opened
by a user.
When the task console is closed, the size and position are cached away
on a per user basis.
Subsequent invocations of this task console use the
cached size and position.
The syntax of the getFrameSize() method is:
public Dimension getFrameSize()
Example:
public Dimension getFrameSize()
{
return new Dimension( 500, 300 );
}
-
verifyOnClose()
-
This method allows derived task frames to prompt the user if they
should close or not.
Derived classes override this method to check internal conditions
and determine if it is okay to close
and, if conditions are not right, to correct them or prompt the user
for direction.
For example, if a user requests a task console to close
but has not yet saved information that was being editing, this
method can be used to prompt the user whether to save the
data before closing, to just close and lose the changes, or
cancel and continue editing.
Return true from this method to close the
frame, otherwise return false to stop the frame from closing.
Note: The task frame can only be stopped from closing if the
user initiated the close of the task frame, that is, cancelType equals
USER_REQUESTED_CLOSE.
If the IBM Director Management Console is
shutting down (MAIN_CONSOLE_SHUTDOWN), you cannot stop the frame
from closing.
The syntax of the verifyOnClose() method is:
public boolean verifyOnClose( int cancelType )
-
pCleanUp()
-
This method allows derived task frame classes to clean up after themselves.
Derived classes override this method to perform their cleanup.
This method is called when the task frame is definitely closing.
This
means that any user verification that might have been implemented
using verifyOnClose() has already completed and the user has indicated it
is okay to close.
The syntax of the pCleanUp() method is:
public void pCleanUp()
Your task frame is now built but you are unclear on how to use the status panel
or how to integrate your help information into IBM Director.
This section describes some of the other methods in
TWGTaskFrame
that you can use (yes,
you don't have to implement these, just use them) that are very
beneficial in making your console task extension act like IBM Director
console tasks.
Refer to
com.tivoli.twg.console.TWGTaskFrame
for complete information on all of the methods provided.
-
getHelpContext()
-
TWGTaskFrame
automatically creates a help context if the task
specifies the
helpTopicsMapping
attribute in the task's property file.
The
helpTopicsMapping
property specifies another property file that
contains the mappings of help topics to HTML help files.
A TWGTaskFrame
instance only has to request its context using
getHelpContext.
It can then associate help with any of the
components within the frame by using the addHelp() method on that
context.
If a
helpTopicsMapping
attribute is not specified, then no
context is created and this method returns null.
Refer to
Integrating online help into IBM Director
for complete information on using help contexts.
Note: Help cannot be specified directly on the frame itself,
but must be set on a component within the frame.
Typically the client pane of the frame is used.
If F1 is pressed
while the frame containing that component has focus, help is then invoked.
Additionally, if help is associated with a button or menu, pressing
that button or selecting that menu invokes help as well.
The syntax of the getHelpContext() method is:
public TWGHelpContext getHelpContext()
Example:
getHelpContext().addHelp( clientPanel, "MyTaskConsole.mainHelpId" );
-
setStatusText()
-
Use this method to specify the text that should be displayed in the
status field message area of the status panel.
The message string to display in the status field is passed in.
The syntax of the setStatusText() method is:
public void setStatusText( String text )
Example:
setStatusText( "Searching..." );
-
startStatusIndicator()
-
Use this method to start animating the frames contained in the
task frame's TWGStatusIndicator class.
This method does nothing
if your task frame does not contain a status indicator.
The syntax of the startStatusIndicator() method is:
public void startStatusIndicator()
-
stopStatusIndicator()
-
Use this method to stop animating the frames contained in the
task frame's TWGStatusIndicator class.
This method does nothing
if your task frame does not contain a status indicator.
The syntax of the stopStatusIndicator() method is:
public void stopStatusIndicator()
-
getTaskFrameServiceNode()
-
Use this method to get a reference to the task frame's service node.
The service node can be used to send commands via the SendCommand
and SendAsynchCommand methods. See IBM Director
Interprocess Communication for more information on ServiceNodes and
sending commands.
The syntax of the getTaskFrameServiceNode() method is:
public final ServiceNode getTaskFrameServiceNode() throws ServiceNodeException
IBM Director provides an on-line help browser that allows the user to request
help when using a specific console or panel by pressing the F1 key or clicking
on a help menu option or help button.
If you are creating your own console
task extensions, you might also want to provide help for your users that is
integrated as part of the IBM Director help system.
The
TWGHelpContext
class provides this integration.
TWGHelpContext is used for all IBM Director help associations.
A help
context provides the base structure to allow task frames and other windows
to associate a specific help panel with a specific frame window or dialog.
A component creates an instance of this class for their use,
passing in the instance of the main GUI and the name of the mapping
file to use to locate the correct HTML file for a specific topic ID.
This context is then used to associate help to components using the
addHelp method.
When help is invoked, the help context maps
the component to its associated help using the mapping file and the
current locale.
Sample Mapping File:
mainHelpTopicID = BobCo/MyTask/mymainhelp.html
mySetupPanelHelpTopicID = BobCo/MyTask/mysetuphelp.html
myInputPanelHelpTopicID = BobCo/MyTask/myinputhelp.html
This section describes how to use
TWGHelpContext
to integrate help into your console task extensions.
- TWGHelpContext()
-
If you are using
TWGTaskFrame,
you do not need this constructor.
The help context is automatically created for you
if you specified the
helpTopicsMapping
attribute in the property file of your task.
The constructor creates a help instance that is used to
bind and locate the correct help for a panel.
Each help instance has a mapping file that is used to map the
help topic IDs to specific HTML files.
This map finds the
appropriate HTML file based on the topic ID requested and the
current locale.
Two parameters are passed to the constructor.
The first is an instance of the main console controller.
This instance can be obtained from the
TWGTaskActivator
object.
Using this, IBM Director queries for the previous size and location used to display the
help window.
If null, then help is started using a default size
each time.
The second parameter is the name of the mapping file that contains
the mappings of the topic IDs to the HTML file names.
This file is in the same format as a regular properties file.
The syntax of the constructor is:
public TWGHelpContext( TWGMainGUI gui, String bundleName )
Example:
TWGHelpContext ivHelp = null;
String mapFile = getTaskActivator().getTask().getHelpTopicsMapping();
if (( mapFile != null ) && ( !mapFile.equals("")))
ivHelp = new TWGHelpContext( getTaskActivator().getMainConsole(),
mapFile );
- addHelp()
-
Use this method to register a help listener to initiate a help
event for this component.
If the component specified is a button
or a menu item, an action listener is registered with the component.
This means a help event is generated if the button is pressed
or if that menu item is selected.
If the component is not
a button or menu item, then it registers F1 as the key that
initiates a help event if the component specified (or the window it
is in) has the focus.
The help event contains the topic ID as event data.
Two parameters are passed to this method.
The first is the component to register the help for.
The second is the topic ID
which identifies the help panel to display when help is requested.
The topic ID must be found in the mapping file.
If null is set, then dynamic help is set up for the component and the
component is queried for the topic ID (and optionally a
different mapping file) when help is requested.
Refer to
TWGDynamicHelp
for information on this advanced topic.
The syntax of the addHelp() method is:
public void addHelp( JComponent comp, String topicID )
Example:
ivHelp.addHelp( clientPanel, "mainHelpTopicID" );
- removeHelp()
-
Use this method to unregister the help listener that would initiate
a help event if the component specified (or the window it is
in) has the focus.
This removes an action listener or keyboard action previously
set up, depending on which kind of listener was originally set up.
The only parameter passed into this method is the
component to unregister the help from.
Note: You should always remove any help associated with
components as part of your cleanup when your task frame is going away.
The syntax of the removeHelp() method is:
public void removeHelp( JComponent comp )
Example:
ivHelp.removeHelp( clientPanel );