Supporting Communication from Managers

When the Listener object is instantiated, the third parameter to the constructor must be a PCHcallable object. The PCHcallable class provides member functions which may be overridden by the application to respond to health status requests from Manager, as well as to handle any Custom Messages.

In addition to responding to the communication from the Managers, these member functions may be implemented to support a variety of application needs, 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, System Manager processing cannot become "stuck" if invoked application code does not return quickly. However, if one of these functions 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 member functions.

Implementing Default Behavior

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:

Handling Health Status Requests

In order for the application to respond to health status requests from a Manager, the third parameter to the Listener constructor must be a PCHcallable object which implements the getHealth member function using the following signature:

bool getHealth(void);

When a Manager sends a health status request to the Listener, the Listener will call back to the getHealth member function to determine if the application is up and operating normally. The function 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 function should simply return true. This is the basic, default behavior as defined by FileNet. However, the function 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 member function should return false.

Processing Custom Messages

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 in two forms: UTF-8 and Unicode, via one of the following function signatures:

void processCustomMessage(const char *message);
void processCustomMessage(const wchar_t *message);

If the application does not support Custom Messages, then these two functions should simply return immediately. This is the basic, default behavior as defined by FileNet. However, the usual implementation would be for at least one of these functions to perform additional processing. For example, the function 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.