Merge "Added Model base class + related doc"

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
@@ -58,8 +58,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()