configurationengine/doc/api/plugin.rst
changeset 3 e7e0ae78773e
parent 0 2e8eeb919028
equal deleted inserted replaced
2:87cfa131b535 3:e7e0ae78773e
     1 Plugin API
     1 .. _plugin-api:
     2 ===============
       
     3 
     2 
     4 .. module:: cone.public.plugin
     3 Extending ConE with plugin API
     5    :platform: Unix, Windows
     4 ==============================
     6    :synopsis: Configuration interface.
       
     7 .. moduleauthor:: Teemu Rytkonen <teemu.rytkonen@nokia.com>
       
     8 
     5 
     9 The Plugin api is intended for extending the ConE functionality with plugins that can be for example 
     6 The Plugin api is intended for extending the ConE functionality with plugins.
    10 implementation or relation plugins. See :ref:`plugin-howto`
     7 Currently there are two ways to extend the functionality:
    11 
     8 
    12 .. image:: cone_plugin_api.png
     9 1. Adding support for new implementation languages
       
    10 2. Extending ConfML or ImplML validation
    13 
    11 
    14 Classes
    12 Usually a plug-in that provides a new implementation language also provides
    15 -------
    13 validation for it.
    16 
    14 
    17 .. class:: ImplBase(ref, configuration)
    15 Developing a ConE plugin
       
    16 ------------------------
       
    17 * See `Cone API epydoc <../epydoc/index.html>`_ for reference guide.
    18 
    18 
    19 The ImplBase class is intended for deriving any implementation plugin in ConE. A single ImplBase 
    19 .. toctree::
    20 instance is created by ConE for each implml file inside a given Configuration. 
    20     :maxdepth: 3
    21 
    21 
    22 See :ref:`plugin-howto`
    22     ../plugins/dev-plugin/plugin-interface
    23  
    23     ../plugins/dev-plugin/index
    24     .. method:: list_output_files()
    24     ../plugins/dev-plugin/validation-plugin-index
    25   
       
    26     The list_output_files should return a list of output files with path, with the current configuration.
       
    27     This mechanism should enable listing of all output files before without actually generating them.
       
    28 
       
    29     .. method:: generate()
       
    30   
       
    31     The plugin instance is supposed to generate its output with the call of generate(). 
       
    32 
       
    33     .. method:: has_ref(refs)
       
    34   
       
    35     This method receives a list as an attribute and is supposed to return True|False. True if this 
       
    36     particular plugin instance has a reference to a Feature inside the given refs list. Otherwise False. 
       
    37 
       
    38 .. class:: ImplSet
       
    39 
       
    40 The ImplSet is a sets.Set object for a set of ImplBase instances. The main purpose of ImplSet 
       
    41 is to allow operations to a set of ImplBase instances, such as generate, filter, etc. 
       
    42 
       
    43 .. class:: ImplFactory
       
    44 
       
    45 ImplFactory is a constructor class for the plugin instances.
       
    46 
       
    47     .. method:: get_impl_by_ext(cls, ext)
       
    48   
       
    49     Get the class name by file extension. 
       
    50     
       
    51 
       
    52     .. method:: get_impl_by_filename(cls, ref, configuration)
       
    53 
       
    54     Get the class name by filename.
       
    55 
       
    56 .. class:: Relation(left, right)
       
    57 
       
    58     .. method:: execute()
       
    59   
       
    60     Executes the rule initiated for this Relation.
       
    61 
       
    62 
       
    63 	Relation is a base class for all Relation implementations. The purpose of a Relation instance is to offer a verb or an 
       
    64 	action that can be used in a rule. A rule in this context means a textual relation between two or more :class:`Feature`'s.
       
    65 	For example a Depends class could be used to define dependencies between two :class:`Feature`
       
    66   
       
    67 	::
       
    68 	
       
    69 		example rule
       
    70 	  	A depends B
       
    71 	
       
    72 	Where A and B are :class:`Feature` references.
       
    73 
       
    74 .. class:: RelationContainer
       
    75 	
       
    76 	RelationContainer is a container object that derives Relation interface, but is meant for storing a set of :class:`Relation`
       
    77 	objects. It can be used to execute a set of rules read to the container.
       
    78 
       
    79 .. class:: RelationFactory
       
    80 
       
    81     .. method:: get_by_name(name)
       
    82   
       
    83     returns a :class:`Relation` if the class that matches the name is found. 
       
    84 
       
    85 	The RelationFactory is intended to be used when the rules are read from some persistent storage. When a rule is found from 
       
    86 	:class:`Configuration` ConE will try to create a :class:`Relation` instance of the rule, by trying to get class 
       
    87 	by :meth:`RelationFactory.get_by_name` and create an instance of that class.
       
    88 	
       
    89 
       
    90 
       
    91