When the Listener object is instantiated, the third parameter to the constructor 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. This interface provides methods which may be overridden by the application to respond to health status requests from Manager, as well as to handle any Custom Messages.
These methods may be implemented to support a variety of application needs when responding to communication from Managers, including changing parameter values in the application or causing the application to perform certain actions, such as dumping the current application state to a log file. A separate background thread is used for processing all received requests and messages. Therefore, IBM® System Dashboard for Enterprise Content Management processing cannot become "stuck" if invoked application code does not return quickly. However, if one of these methods should not return, then all subsequent health requests and Custom Messages from any Manager will be blocked.
The following sections describe the various implementation strategies for this class and its methods.
In order for the application to respond to health status requests from a Manager, the third parameter to the Listener constructor must be null or an object implementing the PCHcallable interface. If it is null or unspecified, then an instance of the defaultCallable class. This class is a stubbed-out implementation of the PCHcallable interface which implements the getHealth method using the following signature:
boolean getHealth();
When a Manager sends a health status request to the Listener, the Listener will call back to the getHealth method to determine if the application is up and operating normally. The method should measure the operating behavior of the functionality supported by the application and return true or false according to the test results. If it is impossible for the application to be up and yet not operating normally, then the method should simply return true. This is the basic, default behavior as defined by FileNet®. However, the method should return false when it has been determined that some portion of the application behavior is not available or operating as expected.
For example, suppose that a provided service depends on the availability of a remote database server. If that server is down or unreachable, then the provided service is unavailable as well, even though the server itself is up and running (and presumably, periodically attempting to reconnect to the database). In such a situation, the getHealth method should return false.
Any connected Manager may send application-specific messages to the Listener. When a Custom Message is received, it is passed to the application by the Listener as a Unicode String using the following method:
void processCustomMessage(String message);
If the application does not support Custom Messages, then this method should simply return immediately. This is the basic, default behavior as defined by FileNet. However, the usual implementation would be for this method to perform additional processing. For example, the method could write to a log file when an unexpected message is received and not processed.
For more information about sending Custom Messages to connected Managers, see Recording Custom Messages.
If the Listener will always be up and responding when the application is operating normally, and if the application does not need to process any Custom Messages, then the default behavior may be implemented. The default behavior for the Listener is to always return a value that indicates that the application is up and operating normally. This is accomplished by specifying the third parameter of the Listener constructor as follows: