===========================================================================
Summary of extension support classes in libSBML-5 (2010-01-15)
===========================================================================

This documentation describes the summary of the extension support 
classes which are used by package developers for creating their
package extensions.

  ---------------------------------------------------------------------------
  (NOTE) 

   Most of APIs used by package developers are only following classes.

     1) SBMLExtension
     2) SBasePlugin
     3) SBaseExtensionPoint
     4) SBMLExtensionNamespaces
     5) SBMLExtensionException

   The following classes are also used by package developers but basically 
   only little code is needed when using these classes in each package, 
   because (1) each class below is a template class or a common class which 
   is basically defined/instantiated by only one line, and (2) basically 
   they are internally used in extension support classes and SBase class, 
   and thus package developers don't have to modify or extend the internal 
   implementation.
   
      1) SBasePluginCreator
      2) SBMLExtensionRegistry
      3) SBMLExtensionRegister
      4) SBMLDocumentPlugin

   Package developers must implement not only extension support classes 
   described below but also SBase derived classes of elements defined
   in their packages. For example, Group, ListOfGroups, Member, and 
   ListOfMembers classes are implemented in the groups extension (These classes 
   are implemented in "src/packages/groups/sbml/").
   ----------------------------------------------------------------------------

1) SBMLExtension class

   SBMLExtension class (abstract class) is a core component of each package extension.
   The feature of this class is as follows:

       (1) provides pure virtual functions for getting common attributes
           (e.g. the name (label) of package, default level, version, and 
            package_version, URI of package versions, a string corresponding
            to the typecode of element, and etc.),

       (2) stores SBasePluginCreatorBase derived objects (factory objects)
           for creating corresponding SBasePlugin derived objects (described
           later),

       (3) provides functions for adding/getting the SBasePluginCreatorBase 
           derived objects,

    Package developers must implement a derived class of the SBMLExtension class; 
    and must implement (1) pure virtual functions in the SBMLExtension class and 
    (2) the following static functions in the derived class:

       (1) defines common static functions (e.g. the name (label) of package, 
           default level, version, and package_version, URI of package versions, 
           and etc.),
	
       (2) provides static init() function that registers the package extension to  
           the SBMLExtensionRegistry class.
          (the static init() function is actually implemented in each SBMLExtension
           derived class implemented by package developers.)
	   
    The detailed information (what virtual functions must be overridden, what static
    data member must be implemented and etc.) is described in the header file of the
    class ( "src/extension/SBMLExtension.h" )


2) SBasePlugin class

   In libSBML-5, each SBase derived object contains zero or more SBasePlugin
   derived objects of package extensions. SBasePlugin derived class defines 
   additional attributes and/or top-level elements of its package extension 
   which are directly added to the target element (e.g. <listOfLayouts> element 
   in the layout extension is directly added to the Model element), and 
   provides functions for reading/writing/creating/setting/getting them.
   
   SBasePlugin class defines basic virtual functions for reading/writing/
   checking additional attributes and/or top-level elements which should or 
   must be overridden by subclasses like SBase class and its derived classes.
   
   Package developers must implement a new SBasePlugin derived class for 
   each element (e.g. SBMLDocument, Model, ...) to which additional attributes 
   and/or top-level elements of the package extension are added.

   To implement reading/writing functions for attributes and/or top-level 
   elements (e.g. readAttributes, writeElements) of the SBsaePlugin derived 
   class, package developers should or must override the corresponding virtual 
   functions provided in the SBasePlugin class.
   
   To implement package-specific creating/getting/manipulating functions of the 
   SBasePlugin derived class (e.g. getListOfLayouts(), createLyout(), getLayout(), 
   and etc in the Model element for layout package), package developers must newly 
   implement such functions (as they like) in the derived class.

   SBasePlugin class defines other virtual functions of internal implementations
   (setSBMLDocument(), connectToParent(), and enablePackageInternal() functions).
   These functions should or must be overridden by subclasses in which one or
   more top-level elements are defined.

   For example, the following three SBasePlugin derived classes are implemented in 
   the layout extension:

     1) SBMLDocuementPlugin class (*) for SBMLDocument element 

         - 'required' attribute is added to SBMLDocument object.

	 -------------------------------------------------------------------
         (*) A common SBasePlugin derived class for SBMLDocument class.
             Package developers can use this class as-is if no additional 
             elements/attributes (except for 'required' attribute) is 
             needed for the SBMLDocument class in their packages, otherwise
             package developers must implement a new SBMLDocumentPlugin
             derived class.
	 -------------------------------------------------------------------

     2) LayoutModelPlugin class for Model element 

        - 'listOfLayouts' element is added to Model object.

        - The following virtual functions for reading/writing/checking
          are overridden: (type of arguments and return values are omitted)

            - createObject()    : (read elements)
            - readOtherXML()    : (read elements in annotation of SBML L2)
            - writeElements()   : (write elements)

        - The following virtual functions of internal implementations
          are overridden: (type of arguments and return values are omitted)

            - setSBMLDocument()
            - connectToParent()
            - enablePackageInternal()

        - The following creating/getting/manipulating functions are newly 
          implemented: (type of arguments and return values are omitted)

           - getListOfLayouts() 
           - getLayout ()      
           - addLayout()
           - createLayout()
           - removeLayout()
           - getNumLayouts()

	   
     3) LayoutSpeciesReferencePlugin class for SpeciesReference element

        - 'id' attribute is internally added to SpeciesReference object
           only for SBML L2V1

        - The following virtual functions for reading/writing/checking
          are overridden: (type of arguments and return values are omitted)

          - readOtherXML()
          - writeAttributes()

   In summary, each package extension must define a set of SBaesPlugin
   derived classes. 
   The set of SBasePlugin derived objects are created and registered by 
   the SBMLExtension (described later) derived class of the package.


3) SBaseExtensionPoint class

  SBaseExtensionPoint class consists of a package name and a typecode of
  the SBase subclass, which represents an extension point to which an 
  SBasePlugin object is connected.

  For example, an SBaseExtensionPoint object for an LayoutModelPlugin object
  (a plugin object of the layout extension which is connected to the Model
  element of the SBML core package) can be created as follows:


     SBaseExtensionPoint modelextp("core", SBML_MODEL);


  Similarly, an SBaseExtensionPoint object for some plugin object connected
  to the Layout element of the layout extension can be created as follows:


     SBaseExtensionPoint layoutextp("layout", SBML_LAYOUT_LAYOUT);


  For example, package developers use this class in init() function of each
  SBMLExtension derived class for initializing each extension.


4) SBasePluginCreatorBase and SBasePluginCreator classes

   The SBasePlugin derived objects are internally/dynamically created and added 
   to the target SBML element (e.g. Model element for the LayoutModelPlugin object)
   if the package extension is required when creating an SBML element.
   
      -----------------------------------------------------------------------------
      (example)

         SBMLNamespaces sbmlns(3,1,"layout",1); <--- SBML L3V1 Core with Layout V1
         Model model(&sbmlns);     

       LayoutModelPlugin object (SBML L3V1 Layout V1) is 
       internally/dynamically created and added to the Model object 
       ("model") when the "model" object is constructed in the above
       example code.

           SBMLNamespaces sbmlns(3,1);   <--- SBML L3V1 Core 
           Model model(&sbmlns);    

       Other hand, no SBasePlugin derived objects are created/added
       when no package extensions are specified as the above code.
      -----------------------------------------------------------------------------

   The creation is internally performed by an SBasePluginCreatorBase derived 
   class (a factory class for SBasePlugin derived object) by invoking its 
   "createPlugin()" function.

       --------------------------------------------------------------------
       The corresponding code is internally implemented in the constructors 
       of SBase and SBMLDocument classes that accept SBMLNamespaces object.
       --------------------------------------------------------------------

   Although package developers must implement such derived class for each 
   SBasePlugin derived class, the derived classes can be easily implemented 
   (by only one line) by using the template class "SBasePluginCreator" which 
   is the derived class of the SBasePluginCreatorBase.

       ---------------------------------------------------------------------
       An example code defining the SBasePluginCreator classes can be shown
       in init() functions in "src/packages/layout/LayoutExtension.cpp" and
       "src/packages/groups/GroupExtension.cpp")
       ---------------------------------------------------------------------

5) SBMLExtensionNamespaces class

   SBMLExtensionNamespaces is a template class and derived from SBMLNamespaces class.
   Package developers must define its own SBMLNamespaces derived class from this template
   class by defining a typedef declaration for their templated class as follows:
   
      typedef SBMLExtensionNamespaces<LayoutExtension> LayoutPkgNamespaces   

     (this code is implemented in "src/packages/layout/extension/LayoutExtension.h")

   Also, package developers must implement a template instantiation code for the above 
   typedef definition in the implementation file (i.e. *.cpp file).
   For example, the template instantiation code for LayoutExtension is as follows:
  
        template class LIBSBML_EXTERN SBMLExtensionNamespaces<LayoutExtension>;

     (this code is implemented in "src/packages/layout/extension/LayoutExtension.cpp")

 
   The purpose of this class is as follows:

     1) To add information of package version
     2) To avoid passing an invalid SBMLNamespaces object to the constructors
        of SBase derived classes of package extensions at runtime.

   Each SBase derived class of package extensions should implement a constructor
   that accepts its SBMLNamespaces derived class.


6) SBMLExtensionRegistry class

    SBMLExtensionRegistry class is a common registry class that stores SBMLExtension
    derived objects registered by package extensions (i.e. stores the information of
    list of package extensions and factory objects of each package extension).
    This class provide the following features:

       (1) registering a package extension (performed by each package extension)
           (adding an SBMLExtension derived class of package extension)
	      
       (2) returning an SBMLExtension derived object for callers to get common 
           properties (e.g. the name of package, default level, version, 
           package_version, and URI of package versions) of the target package 
           extension.

       (3) returning an SBasePluginCreatorBase derived object for callers (basically 
           the caller is SBase class) to internally add an SBasePlugin object of the 
           target package extension (basically when creating an SBase object with 
           the package extension)

       (4) enabling/disabling the registered package extensions.

       (5) getting the number of registered package extensions.


    At least, package developers must use this class for implementing init() function 
    in their SBMLExtension derived class for registering their packages to this class
    as follows:


       int result = SBMLExtensionRegistry::getInstance().addExtension(&layoutExtension);


    Only one object of this class can be instantiated (i.e. singleton design pattern).


7) SBMLExtensionRegister class
         
    SBMLExtensionRegister class is a template class for automatically 
    registering each package extension to the SBMLExtensionRegistry class
    before main() routine invoked.
    This class is very simple and easy to be used as follows (by only one line):


       static SBMLExtensionRegister<LayoutExtension> layoutExtensionRegistry;


    How to use this class is described in SBMLExtension.h.

8) SBMLExtensionException class

    SBMLExtensionException class is a exception class which can be thrown 
    when an exception about pacakge extension occurs (e.g. required package
    is not registered).

    Currently, the exception can be thrown in the following functions if
    the required package is not registered:
    
       1) the constructor of SBMLNamespaces 
       2) the constructor of SBMLExtensionNamespaces

===========================================================================

written by Akiya Jouraku