Added Model base class + related doc

In this changeset I added a Model abtract base class for models
and updated the plugin docs to reference it. I also added the
CDM and CDMC acronyms to the glossary.

Change-Id: Ie7d76a9f84d545715fa6e5bf350b9d2321bab9e1

doc/source/dev/plugin/cdmc-plugin.rst

@@ -22,7 +22,7 @@ cluster data model collectors within Watcher.
 Creating a new plugin
 =====================
 
-In order to create a new model, you have to:
+In order to create a new cluster data model collector, you have to:
 
 - Extend the :py:class:`~.base.BaseClusterDataModelCollector` class.
 - Implement its :py:meth:`~.BaseClusterDataModelCollector.execute` abstract
@@ -65,6 +65,49 @@ This implementation is the most basic one. So in order to get a better
 understanding on how to implement a more advanced cluster data model collector,
 have a look at the :py:class:`~.NovaClusterDataModelCollector` class.
 
+Define a custom model
+=====================
+
+As you may have noticed in the above example, we are reusing an existing model
+provided by Watcher. However, this model can be easily customized by
+implementing a new class that would implement the :py:class:`~.Model` abstract
+base class. Here below is simple example on how to proceed in implementing a
+custom Model:
+
+.. code-block:: python
+
+    # Filepath = <PROJECT_DIR>/thirdparty/dummy.py
+    # Import path = thirdparty.dummy
+
+    from watcher.decision_engine.model import base as modelbase
+    from watcher.decision_engine.model.collector import base
+
+
+    class MyModel(modelbase.Model):
+
+        def to_string(self):
+            return 'MyModel'
+
+
+    class DummyClusterDataModelCollector(base.BaseClusterDataModelCollector):
+
+        def execute(self):
+            model = MyModel()
+            # Do something here...
+            return model
+
+        @property
+        def notification_endpoints(self):
+            return []
+
+Here below is the abstract ``Model`` class that every single cluster data model
+should implement:
+
+.. autoclass:: watcher.decision_engine.model.base.Model
+    :members:
+    :special-members: __init__
+    :noindex:
+
 Define configuration parameters
 ===============================
 

doc/source/glossary.rst

@@ -96,8 +96,8 @@ The :ref:`Cluster <cluster_definition>` may be divided in one or several
 
 .. _cluster_data_model_definition:
 
-Cluster Data Model
-==================
+Cluster Data Model (CDM)
+========================
 
 .. watcher-term:: watcher.decision_engine.model.collector.base
 
@@ -164,7 +164,8 @@ Goal
 Host Aggregate
 ==============
 
-Please, read `the official OpenStack definition of a Host Aggregate <http://docs.openstack.org/developer/nova/aggregates.html>`_.
+Please, read `the official OpenStack definition of a Host Aggregate
+<http://docs.openstack.org/developer/nova/aggregates.html>`_.
 
 .. _instance_definition:
 

watcher/decision_engine/model/base.py

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+# Copyright (c) 2016 b<>com
+#
+# Authors: Vincent FRANCOISE <Vincent.FRANCOISE@b-com.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This component is in charge of executing the
+:ref:`Action Plan <action_plan_definition>` built by the
+:ref:`Watcher Decision Engine <watcher_decision_engine_definition>`.
+
+See: :doc:`../architecture` for more details on this component.
+"""
+
+import abc
+import six
+
+
+@six.add_metaclass(abc.ABCMeta)
+class Model(object):
+
+    @abc.abstractmethod
+    def to_string(self):
+        raise NotImplementedError()

watcher/decision_engine/model/collector/base.py

@@ -19,8 +19,8 @@
 #
 
 """
-A :ref:`Cluster Data Model <cluster_data_model_definition>` is a logical
-representation of the current state and topology of the :ref:`Cluster
+A :ref:`Cluster Data Model <cluster_data_model_definition>` (or CDM) is a
+logical representation of the current state and topology of the :ref:`Cluster
 <cluster_definition>` :ref:`Managed resources <managed_resource_definition>`.
 
 It is represented as a set of :ref:`Managed resources
@@ -59,8 +59,11 @@ to know:
 In the Watcher project, we aim at providing a some generic and basic
 :ref:`Cluster Data Model <cluster_data_model_definition>` for each :ref:`Goal
 <goal_definition>`, usable in the associated :ref:`Strategies
-<strategy_definition>` through a plugin-based mechanism that are directly
-accessible from the strategies classes in order to:
+<strategy_definition>` through a plugin-based mechanism which are called
+cluster data model collectors (or CDMCs). These CDMCs are responsible for
+loading and keeping up-to-date their associated CDM by listening to events and
+also periodically rebuilding themselves from the ground up. They are also
+directly accessible from the strategies classes. These CDMs are used to:
 
 - simplify the development of a new :ref:`Strategy <strategy_definition>` for a
   given :ref:`Goal <goal_definition>` when there already are some existing

watcher/decision_engine/model/model_root.py

@@ -22,11 +22,13 @@ import six
 from watcher._i18n import _
 from watcher.common import exception
 from watcher.common import utils
+from watcher.decision_engine.model import base
 from watcher.decision_engine.model import element
 from watcher.decision_engine.model import mapping
 
 
-class ModelRoot(object):
+class ModelRoot(base.Model):
+
     def __init__(self, stale=False):
         self._nodes = utils.Struct()
         self._instances = utils.Struct()