Repository :
http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
---------------------------------------------------------------
commit 7ee33e3a956b3d4e171a5de53a4e246f09f32ac1
Author: Stephen Gallagher <sgallagh(a)redhat.com>
Date: Tue Nov 26 13:54:19 2013 -0500
Improve lmishell indication documentation
---------------------------------------------------------------
cli/lmi/shell/LMIIndicationListener.py | 4 +
doc/src/indications.rst | 99 ++++++++++++++++++++------------
2 files changed, 67 insertions(+), 36 deletions(-)
diff --git a/cli/lmi/shell/LMIIndicationListener.py
b/cli/lmi/shell/LMIIndicationListener.py
index c8647bf..5b76f06 100644
--- a/cli/lmi/shell/LMIIndicationListener.py
+++ b/cli/lmi/shell/LMIIndicationListener.py
@@ -149,6 +149,8 @@ class LMIIndicationListener(object):
"""
Starts a indication listener.
+ The indication listener runs in a newly-created thread.
+
:returns: True, if the indication listener started with no errors; False
otherwise
"""
try:
@@ -170,6 +172,8 @@ class LMIIndicationListener(object):
def stop(self):
"""
Stops the indication listener.
+
+ This method will also terminate the listener thread.
"""
if self._server:
self._server.shutdown()
diff --git a/doc/src/indications.rst b/doc/src/indications.rst
index d29a77d..50f8730 100644
--- a/doc/src/indications.rst
+++ b/doc/src/indications.rst
@@ -1,8 +1,59 @@
Indications
===========
Indication is a reaction to some specific event that occurs in response to a
-change to a particular change in data. LMIShell can perform a indication
-subscription, by which we can receive such event responses.
+particular change in data. LMIShell can perform an indication subscription, by
+which we can receive such event responses.
+
+
+
+Indication handler
+------------------
+The first step is to set up an indication handler. This is a routine that will
+be triggered when the OpenLMI sends us an indication for which we have
+registered (see below). It is important to set up the handler first so that we
+can generate a unique registration name and avoid conflicts with other clients
+that may wish to register for the same indication. The indication handler may
+be part of the same process that will initiate the provider registration or it
+may be an independent script, but the unique registration name must be
+acquired first in either case.
+
+The following example describes creating a handler and a listener for an
+indication:
+
+.. code-block:: python
+
+ > def handler(ind, arg1, arg2, **kwargs):
+ ... exported_objects = ind.exported_objects()
+ ... do_something_with(exported_objects)
+ > listener = LMIIndicationListener("0.0.0.0", listening_port)
+ > unique_name = listener.add_handler("indication-name-XXXXXXXX",
handler, arg1, arg2, **kwargs)
+ > listener.start()
+ >
+
+The first argument of the handler is an :py:class:`LMIIndication` object,
+which contains the list of methods and objects exported by the indication.
+The other arguments are handler-specific; Any number of arguments may be
+specified as necessary; those arguments must then be provided to the
+:py:meth:`.LMIIndicationListener.add_handler` method of the listener. In the
+above example, the string used in the
+:py:meth:`.LMIIndicationListener.add_handler` call is specified with eight
+**"X"** characters. Those characters will be replaced by unique string, which
+is generated by the listeners to avoid a handler name clash. Use of this
+uniqueness capability is not mandatory but is highly recommended. The
+substituted name is returned as the result of the
+:py:meth:`.LMIIndicationListener.add_handler` method so it can be used later.
+
+The :py:class:`LMIIndicationListener` constructor takes up to four
+arguments, two mandatory (hostname and port) and two optional when using SSL
+(certfile and keyfile). It returns an :py:class:`LMIIndicationListener`
+object.
+
+The :py:meth:`.LMIIndicationListener.start` method creates a new thread and
+runs an HTTP service in that thread, awaiting indications from the CIMOM. This
+method will continue to run until :py:meth:`.LMIIndicationListener.stop` is
+called or the current application exits.
+
+
Subscribing to an indication
----------------------------
@@ -18,7 +69,7 @@ How to subscribe to an indication, please, follow the next example:
c.subscribe_indication(
...
QueryLanguage="WQL",
... Query='SELECT * FROM CIM_InstModification',
- ... Name="cpu",
+ ... Name=unique_name,
... CreationNamespace="root/interop",
... SubscriptionCreationClassName="CIM_IndicationSubscription",
... FilterCreationClassName="CIM_IndicationFilter",
@@ -27,7 +78,7 @@ How to subscribe to an indication, please, follow the next example:
... HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
... HandlerSystemCreationClassName="CIM_ComputerSystem",
... # destination computer, where the indications will be delivered
- ... Destination="http://192.168.122.1:5988"
+ ... Destination="http://192.168.122.1:%d" % listening_port
... )
LMIReturnValue(rval=True, rparams={}, errorstr="")
@@ -49,7 +100,7 @@ Simplified subscription:
c = connect("host", "privileged_user",
"password")
c.subscribe_indication(
- ... Name="cpu",
+ ... Name=unique_name,
... Query='SELECT * FROM CIM_InstModification',
... Destination="http://192.168.122.1:5988"
... )
@@ -79,47 +130,23 @@ To list all the subscribed indications, run following code:
> subscribed_ind_lst = c.subscribed_indications()
-Unsubscribing from an indications
+Unsubscribing from an indication
---------------------------------
By default, the subscriptions created by the shell are auto-deleted, when the
shell quits.
-If you want to delete the subscriptions sooner, you can use following methods:
+If you want to delete the subscriptions sooner, you can use the following methods:
+
+To unsubscribe from a specific indication:
.. code-block:: python
- > c.unsubscribe_indication(indication_name)
+ > c.unsubscribe_indication(unique_name)
LMIReturnValue(rval=True, rparams={}, errorstr="")
- > c.unsubscribe_all_indications()
- >
-
-Indication handler
-------------------
-In the previous example, there is a local computer specified (the one, which
-runs the shell), now we need to start a indication listener with our indication
-handler function defined. This example continues (see previous one). It is also
-possible to start another shell, script and start the indication listener
-there.
-See the following example:
+Or to unsubscribe from all indications:
.. code-block:: python
- > def handler(ind, arg1, arg2, **kwargs):
- ... exported_objects = ind.exported_objects()
- ... do_something_with(exported_objects)
- > listener = LMIIndicationListener("0.0.0.0", listening_port)
- > listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2,
**kwargs)
- > listener.start()
+ > c.unsubscribe_all_indications()
-
-The first argument of the handler is :py:class:`LMIIndication` object, which
-contains list of methods and objects exported by the indication. Other
-parameters are user specific; those arguments need to be specified, when adding
-a handler to the listener. In the example, there is a special string used in
-the :py:meth:`.LMIIndicationListener.add_handler` call; note the eight **"X"**
-characters. Those characters will be replaced by random string, which is
-generated by the listeners to avoid handler name clash. If you want to use that
-random-based string, start indication listener first, then subscribe to an
-indication, so the *Destination* property of a handler object contains
-``<schema>://<hostname>/<random-based string>``.