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.
The following code snippet illustrates how to set up a simple indication listener.
/** * Starts a indication listener that dumps every received indication to System.out * @param port The TCP port to listen on * @param ssl Set true if you want to listen on a secure (SSL) socket * @return The indication listener instance. Call removeLister() to stop the listener. */ private WBEMListener startIndicationListener(int pPort, boolean pSsl) throws IOException { try { WBEMListener listener = WBEMListenerFactory.getListener("CIM-XML"); listener.addListener(new IndicationListener() { public void indicationOccured(String pIndicationURL, CIMInstance pIndication) { System.out.println("Indication received on: " + pIndicationURL + ":"); System.out.println(pIndication.toString(); } }, pPort, pSSL ? "https" : "http"); return listener; } catch (IOException e) { System.err.println("Failed to bind socket to port "+pPort); throw e; } } }
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.
In order to stop listening and free the socket just call removeListener(int pPort)
The WBEMListener
is a singleton that keeps a map of socket listerners keyed by port. On
multi-homed systems it is possible to bind the listener to a given IP only. The WBEMListenerSBLIM
class offers an additional signature of addListener()
that allows to pass individual configuration
properties.
When you start an indication listener you start a little HTTP server. This server has to fullfill the usual duties: Wait for incoming connections, handle them (also concurrently), parse the request, send a response, create a CIM indication and forward it to the corresponding indication listener from you application.
This duties are handled by four layer each of which runs in one or more seperate threads (compare with picture).
When you subscribe on multiple CIMOMs you have to be able to distinguish which CIMOM is the origin of a particular indication. This is not as easy as it seems since an indication doesn't have sender information. Therefore the common way is to make the destination unique in the subscription. This can be done by either using an individual port per subscription or by using an individual local path per subscription. The first option creates more overhead in the client since we have to start a seperate HTTP server for each port. Therefore we recommend to use the second option.
We have 5 configuration options that allow you to fine tune the indication listener. All of them are coupled together and wrong setting might harm our ability to receive indications.
http timeout | min pool size | max pool size | backlog | idle timeout | remarks |
---|---|---|---|---|---|
10s | 2 | 8 | 2 | 30s | Default setting. Will keep number of handlers low & stable. Aggressive http timeout and two handlers always open will keep vulnerability low. |
60s | 0 | 8 | 0 | 10s | More dynamic handler allocation. Will destroy all handlers fast when idling and create them without delay on traffic. Allows higher http timeout. |
60s | 0 | 8 | 0 | 120s | Similliar to default but keeps handler count stable by long idle timeout instead of backlog. Makes it less vulnerable against blocking, but keeps handler open long after traffic peeks. Needs in average more handlers than default. |
10s | 0 | 2 | 0 | 10s | Resource saving: maximum of two handlers, aggressive http timeout, short idle timeout. Will keep number of handlers low but is heavily creating & destroying it's handlers. |