Repository : http://git.fedorahosted.org/cgit/cura-tools.git
On branch : 0.9-fixes
commit 400248efc1b92873074a3b729114c8fa7435b106 Author: Stephen Gallagher sgallagh@redhat.com Date: Tue Nov 26 13:54:19 2013 -0500
Improve lmishell indication documentation
Conflicts: doc/src/indications.rst
cli/lmi/shell/LMIIndicationListener.py | 4 ++ doc/src/indications.rst | 84 +++++++++++++++++++++++-------- 2 files changed, 66 insertions(+), 22 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 096d807..6cdcb69 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="") > @@ -55,38 +106,27 @@ 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