Repository :
http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
---------------------------------------------------------------
commit b8adab461155944c176ff6a6ea710cbbcdb2eb80
Author: Peter Hatina <phatina(a)redhat.com>
Date: Wed Oct 8 13:17:50 2014 +0200
doc: lmishell's documentation update
There are several changes that popped out when Jan started working on the new OpenLMI
docs. The patch reflects most of desired changes listed here:
https://lists.fedorahosted.org/pipermail/openlmi-devel/2014-October/00238...
---------------------------------------------------------------
doc/src/shell/associated_objects.rst | 12 ++++-
doc/src/shell/classes.rst | 22 ++++----
doc/src/shell/indications.rst | 98 ++++++++++++++++++++--------------
doc/src/shell/instance_names.rst | 2 +-
doc/src/shell/instances.rst | 19 +++++--
5 files changed, 92 insertions(+), 61 deletions(-)
diff --git a/doc/src/shell/associated_objects.rst b/doc/src/shell/associated_objects.rst
index 42f0e1f..3610aea 100644
--- a/doc/src/shell/associated_objects.rst
+++ b/doc/src/shell/associated_objects.rst
@@ -1,7 +1,15 @@
Associated Objects
==================
-CIM defines an association relationship between managed objects. Following text
-describes the means of retrieving associated objects within a given one.
+An association from CIM perspective is a type of class that contains two or
+more references. Associations represent relationships between two or more
+classes.
+
+Associations are classes which establish a relationship between classes without
+affecting any of the related classes. In other words, the addition of an
+association has no effect on any of the related classes.
+
+Following text describes the means of retrieving associated objects within
+a given one.
.. _associators_instances:
diff --git a/doc/src/shell/classes.rst b/doc/src/shell/classes.rst
index 3826e1e..8acaef0 100644
--- a/doc/src/shell/classes.rst
+++ b/doc/src/shell/classes.rst
@@ -1,9 +1,9 @@
Classes
=======
-Each class in LMIShell represents a class provided by a CIMOM. You can get a
-list of its properties, methods, instances, instance names and ValueMap
-properties. It is also possible to print a documentation string, create a new
-instance or new instance name.
+Each :py:class:`.LMIClass` in LMIShell represents a class implemented by a
+certain provider. You can get a list of its properties, methods, instances,
+instance names and ValueMap properties. It is also possible to print a
+documentation string, create a new instance or new instance name.
Getting a class object
----------------------
@@ -19,16 +19,16 @@ To get a class which is provided by a broker, you can do following:
Fetching a class
----------------
Objects of :py:class:`.LMIClass` use lazy fetching method, because some methods
-do not need the :py:class:`lmiwbem.CIMClass` object.
+do not need the :py:class:`wbem.CIMClass` object.
-To manually fetch the :py:class:`lmiwbem.CIMClass` object, call following:
+To manually fetch the :py:class:`wbem.CIMClass` object, call following:
.. code-block:: python
cls.fetch()
-The methods, which need the :py:class:`lmiwbem.CIMClass` object to be fetched
+The methods, which need the :py:class:`wbem.CIMClass` object to be fetched
from CIMOM, do this action automatically, without the need of calling
:py:meth:`.LMIClass.fetch` method by hand.
@@ -87,8 +87,8 @@ To get :py:class:`.LMIInstance` object, execute the following example:
Get Instance Names
^^^^^^^^^^^^^^^^^^
-The :py:class:`lmiwbem.CIMInstanceName` objects clearly identify
-:py:class:`lmiwbem.CIMInstance` objects. LMIShell can retrieve
+The :py:class:`wbem.CIMInstanceName` objects clearly identify
+:py:class:`wbem.CIMInstance` objects. LMIShell can retrieve
:py:class:`.LMIInstanceName` objects, by calling following:
.. code-block:: python
@@ -116,7 +116,7 @@ following example:
New Instance Name
^^^^^^^^^^^^^^^^^
-LMIShell is able to create a new wrapped :py:class:`lmiwbem.CIMInstanceName`, if
+LMIShell is able to create a new wrapped :py:class:`wbem.CIMInstanceName`, if
you know all the primary keys of a remote object. This instance name object can
be then used to retrieve the whole instance object.
@@ -242,7 +242,7 @@ class (refer to :ref:`startup_connection`). See next example:
Wrapped Object
^^^^^^^^^^^^^^
-This property returns a wrapped :py:mod:`lmiwbem` object. See the example:
+This property returns a wrapped :py:mod:`wbem` object. See the example:
.. code-block:: python
diff --git a/doc/src/shell/indications.rst b/doc/src/shell/indications.rst
index a69de2e..b3f0af3 100644
--- a/doc/src/shell/indications.rst
+++ b/doc/src/shell/indications.rst
@@ -1,16 +1,28 @@
Indications
===========
-Indication is a reaction to some specific event that occurs in response to a
-particular change in data. LMIShell can perform an indication subscription, by
-which we can receive such event responses.
+From CIM point of view, an *indication* is the representation of the occurrence
+of an event. Indications are classes so they can have properties and methods.
+Instances of an indication are transient and can not be obtained by using CIM
+Operations, such as ``GetInstance()`` or ``EnumerateInstances()``. Indications
+can only be received by subscribing to them.
+An indication subscription is performed by the creation of an
+*CIM_IndicationSubscription* association instance that references an
+*CIM_IndicationFilter* (a filter) instance, and an *CIM_IndicationHandler*
+(a handler) instance. The filter contains the query that selects an *Indication*
+class or classes. The size and complexity of the result delivered to the
+destination is defined by the query.
+
+LMIShell can perform an indication subscription, by which we can receive such
+event responses. The shell also provides a mechanism for the indication
+reception.
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
+When working with indications, the first step is to set up an indication handler. This is
a routine that will
+be triggered when the CIMOM sends us an indication for which we have
+subscribed (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
@@ -26,18 +38,18 @@ indication:
... """
... Indication handler.
...
- ... :param CIMInstance indication: exported lmiwbem.CIMInstance
+ ... :param wbem.CIMInstance indication: exported wbem.CIMInstance
... :param arg1: ...
... :param arg2: ...
... ...
... """
... do_something_with(indication)
- > listener = LMIIndicationListener()
+ > listener = LMIIndicationListener(listening_address, listening_port, certfile,
keyfile, trust_store)
unique_name =
listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2, **kwargs)
- > listener.start(listening_port, cert_file, key_file)
+ > listener.start()
-The first argument of the handler is a :py:class:`lmiwbem.CIMInstance` object;
+The first argument of the handler is a :py:class:`wbem.CIMInstance` object;
the exported 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
@@ -50,40 +62,37 @@ substituted name is returned as the result of the
:py:meth:`.LMIIndicationListener.add_handler` method so it can be used later.
When all necessary handlers are registered, the listener can be started by
-calling :py:meth:`.LMIIndicationListener.start`, which takes up to three
-arguments, one mandatory (port) and two optional when using SSL (cert_file and
-key_file; paths to X509 certificate and private key in PEM format).
+calling :py:meth:`.LMIIndicationListener.start`.
+
+When a secure connection is desired, :py:class:`.LMIIndicationListener` can be
+constructed with `keyfile`, `certfile` and `trust_store` (paths to X509
+certificate, private key in PEM format and trust store).
Subscribing to an indication
----------------------------
-The LMIShell is capable of creating an indication subscription with the filter and
-handler objects in one single step. This example is based upon `sblim-cmpi-base`
-provider.
+Now, when the indication listener is up and running, the indication
+subscription can be done. The LMIShell is capable of creating an indication
+subscription with the filter and handler objects in one single step.
-How to subscribe to an indication, please, follow the next example:
+Example of indication subscription with 3 mandatory arguments:
.. code-block:: python
- > c = connect("host", "privileged_user",
"password")
- > c.subscribe_indication(
- ... QueryLanguage="WQL",
- ... Query='SELECT * FROM CIM_InstModification',
- ... Name=unique_name,
- ... CreationNamespace="root/interop",
- ... SubscriptionCreationClassName="CIM_IndicationSubscription",
- ... FilterCreationClassName="CIM_IndicationFilter",
- ... FilterSystemCreationClassName="CIM_ComputerSystem",
- ... FilterSourceNamespace="root/cimv2",
- ... HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
- ... HandlerSystemCreationClassName="CIM_ComputerSystem",
- ... # destination computer, where the indications will be delivered
- ... Destination="http://192.168.122.1:%d" % listening_port
- ... )
- LMIReturnValue(rval=True, rparams={}, errorstr="")
-
+ > c = connect("host",
"privileged_user", "password")
+ > c.subscribe_indication(
+ ... Name=unique_name,
+ ... Query='SELECT * FROM CIM_InstModification',
+ ... Destination="http://192.168.122.1:%d" % listening_port
+ ... )
+ LMIReturnValue(rval=True, rparams={}, errorstr="")
+ >
+
+**NOTE:** Make sure, that you an account which has write privileges in the
+*root/interop* namespace.
-The previous code can be simplified by omitting some optional parameters:
+The indication subscription can created with an extensive list of arguments,
+where optional arguments can be specified:
* *QueryLanguage*: *DMTF:CQL*
* *CreationNamespace*: *root/interop*
@@ -94,24 +103,29 @@ The previous code can be simplified by omitting some optional
parameters:
* *HandlerCreationClassName*: *CIM_IndicationHandlerCIMXML*
* *HandlerSystemCreationClassName*: *CIM_ComputerSystem*
-Simplified subscription:
-
.. code-block:: python
c = connect("host", "privileged_user",
"password")
c.subscribe_indication(
- ... Name=unique_name,
+ ... QueryLanguage="WQL",
... Query='SELECT * FROM CIM_InstModification',
- ... Destination="http://192.168.122.1:5988"
+ ... Name=unique_name,
+ ... CreationNamespace="root/interop",
+ ... SubscriptionCreationClassName="CIM_IndicationSubscription",
+ ... FilterCreationClassName="CIM_IndicationFilter",
+ ... FilterSystemCreationClassName="CIM_ComputerSystem",
+ ... FilterSourceNamespace="root/cimv2",
+ ... HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
+ ... HandlerSystemCreationClassName="CIM_ComputerSystem",
+ ... Destination="http://192.168.122.1:%d" % listening_port
... )
LMIReturnValue(rval=True, rparams={}, errorstr="")
-**NOTE:** Make sure, that you are logged-in with an account, which has write
-privileges in the *root/interop* namespace.
In this state, we have a indication subscription created.
+
Auto-delete subscriptions
^^^^^^^^^^^^^^^^^^^^^^^^^
By default all subscriptions created by LMIShell will be **auto-deleted**, when
@@ -119,6 +133,7 @@ the shell quits. To change this behavior, you can pass
:samp:`Permanent=True`
keyword parameter to :py:meth:`.LMIConnection.subscribe_indication` call, which
will prevent LMIShell from deleting the subscription.
+
Listing subscribed indications
------------------------------
To list all the subscribed indications, run following code:
@@ -130,6 +145,7 @@ To list all the subscribed indications, run following code:
> subscribed_ind_lst = c.subscribed_indications()
+
Unsubscribing from an indication
---------------------------------
By default, the subscriptions created by the shell are auto-deleted, when the
diff --git a/doc/src/shell/instance_names.rst b/doc/src/shell/instance_names.rst
index 4e9c68b..f1cc50e 100644
--- a/doc/src/shell/instance_names.rst
+++ b/doc/src/shell/instance_names.rst
@@ -104,7 +104,7 @@ instance name (refer to :ref:`startup_connection`). See next example:
Wrapped Object
^^^^^^^^^^^^^^
-This property returns a wrapped :py:mod:`lmiwbem` object. See the example:
+This property returns a wrapped :py:mod:`wbem` object. See the example:
.. code-block:: python
diff --git a/doc/src/shell/instances.rst b/doc/src/shell/instances.rst
index 7bc1599..c66f387 100644
--- a/doc/src/shell/instances.rst
+++ b/doc/src/shell/instances.rst
@@ -1,8 +1,9 @@
Instances
=========
-Each instance in LMIShell represents a CIM instance provided by a CIMOM.
+Each :py:class:`.LMIInstance` in LMIShell represents a CIM instance provided by
+a certain provider.
-Operations, that can be done within a :py:class:`.LMIInstance`:
+Operations that can be performed within a :py:class:`.LMIInstance`:
* get and set properties
* list/print/execute its methods
@@ -61,10 +62,16 @@ Synchronous methods
^^^^^^^^^^^^^^^^^^^
LMIShell can perform synchronous method call, which means, that the LMIShell is
able to synchronously wait for a Job object to change its state to `Finished`
-state and then return the job's return parameters. LMIShell can perform the
-synchronous method call, if the given method returns a object of following
-classes:
+state and then return the job's return parameters.
+Most of the implemented methods in OpenLMI providers are *asynchronous*
+methods, which means that user can execute such method and do other desired
+actions while waiting for the result(s).
+
+LMIShell can perform the synchronous method call, if the given method returns a
+object of following classes:
+
+* :py:class:`LMI_SELinuxJob`
* :py:class:`LMI_StorageJob`
* :py:class:`LMI_SoftwareInstallationJob`
* :py:class:`LMI_SoftwareVerificationJob`
@@ -317,7 +324,7 @@ instance (refer to :ref:`startup_connection`). See next example:
Wrapped Object
^^^^^^^^^^^^^^
-This property returns a wrapped :py:mod:`lmiwbem` object. See the example:
+This property returns a wrapped :py:mod:`wbem` object. See the example:
.. code-block:: python