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 that can be overridden by the application to respond to health status requests from Manager, along with handling any Custom Messages.

In addition to responding to the communication from the Managers, these member functions can be implemented to support various application needs, including changing parameter values in the application or causing 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 started application code does not return quickly. However, if one of these functions does not return, then all subsequent health requests and Custom Messages from any Manager are blocked.

The following sections describe the various implementation strategies for this class and its member functions.

Implementing Default Behavior

If the Listener is always 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 can 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:
  • As a PCHcallable object, which is used by developers to obtain the default behavior as defined by Content Cortex.
  • Using null (default), which causes the constructor to automatically create a PCHcallable object for the application with the basic, default behavior as defined by Content Cortex.

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 by using the following signature:
bool getHealth(void);

When a Manager sends a health status request to the Listener, the Listener calls back to the getHealth member function to determine whether the application is up and operating normally. The function measures the operating behavior of the functionality that is 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 returns true. This is the basic, default behavior as defined by Content Cortex. However, the function returns false when it determines 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 returns false.

Processing Custom Messages

Any connected Manager can 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 through 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 return immediately. This is the basic, default behavior as defined by Content Cortex. However, the usual implementation would be for at least one of these functions to perform extra processing. For example, the function can 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.