|
0
|
1 |
.. _plugin-howto-plugin-interface:
|
|
|
2 |
|
|
|
3 |
Plug-in interface
|
|
|
4 |
=================
|
|
|
5 |
|
|
3
|
6 |
Implementation languages
|
|
|
7 |
------------------------
|
|
|
8 |
|
|
|
9 |
A ConE plug-in that adds support for an implementation language has two points
|
|
|
10 |
for interfacing with ConE:
|
|
0
|
11 |
|
|
|
12 |
#. Reader classes that derive from ``cone.public.plugin.ReaderBase`` . These classes
|
|
|
13 |
define supported Implementation Markup Languages (i.e. supported XML namespaces)
|
|
|
14 |
and other attributes related to them like file extensions. As the name suggests, they are
|
|
|
15 |
also responsible for reading implementation instances from XML data.
|
|
|
16 |
#. Implementation classes that derive from ``cone.public.plugin.ImplBase``. These classes
|
|
|
17 |
supply the actual run-time functionality of the plug-ins.
|
|
|
18 |
|
|
|
19 |
The following UML diagram shows the most important classes and their interdependencies:
|
|
|
20 |
|
|
|
21 |
.. image:: plugin_classes.jpg
|
|
|
22 |
|
|
3
|
23 |
For more information on the classes see the
|
|
|
24 |
`ConE API epydoc <../../epydoc/cone.public.plugin-module.html>`_.
|
|
|
25 |
|
|
0
|
26 |
ConE generation can be seen to consist of two phases, implementation parsing
|
|
|
27 |
and output generation:
|
|
|
28 |
|
|
|
29 |
Parsing phase:
|
|
|
30 |
|
|
|
31 |
- Implementation file list is filtered based on a user-given file name pattern
|
|
|
32 |
and supported file extensions
|
|
|
33 |
- All remaining files are parsed into ``ElementTree`` instances
|
|
|
34 |
- The ``ElementTree`` instance is scanned for supported ImplML namespaces and
|
|
|
35 |
implementation instances are created using the correct reader classes
|
|
|
36 |
(the ``read_impl()`` method)
|
|
|
37 |
- All implementations are collected into an ``ImplSet`` instance
|
|
|
38 |
|
|
|
39 |
Generation phase:
|
|
|
40 |
|
|
|
41 |
- Implementation instances are further filtered using tags and ConfML references
|
|
|
42 |
(the ``has_tag()`` and ``has_ref()`` methods)
|
|
|
43 |
- Implementations instances are divided into separate sets based on their invocation
|
|
|
44 |
phases
|
|
|
45 |
- Output is generated using each implementation set. For each implementation set:
|
|
|
46 |
|
|
|
47 |
- The ``generation_context`` variable of each implementation instance is set
|
|
3
|
48 |
(this context contains generation-scope information implementation instances may use)
|
|
0
|
49 |
- The ``generate()`` method of each instance is called
|
|
|
50 |
- The ``post_generate()`` method of each instance is called
|
|
|
51 |
|
|
|
52 |
From a plug-in's point of view, the sequence of method calls goes as follows:
|
|
|
53 |
|
|
|
54 |
.. image:: plugin_lifecycle.jpg
|
|
|
55 |
|
|
|
56 |
Explanations of the steps in the diagram:
|
|
|
57 |
|
|
|
58 |
====== ========================================================================
|
|
|
59 |
Step Explanation
|
|
|
60 |
====== ========================================================================
|
|
|
61 |
1 ``read_impl()`` is called to create an implementation instance based on
|
|
|
62 |
XML data.
|
|
|
63 |
2 ``read_impl()`` creates the instance.
|
|
|
64 |
3-6 Filtering based on ConfML references and implementation tags is done.
|
|
|
65 |
The implementation instance returns True in all cases, so it is included
|
|
|
66 |
in the actual generation.
|
|
|
67 |
7-8 The instance is asked for its invocation phase (here it returns "normal")
|
|
|
68 |
9 The implementation instance's ``generation_context`` variable is set, so
|
|
|
69 |
then it can be used in the actual generation.
|
|
|
70 |
10-11 Output generation methods are called
|
|
|
71 |
====== ========================================================================
|
|
|
72 |
|
|
3
|
73 |
|
|
|
74 |
.. _plugin-howto-plugin-interface-validation:
|
|
0
|
75 |
|
|
3
|
76 |
Validation
|
|
|
77 |
----------
|
|
0
|
78 |
|
|
3
|
79 |
.. note::
|
|
|
80 |
|
|
|
81 |
See also :ref:`validation-overview`
|
|
0
|
82 |
|
|
3
|
83 |
The ConE plug-in interface allows for the extension of ConfML and ImplML validation.
|
|
|
84 |
In the same way as support for new implementation languages can be provided
|
|
|
85 |
by exposing implementation reader classes via egg entry points, validation
|
|
|
86 |
can be extended by exposing validator classes.
|
|
|
87 |
|
|
|
88 |
Validation happens roughly in the following manner:
|
|
0
|
89 |
|
|
3
|
90 |
1. A list of *validator classes* is obtained through some means. In practice
|
|
|
91 |
this usually means finding all validator classes, and then filtering them
|
|
|
92 |
down to those that produce the problems that we are interested in.
|
|
|
93 |
2. A *validation context* is created. This contains everything associated with
|
|
|
94 |
the validation, and here all found problems are reported. All validators
|
|
|
95 |
have access to it.
|
|
|
96 |
3. For each entity (configuration or implementation instance) that is being
|
|
|
97 |
validated, an instance of each validator class is created and invoked.
|
|
0
|
98 |
|
|
3
|
99 |
This process is nearly the same for ConfML and ImplML validation, only some
|
|
|
100 |
details about the validation context and the entities being validated are
|
|
|
101 |
different, as well as the fact ConfML validation on the entire configuration,
|
|
|
102 |
whereas ImplML validation happens on individual implementation instances, with
|
|
|
103 |
a few exceptions.
|
|
|
104 |
|
|
|
105 |
The following diagram illustrates ImplML validation:
|
|
|
106 |
|
|
|
107 |
.. image:: impl-validation-classes.jpg
|
|
0
|
108 |
|
|
3
|
109 |
The following diagram illustrates ConfML validation:
|
|
|
110 |
|
|
|
111 |
.. image:: confml-validation-classes.jpg
|
|
|
112 |
|
|
|
113 |
For more information on the classes involved in validate see the
|
|
|
114 |
ConE API epydoc for `cone.validation.implmlvalidation <../../epydoc/cone.validation.implmlvalidation-module.html>`_
|
|
|
115 |
and `cone.validation.confmlvalidation <../../epydoc/cone.validation.confmlvalidation-module.html>`_.
|
|
|
116 |
Also the built-in validators in the package `cone.validation.builtinvalidators <../../epydoc/cone.validation.builtinvalidators-module.html>`_
|
|
|
117 |
can serve as examples. |