This topic describes the steps required to create and register an IBM Director Java-based
agent extension. "Java-based agent" refers to a Java implementation of the IBM Director Agent
supported on particular operating system platforms (such as the Linux).
To better understand the basic nature of an agent and the requirements of IBM Director
server-to-agent communication, see Creating and registering an agent service.
Subtopics
Related topics
Related sample code
The Java-based agent supports different types of extensions. All extensions:
- must define a properties file containing basic properties of the extension and extension type-specific properties.
- might identify service node name(s) to register with the agent (and optionally prestart).
- might define a
TWGAgentExtension
subclass which overrides exit methods to perform initialization, running, and termination.
- have their
TWGAgentExtension
subclass methods and service node(s) (if defined) run in their own protected thread group.
If an unhandled exception occurs in the extension's thread group, only the extension's thread
group is ended (after an error is logged to file /opt/IBM/director/log/extname.err
where extname is the extension name).
The built-in types of Java-based agent extensions are:
- Base agent extension ("subagent"). A subagent is the base type of agent extension
which is started and ended by the main agent itself.
A subagent might optionally provide interprocess communication (IPC) enabled services
which can communicate with other IPC-enabled components (service nodes) on the IBM Director server, agent
and console.
Built-in IBM Director agent services such as monitoring and inventory are implemented as subagents
themselves.
- Monitor agent extension ("monlet"). The monlet extension type is managed and used by the built-in
monitor subagent. A monlet instruments monitorable attributes to extend the tree of attributes provided
by the built-in monitor subagent. The monitor subagent uses the agent extension facility to find and load its
subextensions (monlets).
Similar to IBM Director Server extensions, Java-based agent extensions
are discovered by the IBM Director agent at initialization by searching directory
/opt/IBM/director/classes/extensions for file names with a suffix that matches one of the
supported extension types (including built-in types TWGSubagent and TWGMonlet.)
The files found are loaded as Java properties files.
The following properties apply to all extension types:
Note: At least one of the following properties must be defined or the extension will fail to load:
twg.extension.classname, twg.extension.servicenode.x
- twg.extension.classname
- Specifies the fully qualified name of the TWGAgentExtension subclass to load and instantiate.
- twg.extension.servicenode.x where x is a consecutive integer for each instance of the property starting at 0.
- Specifies a service node name to register for the extension. Registered service nodes can be discovered
by IBM Director servers.
Example: twg.extension.servicenode.0 name:myService | classname:com.BobCo.myServiceNodeClass | prestart:true
The following keyword+value pairs are recognized for this
property value, using "|" as a separator between keywords:
- name (required)
- Service node name to register.
- classname (required)
- Fully qualified ServiceNode subclass to register for the service.
- prestart (optional; default is false)
- When true the service node is created at initialization time, otherwise the service node is created on demand when
an IPC command is sent to the service or the service is started by the agent service manager (SvcMgr service node).
- twg.extension.nlsclassname (optional)
- Specifies the fully qualified name of the Java class that is a ResourceBundle containing translatable strings.
- twg.extension.name
- Provides a place to specify the name of the extension. This can be either a label to retrieve a string from the ResourceBundle or a literal string value.
- twg.extension.version
- Provides a place to specify a version number
- twg.extension.vendor
- Provides a place to specify the name of the vendor that implemented the extension. This can be either a label to retrieve a
string from the ResourceBundle or a literal string value.
- classpath.prepend.x
- where x is a consecutive integer for each instance of
the property starting at 1.
Specifies the relative or fully-qualified pathname of the JAR file or
classes directory that contains your Agent Extension class files. This name
is prepended to the agent's classpath when your extension is loaded.
Relative paths are relative to the home directory of the Director
product. On Windows NT, the home directory is usually x:\Program Files\IBM\Director, where
x: is the logical drive. For Linux platforms, the home directory is usually
/opt/IBM/director.
- classpath.append.x
- where x is a consecutive integer for each instance of
the property starting at 1.
Specifies the relative or fully qualified pathname of the JAR file or
classes directory that contains your Agent Extension class files. This name
is appended to the agent's classpath when your extension is loaded.
Relative paths are relative to the home directory of the IBM Director agent,
as described above for prepends.
- Other
- Other twg.* names are reserved for future standard variables. Extensions might define other variables with names other than
twg.*. TWGAgentExtension subclasses can access these property values with method
getProperty(String name).
Following is a description of the life cycle of an agent extension in the context of agent processing.
- Properties file is loaded.
-
TWGAgentExtension
subclass is instantiated (if specified).
- Each service node specified on a service node property (if any) is registered (and prestarted, if specified).
- The agent extension is initialized by calling the TWGAgentExtension subclass'
initAgentExtension() method.
- After all agent extensions are initialized, the agent is considered active and it sends out notification
to its IBM Director server(s) that it is active. If the agent extension initialization timeout (60 seconds) expires
before all extensions are active, the agent becomes active regardless of whether agent extensions have completed initialization.
- The agent extension is given an opportunity to own the extension's main thread by calling the TWGAgentExtension
subclass'
runAgentExtension() method.
- When the agent extension is terminated the TWGAgentExtension subclass'
terminateAgentExtension() method
is called allowing it to perform any cleanup.
A base agent extension (subagent) might optionally provide a subclass of
TWGAgentExtension
and override its exit methods listed in the agent extension life cycle description above.
It might also register service node(s) via the
twg.extension.servicenode.x properties. As an alternative to the service node property,
an extension might call the methods
registerService()
to register a service during initialization and
deregisterService()
to deregister a service during termination.
A TWGMonlet extension properties file must identify a
TWGAgentExtension
subclass name for property
twg.extension.classname. In addition to extending TWGAgentExtension,
the class must implement
the Monlet interface.
A monlet provides a tree of monitorable attributes where the root node of a monlet's attribute tree
is a child node of the "IBM Director Agent" node (the monitor agent's root node).
A monlet must define a unique programmatic node name for its root node on property
twg.monlet.root.name. This property value is also used as the string ID to retrieve
the NLS string displayed for the root node from the monlet's resource bundle.
If no NLS string is defined for the string ID, the string ID itself is used as the displayed node name.
A properties file with a suffix EventProviderExt needs to be in the /opt/IBM/director/classes/extensions directory.
The only property is event.provider.classname.
- event.provider.classname
- Specifies the fully qualified name of the class that implements
EventProvider interface.
The Java-based agent uses the same trace logging facility as the IBM Director server, with differences noted below.
For details on using IBM Director trace logging in your Java extension, see
Controlling IBM Director logging.
Notable differences in trace logging for the Java-based agent versus IBM Director Server are:
- The trace log output goes to the binary files
/opt/IBM/director/log/TWGRas.log on UNIX-based operating systems,
C:\Program Files\IBM\director\log\TWGAgentRas.log on Windows-based operating systems
with both the IBM Director Server and agent installed, and
C:\Program Files\IBM\director\log\TWGRas.log on Windows-based operating systems with
only the IBM Director Agent installed.
If IBM Director is not installed in the default directory, the
log files will be located in the log subdirectory in the IBM Director installation directory.
- When STDOUT and STDERR output streams are enabled, they are piped to a text file in the
log directory with a file extension of .stdout.
- To view log output,
use the RasDump and RasView tools to operate against the TWGAgentRas.log
and TWGRas.log file. The RasView tool is similar to the RasWatch tool;
it dynamically reads and shows updates to a log file.
To run the RasView program, set the current directory to the log directory and enter
the command
RasView logfilename
If the logfilename parameter is
not specified, RasView defaults to viewing TWGRas.log.