Extending the Java-based agent

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

Agent extension facility

The Java-based agent supports different types of extensions. All extensions:

The built-in types of Java-based agent extensions are:

Agent extension properties file

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).

Agent extension life cycle

Following is a description of the life cycle of an agent extension in the context of agent processing.

  1. Properties file is loaded.
  2. TWGAgentExtension subclass is instantiated (if specified).
  3. Each service node specified on a service node property (if any) is registered (and prestarted, if specified).
  4. The agent extension is initialized by calling the TWGAgentExtension subclass' initAgentExtension() method.
  5. 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.
  6. The agent extension is given an opportunity to own the extension's main thread by calling the TWGAgentExtension subclass' runAgentExtension() method.
  7. When the agent extension is terminated the TWGAgentExtension subclass' terminateAgentExtension() method is called allowing it to perform any cleanup.

Creating a subagent

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.

Creating a monlet

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.

Creating an event provider

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.

Debugging a Java-based Agent extension

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:

  1. 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.
  2. 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.
  3. 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.