Getting started with indications

The prerequisite for receiving indications is at least one existing subscription on a CIMOM. It is out of the scope of this document to explain the creation of subscriptions. Please see the corresponding DMTF standards.

The delivery of indications reverses the roles of client and server. The CIMOM acts as HTTP client, the client as an HTTP server. The indication delivery is asynchronous and completely independent from an open client-to-CIMOM connection.

Setting up an indication listener

The following code snippet illustrates how to set up a simple indication listener.

/**
 * Starts a indication listener
 * @param port The TCP port to listen on
 * @param ssl Set true if you want to listen on a secure (SSL) socket  
 */ 
private HttpServerConnection startIndicationListener(int port, boolean ssl) {

   CIMIndicationListenertList listeners = new CIMIndicationListenertList();
   indicationClient.addListener(new CIMListener() {
      public void indicationOccured(CIMEvent pEvent) {
         System.out.println("Received indication from "+pEvent.getInetAddress()+" on local path"+pEvent.getID());
         System.out.println("Indication instance: "+pEvent.getIndication());
      }
   });

   CIMEventDispatcher dispatcher = new CIMEventDispatcher(listeners);
   CIMIndicationHandler handler = new CIMIndicationHandler(dispatcher);

   try {
      HttpServerConnectionserver = new HttpServerConnection(new HttpConnectionHandler(handler), port, ssl);
      server.setName("CIMListener - Http Server");
      server.start();
      return server;
   } catch (Exception e) {
      dispatcher.kill();
   }
   return null;
}
       

This sample will listen for indication on the given socket. Every indication received is dispatched to the single registered CIMListener that prints the event details to stdout. In a real world application you would replace the System.out.println() with your indication processing code.

Note: Once you add more than one CIMListener to the CIMIndicationListenerList the indications will be dispatched by the local path information. The CIMIndicationListenerList will look for a CIMListener where hashcode()==String.valueOf(localpath). Therefore you need to specify the corresponding listener's hashcode in the subscription: CIMListenerDestinationCIMXML.destination="protocol://ip_address:port/hashcode". Note that this dispatching scheme is only applied if you add multiple CIMListeners to one CIMIndicationListenerList. If you want to share a single port between multiple listeners without being restricted to specify the listener's hashocde as local path you might add only a single one that dispatches on your own criteria.

In order to stop listening and free the socket just call HttpServerConnection.close()

.

Alternative, but deprecated way

The CIMClient class offers a method addCIMListener(). If you call this method and pass your CIMListener it will start up a complete indication listener. This listener is bound to the next free TCP port and always unsecure (no SSL). With the method getIndicationListener() you get an CIMListenerDestinationCIMXML instance to use for subscribing.

This pattern has three weak points.

  1. First the lifetime of the listener is bound to the lifetime of the client connection. Means CIMClient.close() will shutdown the listener too.
  2. You cannot secure the indication delivery with SSL.
  3. You cannot specify to listener port.
Since we strongly believe that tying listeners and client connections together is a bad thing, this way is regarded as deprecated.