The first step in using the FileNet® System Manager Listener Java™ API is to instantiate the Listener object to listen for connections from Managers. The application should only create one Listener object and once created, the Listener must exist for the lifetime of the application. The syntax for instantiating the Listener is as follows:
Listener listener = new Listener("appName", "appVersion",
[optional] heartbeatObject, [optional] enabled);
The appName and appVersion
parameters are
Unicode Strings that provide the name and version number of the application
and can contain any printable characters excluding the newline character.
The heartbeatObject
is an optional parameter that
provides the Listener with the ability to handle health status requests or Custom
Messages received from connected Managers. This parameter must be null or an
object implementing the PCHcallable interface.
If it is null or unspecified, then an instance of the defaultCallable
class, which is a stubbed-out implementation of the PCHcallable interface, will
be used. For more information about implementing this class, see Supporting
Communication from Managers.
The enabled
parameter is an optional Boolean value that
indicates whether the Listener object should actually be enabled to create background
threads, open sockets, write to log files, and so on. When set to false, the application
can easily "turn off" this Listener functionality if necessary. When
this parameter is not specified, it defaults to true unless the filenet.pch
Java system property exists and the value of the property is set to disabled.
However, even when the Listener is not enabled, objects are still created and
can be accessed in the usual manner from the Listener APIs.
The aggregation interval is the length of time over which each summary block of performance data is accumulated by the Listener. At the end of each aggregation interval, the Listener computes a summary block (basically, a snapshot of the current counter values), sends this summary to any Managers that have requested automatic updates, and then resets the min and max values associated with the Accumulators. This summary block is also added to a running history maintained by the Listener, which allows newly-connecting Managers to request information about recent application activity.
Although an application may configure the aggregation interval, the value is normally left to the default or specified by the Manager. The interval value can be specified in the following ways:
output_count
and output_interval
configuration parameters. For more information
about modifying these parameters, see Configuring
the Listener.listener.setInterval(interval);
When the application is going to exit, it may call the shutdown method of the Listener to record any partial summary blocks and guarantee that the final gathered performance data will not be lost:
listener.shutdown();
However, it is not necessary for the application to directly call shutdown as the finalize method of the Listener object will also call shutdown.
CAUTION If the application exits without
calling either the finalize method of the Listener or shutdown, then the most
recent performance data which was being added to the current summary block will
be lost, but there will be no other negative consequences.