CIM API concepts
================

Storage API is based on several design patterns, which are common in CIM and
SMI-S.

Separation of state and configuration
-------------------------------------
If *foo* is configurable, CIM uses two classes to describe it:


- ``CIM_Foo``: *state* of foo.

- ``CIM_FooSetting``: *configuration* of foo.

That means, each *foo* on managed system is represented by one ``CIM_Foo``
instance and one ``CIM_FooSetting`` instance. They are connected together using
``CIM_FooElementSettingData`` association instance.

If there is no ``CIM_FooSetting instance`` for a ``CIM_Foo``, it indicates that
the *foo* is not configurable.

For example, a local filesystem is represented by:

- one instance of ``CIM_LocalFileSystem``, which contains *state* of the
  filesystem – nr. of inodes, nr. of free inodes, total space on the
  filesystem, free space, etc.

- one instance of ``CIM_LocalFileSystemSetting``, which contains
  *configuration* of the filesystem – inode size, journal size, ...

Sometimes, state and configuration overlap. In our filesystem example,
``BlockSize`` is property of both ``CIM_LocalFileSystem`` and
``CIM_LocalFileSystemSetting``. Logically, the ``BlockSize`` should be only in
``CIM_LocalFileSystemSetting``. But if a filesystem was not configurable, there
would be no ``CIM_LocalFileSystemSetting`` for it and therefore any management
application would not have access to its ``BlockSize``, which is important
feature of the filesystem.

.. figure:: pic/intro-setting.svg

Configuration service
---------------------
In CIM world, managed elements cannot be configured directly by editing the
associated ``CIM_FooSetting`` with the configuration of *foo*. Instead, there
is ``CIM_FooConfigurationService`` singleton, which has method to create,
modify and sometimes also delete *foos*.


Change of configuration
-----------------------
If an application want to change configuration of a *foo*, it must create new
auxiliary ``CIM_FooSetting`` instance with requested new configuration and
associate this new ``CIM_FooSetting`` with the ``CIM_Foo`` it wants to
configure. The application does not need to completely fill the auxiliary
``CIM_FooSetting``, in most cases it is enough to edit only the properties that
it wants to change, the rest of properties can be ``NULL``.

For example, to change ``CIM_LocalFileSystemSetting`` of a
``CIM_LocalFileSystem``, the application must create new
``CIM_LocalFileSystemSetting``, fill its properties it wants to change and then
call ``CIM_FileSystemConfigurationService.SNIA_ModifyFileSystem()`` method.

The auxiliary ``CIM_LocalFileSystemSetting`` created by the application can be
reused by the application to change configuration of different
``CIM_LocalFileSystem`` instances.


Creation of instances
---------------------
The ``CIM_FooSetting`` is also used to create new objects. If an application
wants to create new *foo*, it creates new auxiliary ``CIM_FooSetting``, which
describes configuration of the *foo* to create. The application can then call
specific API method to create the *foo* and new ``CIM_Foo`` is created, with
its own associated ``CIM_FooSetting``. The associated ``CIM_FooSetting`` is
basically a copy of the auxiliary CIM_FooSetting created by the application.
Therefore the application can reuse one auxiliary ``CIM_FooSetting`` instance
to create or modify multiple *foos*.

For example, to create a filesystem on a block device, the application must
create ``CIM_LocalFileSystemSetting``, set its properties as it wants and call
``CIM_FileSystemConfigurationService.SNIA_CreateFileSystem``.


Capabilities
------------
The DMTF and SMI-S describe various methods and configuration properties of
various classes. Implementations of the standards can implement only some of
these methods and properties. Therefore ``CIM_FooConfigurationCapabilities``
describes what methods and kinds of *foo* our implementation of
``CIM_FooConfigurationService`` supports.

For example, if our ``CIM_FileSystemConfigurationService`` supports xfs and ext3
filesystems and only ``SNIA_CreateFileSystem`` and ``SNIA_ModifyFileSystem``
method calls, it will be reflected in its associated
``CIM_FileSystemConfigurationCapabilities``.

In addition, if there are several different kind of *foos* supported by the
implementation, each such kind can have its own ``CIM_FooCapabilities``
instance to describe all available configuration options and their value ranges.

For example, if our ``CIM_FileSystemConfigurationService`` is able to create xfs
and ext3 filesystems, there are two ``CIM_LocalFileSystemCapabilities``
instances, one for xfs and the second for ext3. The xfs-related instance
describes valid inode sizes for xfs, while the ext3-related instance describes
valid inode sizes for ext3. Since we can subclass
``CIM_LocalFileSystemCapabilities``, the xfs-related instance can have
additional xfs-specific properties and so can have also the ext3-related
instance.

The supported properties and their ranges can be either defined directly in the
``CIM_FooCapabilities`` (which is the most common case) or using
``CIM_FooSetting`` attached to ``CIM_FooCapabilities`` using
``CIM_SettingsDefineCapabilities`` association. The associated
``CIM_FooSetting`` can then define minimum, maximum or default values of the
configuration properties. Consult DMTF description of
``CIM_SettingsDefineCapabilities`` association in this case.

This is the case of filesystem configuration, the capabilities of xfs and ext3
filesystem is defined using ``CIM_LocalFileSystemSetting``.

.. figure:: pic/intro-service.svg

    Example ``CIM_FileSystemConfigurationService`` with capabilities and
    settings, which define the capabilities.

There are slight variations on this concept across DMTF and SMI-S profiles as
the standards evolved, sometimes are ``CIM_FooConfigurationCapabilities`` and
``CIM_FooCapabilities`` merged into one class, sometimes the capabilities are
associated directly to managed elements, sometimes the capabilities as defined
using setting instances etc. Still, the concept is the same - *capabilities*
define what configuration options are supported by the implementation and its
valid values or value ranges. Different implementations will have different
capabilities. *Setting* instances then describe specific configuration of one
managed element.

Predefined configurations
-------------------------
To simplify management applications, the implementation can provide several
``CIM_FooSetting`` instances for the most typical *foo* configurations. These
instances are associated to ``CIM_FooCapabilities``. Application then does not
need to manually create auxiliary ``CIM_FooSetting`` instance and fill its
properties, it can directly use the preconfigured ones.

For example, an implementation can provide one typical
``CIM_LocalFileSystemSetting`` instance for generic xfs filesystem and one
``CIM_LocalFileSystemSetting`` instance for xfs filesystem tuned for Gluster,
which needs larger inode size for better performance.

