.. _plugin-howto-plugin-interface:
Plug-in interface
=================
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)
and other attributes related to them like file extensions. As the name suggests, they are
also responsible for reading implementation instances from XML data.
#. Implementation classes that derive from ``cone.public.plugin.ImplBase``. These classes
supply the actual run-time functionality of the plug-ins.
The following UML diagram shows the most important classes and their interdependencies:
.. 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:
Parsing phase:
- Implementation file list is filtered based on a user-given file name pattern
and supported file extensions
- All remaining files are parsed into ``ElementTree`` instances
- The ``ElementTree`` instance is scanned for supported ImplML namespaces and
implementation instances are created using the correct reader classes
(the ``read_impl()`` method)
- All implementations are collected into an ``ImplSet`` instance
Generation phase:
- Implementation instances are further filtered using tags and ConfML references
(the ``has_tag()`` and ``has_ref()`` methods)
- Implementations instances are divided into separate sets based on their invocation
phases
- 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 implementation instances may use)
- The ``generate()`` method of each instance is called
- The ``post_generate()`` method of each instance is called
From a plug-in's point of view, the sequence of method calls goes as follows:
.. image:: plugin_lifecycle.jpg
Explanations of the steps in the diagram:
====== ========================================================================
Step Explanation
====== ========================================================================
1 ``read_impl()`` is called to create an implementation instance based on
XML data.
2 ``read_impl()`` creates the instance.
3-6 Filtering based on ConfML references and implementation tags is done.
The implementation instance returns True in all cases, so it is included
in the actual generation.
7-8 The instance is asked for its invocation phase (here it returns "normal")
9 The implementation instance's ``generation_context`` variable is set, so
then it can be used in the actual generation.
10-11 Output generation methods are called
====== ========================================================================
.. _plugin-howto-plugin-interface-validation:
Validation
----------
.. note::
See also :ref:`validation-overview`
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:
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.
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
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.