Cassatt Event Registration Interface (CERI): Writing Client Programs for Use With Cassatt Active Response

Intended for use with Cassatt Active Response Standard Edition, Premium Edition and Data Center Edition V5.1.

What is it?

The Cassatt Event Registration Interface (CERI) provides a programmatic way to access Cassatt Active Response system events. You can use this interface when you want to programmatically leverage Cassatt Active Response events to trigger other actions in your environment. For example, say you want to populate a site CMDB with inventory data collected by Cassatt Active Response, to communicate with load balancing software to modify application node configuration, or to otherwise modify behavior based on the state of application nodes in a Cassatt Active Response environment. You just need to write a client program that registers with the CERI server, interprets the incoming event stream, and modifies system behavior or configuration based on those events.

The CERI is a set of Java library classes and methods needed to register and authenticate requests from a calling application. CERI is available on the Cassatt Active Response distribution media as a JAR file. You simply place the JAR where you want your client program to run, ensure the JAR is in the classpath, and execute your client program. The JAR also includes a sample program. If you want to see the entire program, click Sample CERI client program, but I will highlight key sections of it in this article. (There is also a sample shell script named watch that you can use to run the sample program. Just modify the classpath and connection parameters for your site before running the program. Then it will output the various events provided by CERI.)

top

Writing a CERI client application

A CERI client program minimally needs to do the following to successfully communicate with the CERI server and receive Cassatt Active Response events:

• Register with the CERI server on the control node via the registerClient() method.
• Implement the following three public interface methods:
  • processEvent() – this method does the bulk of the work for your client program. Based on the Cassatt Active Response events it receives, you can trigger other actions (defined by the processEvent() method) in your environment to meet your configuration goals.
  • reStart() – this method is used to notify the client application that a Cassatt Active Response control node restart is going to occur and to expect a new initialization event when the control node comes back online.
  • unregistered() – this method is called when the CERI server unregisters a client that has thrown an exception. The CERI server returns the exception to the client via the unregistered() method. To start receiving events again, the client application needs to re-register with the CERI server.

The CERI client JAR file provides a Java interface class named EventReceiver that defines these methods. A CERI client application must pass an implementation class of this interface to the registerClient() method to successfully register with the CERI server.

Now, let's take a look at the sample program in the CERI JAR file to see how to register and implement these methods.

top

Registering with CERI server

The sample program is called CollageEventWatcher. In it, you'll see the following try block, which registers with CERI and then enters a loop to receive events as they are supplied by Cassatt Active Response, and then unregisters the client. Notice that the registerClient() method includes user, password, and host access information. This information is used by the CERI server to authenticate the client registration.

try {
    NotificationClient.registerClient(user, pw, host, rmiPort, 
                                   namingPort, eventReceiver);
    if (verbose) {
        System.err.println("Registration request complete.");
        System.err.println("");
 }

while (true) {
   // keep alive
   for (int i = 0; i < LOOPS; i++) {
      try {
          Thread.sleep(SLEEP_INTERVAL);
      } catch (final InterruptedException ie) {
    // deliberately ignored
      }
   }
}

} catch (Exception e) {
      if (verbose) {
         System.err.println("Failed to register event 
                        receiver with Collage: " + e);
   }
} finally {
      NotificationClient.unregisterClient(
                       eventReceiver.getReceiverId());
      if (verbose) {
         System.err.println("Unregistered event receiver 
            with Collage: " + eventReceiver.getReceiverId());
      }
 }
}                   

top

Processing events

The first method you must implement in your CERI client program is processEvent(). The processEvent() method does the work of your CERI client program. In the sample client program, processEvent() simply prints events as they are reported from the CERI server. In your own program, this is where you would put the logic to modify your site configuration or system behavior. The receiverID is the unique ID CERI assigns to each event receiver. This ID is needed for the client to unregister with CERI.

     public void processEvent(final UUID myReceiverId, final Event event) {
         System.out.println("CollageEventWatcher received event: ");
         System.out.println(event);
         System.err.println("");

         receiverId = myReceiverId;
     }

top

Handling restarts

The second method you must implement is reStart(). This method is used in the case where the Cassatt Active Response control node has been restarted. The reStart() method serves as an indicator to the client to expect an initialization event after the Cassatt Active Response restart occurs. Here's the implementation of reStart() from the sample CERI client program:

     public void reStart(final UUID myReceiverId) {
        System.out.println("CollageEventWatcher notified of a re-start.");
     }

top

Handling failures

The last method you are obligated to implement is the unregistered() method. This method is used by CERI to pass back debug data when the client operation fails. If the client does not call the unregisteredClient() method, CERI will unregister the client after it looses communication (for example, on a failed attempt to invoke processEvent() on the client).

     public void unregistered(final Throwable throwable) {
        System.out.println("CollageEventWatcher un-registered with cause: " + throwable);
     }

top

Event types

CERI provides the following types of events to client programs:

You can look at the sidebar Sample event output to see how the CERI server outputs events. Now, though, let's examine the data provided by each type of Cassatt Active Response event.

top

Event data definitions

The following tables show the data provided by each type of event.

InitializationEvent data

top

NodeInventoryEvent data

^† CERI returns inventory data in an XML string. This data is defined in the XSD included in the CERI JAR file.

top

NodeConfigurationEvent data

top

ServiceConfigurationEvent data

top

Was this article useful? Tell us what you think.
Email infocentral@cassatt.com.