diff -r 87cfa131b535 -r e7e0ae78773e configurationengine/doc/plugins/dev-plugin/plugin-interface.rst --- a/configurationengine/doc/plugins/dev-plugin/plugin-interface.rst Fri Mar 12 08:30:17 2010 +0200 +++ b/configurationengine/doc/plugins/dev-plugin/plugin-interface.rst Tue Aug 10 14:29:28 2010 +0300 @@ -3,7 +3,11 @@ Plug-in interface ================= -A ConE plug-in has two points for interfacing with ConE: +Implementation languages +------------------------ + +A ConE plug-in that adds support for an implementation language has two points +for interfacing with ConE: #. Reader classes that derive from ``cone.public.plugin.ReaderBase`` . These classes define supported Implementation Markup Languages (i.e. supported XML namespaces) @@ -16,6 +20,9 @@ .. image:: plugin_classes.jpg +For more information on the classes see the +`ConE API epydoc <../../epydoc/cone.public.plugin-module.html>`_. + ConE generation can be seen to consist of two phases, implementation parsing and output generation: @@ -38,7 +45,7 @@ - Output is generated using each implementation set. For each implementation set: - The ``generation_context`` variable of each implementation instance is set - (this context contains generation-scope information implementations instances may use) + (this context contains generation-scope information implementation instances may use) - The ``generate()`` method of each instance is called - The ``post_generate()`` method of each instance is called @@ -63,138 +70,48 @@ 10-11 Output generation methods are called ====== ======================================================================== -Plug-in interface class source ------------------------------- + +.. _plugin-howto-plugin-interface-validation: -The following source listings show the most important parts of the ``ImplReader`` -and ``ImplBase`` classes from a plug-in's point of view: - -.. code-block:: python +Validation +---------- - class ReaderBase(object): - """ - Base class for implementation readers. - - Each reader class supports one XML namespace, from which it reads an implementation - instance. - - The method for parsing an implementation (read_impl()) is given an ElementTree - XML element as the root from which to parse the implementation. The plug-in - machinery handles each XML file so that the correct reader class is used to read - the implementations from XML elements based on the namespaces. - """ - - # The XML namespace supported by the implementation reader. - # Should be something like "http://www.xyz.org/xml/1". - # Can also be None, in which case the reader will not be used - # (this can be useful for defining base classes for e.g. readers - # for different versions of an implementation). - NAMESPACE = None - - # Any extra XML namespaces that should be ignored by the - # implementation parsing machinery. This is useful for specifying - # namespaces that are not actual ImplML namespaces, but are used - # inside an implementation (e.g. XInclude) - IGNORED_NAMESPACES = [] - - # Supported implementation file extensions. - # Sub-classes can override this to add new supported file extensions - # if necessary. The file extensions simply control whether implementations - # are attempted to be read from a file or not. - # Note that the extensions are case-insensitive. - FILE_EXTENSIONS = ['implml'] - - @classmethod - def read_impl(cls, resource_ref, configuration, doc_root): - """ - Read an implementation instance from the given element tree. - - @param resource_ref: Reference to the resource in the configuration in - which the given document root resides. - @param configuration: The configuration used. - @param doc_root: The document root from which to parse the implementation. - @return: The read implementation instance, or None. - """ - raise exceptions.NotSupportedException() +.. note:: + + See also :ref:`validation-overview` -.. code-block:: python +The ConE plug-in interface allows for the extension of ConfML and ImplML validation. +In the same way as support for new implementation languages can be provided +by exposing implementation reader classes via egg entry points, validation +can be extended by exposing validator classes. + +Validation happens roughly in the following manner: - class GenerationContext(object): - """ - Context object that can be used for passing generation-scope - data to implementation instances. - """ - - def __init__(self, tags={}): - # The tags used in this generation context - # (i.e. the tags passed from command line) - self.tags = tags - - # A dictionary that implementation instances can use to - # pass any data between each other - self.impl_data_dict = {} - -.. code-block:: python +1. A list of *validator classes* is obtained through some means. In practice + this usually means finding all validator classes, and then filtering them + down to those that produce the problems that we are interested in. +2. A *validation context* is created. This contains everything associated with + the validation, and here all found problems are reported. All validators + have access to it. +3. For each entity (configuration or implementation instance) that is being + validated, an instance of each validator class is created and invoked. - class ImplBase(object): - """ - Base class for any confml implementation. - """ - - # Identifier for the implementation type, used e.g. in .cfg files. - # Should be a string like e.g. 'someml'. - IMPL_TYPE_ID = None - - # Defines the default invocation phase for the implementation. - # The default is used if the phase is not explicitly set in the - # ImplML file or manually overridden by calling set_invocation_phase() - DEFAULT_INVOCATION_PHASE = None - - def __init__(self,ref, configuration): - """ - Create a ImplBase object - @param ref : the ref to the Implml file resource. - @param configuration : the Configuration instance for the - configuration data. - """ - self._settings = None - self.ref = ref - self.index = None - self.configuration = configuration - self.output_root = self.settings.get('output_root','output') - self.output_subdir = self.settings.get('output_subdir','') - self.plugin_output = self.settings.get('plugin_output','') - - self.generation_context = None - self._tags = None - self._invocation_phase = None - self._tempvar_defs = [] +This process is nearly the same for ConfML and ImplML validation, only some +details about the validation context and the entities being validated are +different, as well as the fact ConfML validation on the entire configuration, +whereas ImplML validation happens on individual implementation instances, with +a few exceptions. + +The following diagram illustrates ImplML validation: + +.. image:: impl-validation-classes.jpg - def generate(self): - """ - Generate the given implementation. - @return: - """ - raise exceptions.NotSupportedException() - - def post_generate(self): - """ - Called when all normal generation has been done. - - @attention: This is a temporary method used for implementing cenrep_rfs.txt generation. - """ - pass - - def list_output_files(self): - """ - Return a list of output files as an array. - """ - raise exceptions.NotSupportedException() - - def get_refs(self): - """ - Return a list of all ConfML setting references that affect this - implementation. May also return None if references are not relevant - for the implementation. - """ - return None +The following diagram illustrates ConfML validation: + +.. image:: confml-validation-classes.jpg + +For more information on the classes involved in validate see the +ConE API epydoc for `cone.validation.implmlvalidation <../../epydoc/cone.validation.implmlvalidation-module.html>`_ +and `cone.validation.confmlvalidation <../../epydoc/cone.validation.confmlvalidation-module.html>`_. +Also the built-in validators in the package `cone.validation.builtinvalidators <../../epydoc/cone.validation.builtinvalidators-module.html>`_ +can serve as examples. \ No newline at end of file