================================================================================
Summary of how to implement a package extension (2010-01-16)
================================================================================

This documentation describes the summary of how to implement a package
extension for libSBML-5.
Please see 00README-ExtensionSupportClasses.txt for the summary of 
extension supported classes.

 (Note that since libSBML-5 is currently in development stage
 the API described in this documentation may be changed in the future.)

--------------------------------------------------------------
Table of contents:

  1. Implement an SBMLExtension derived class
  2. Implement SBase derived classes of the package extension 
  3. Implement one or more SBasePlugin derived classes 
  4. Implement a forward declaration file 
  5. Implement a header file which includes all SBML types 
     defined in the extension
  6. Defines a macro value of the package extension 
  7. How to import a source tree of a package extension into 
     the source tree of libSBML-5
--------------------------------------------------------------

--------------------------------------------------------------------------------          
1. Implement an SBMLExtension derived class
--------------------------------------------------------------------------------

  Firstly, an SBMLExtension derived class for your package needs to be implemented 
  based on the following steps.

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

    "src/pacakges/groups/extension/GroupsExtension.{h,cpp}" and
    "src/pacakges/layout/extension/LayoutExtension.{h,cpp}" are
    example files in which SBMLExtension derived classes are implemented.
  ----------------------------------------------------------------------

   --------------------------------------------------------------------------------
   1-1) Define the following static functions in the extended class
   --------------------------------------------------------------------------------
     
      1] A string of package name (label) 

        const std::string& GroupsExtension::getPackageName ()
        {
            static const std::string pkgName = "groups";
            return pkgName;
        }

         --------------------------------------------------
         (NOTE) The function name must be "getPackageName"
         --------------------------------------------------
   
      2] Methods returning an integer of Default SBML level, version, 
	     and package version ()

         unsigned int GroupsExtension::getDefaultLevel()
         {
            return 3;
         }  
         unsigned int GroupsExtension::getDefaultVersion()
         {
            return 1; 
         }
         unsigned int GroupsExtension::getDefaultPackageVersion()
         {
            return 1;
         }  

         --------------------------------------------------
         (NOTE) The method names must be "getDefaultLevel()", 
		        "getDefaultVersion()", and "getDefaultPackageVersion()" 
		        respectively.
         --------------------------------------------------

      3] Methods returning Strings that represent the URI of packages

	     const std::string& GroupsExtension::getXmlnsL3V1V1 ()
         {
	       static const std::string xmlns = 
		       "http://www.sbml.org/sbml/level3/version1/groups/version1";
	       return xmlns;
         }
	     ...
         ...
  
      4] Other URI needed in this package (if any)


   --------------------------------------------------------------------------------
   1-2) Define a typedef of the SBMLNamespaces derived template class of the package
        extension and then instantiates the template.
   --------------------------------------------------------------------------------

      For example, GroupsPkgNamespaces is defined by using the template 
      class in GroupsExtension.h and instantiated in GroupsExtension.cpp 
      as follows:


       (GroupsExtension.h)

          typedef SBMLExtensionNamespaces<GroupsExtension> GroupsPkgNamespaces;

       (GroupsExtension.cpp)

          template class LIBSBML_EXTERN SBMLExtensionNamespaces<GroupsExtension>;


      Similarly, LayoutPkgNamespaces is defined and instantiated as follows:


        (LayoutExtension.h)

          typedef SBMLExtensionNamespaces<LayoutExtension> LayoutPkgNamespaces;

        (LayoutExtension.cpp)

          template class LIBSBML_EXTERN SBMLExtensionNamespaces<LayoutExtension>;


      The SBMLNamespaces derived class can be used as an argument of constructors 
      of SBase derived classes defined in the package extensions.
      For example, a GroupsPkgNamespaces object can be used when creating a group 
      object as follows:


          GroupPkgNamespaces gpns(3,1,1);  // The arguments are SBML Level, 
                                           // SBML Version, and Groups Package Version.

          Group *g = new Group(&gpns);     // Creates a group object of L3V1 Groups V1.

      
       Also, the GroupsPkgNamespaces object can be used when creating an
       SBMLDocument object with the groups package as follows:


           GroupsPkgNamespaces gpns(3,1,1);
           SBMLDocument* doc;

           doc  = new SBMLDocument(&gnps); // Creates an SBMLDocument of L3V1 with 
                                           // Groups V1

   --------------------------------------------------------------------------------
   1-3) Define an enum type for each SBase derived classes defined in the package 
        extension
   --------------------------------------------------------------------------------

      (How to implement SBase derived classes of the package extension
        is described later)

      For example, SBMLLayoutTypeCode_t for the layout extension, SBMLGroupTypeCode_t 
      for group extension are defined in LayoutExtension.h and GroupsExtension.h 
      as follows:
      
        (LayoutExtension.h)

           typedef enum
           {
              SBML_LAYOUT_BOUNDINGBOX           = 100
            , SBML_LAYOUT_COMPARTMENTGLYPH      = 101
            , SBML_LAYOUT_CUBICBEZIER           = 102
            , SBML_LAYOUT_CURVE                 = 103
            , SBML_LAYOUT_DIMENSIONS            = 104
            , SBML_LAYOUT_GRAPHICALOBJECT       = 105
            , SBML_LAYOUT_LAYOUT                = 106   
            , SBML_LAYOUT_LINESEGMENT           = 107   
            , SBML_LAYOUT_POINT                 = 108    
            , SBML_LAYOUT_REACTIONGLYPH         = 109    
            , SBML_LAYOUT_SPECIESGLYPH          = 110    
            , SBML_LAYOUT_SPECIESREFERENCEGLYPH = 111
            , SBML_LAYOUT_TEXTGLYPH             = 112
           } SBMLLayoutTypeCode_t;


        (GroupsExtension.h)

           typedef enum
           {
              SBML_GROUPS_GROUP  = 200
            , SBML_GROUPS_MEMBER = 201
           } SBMLGroupsTypeCode_t;

      
      These enum values are returned by corresponding getTypeCode() functions.
      (e.g. SBML_GROUPS_GROUP is returned in Group::getTypeCode())

      The value of each typecode can be duplicated between those of different 
      packages.
      (In the above SBMLayoutTypeCode_t and SBMLGroupsTypeCode_t types, unique 
       values are assigned to enum values, but this is not mandatory.)

      Thus, to distinguish the typecodes of different packages, not only the return
      value of getTypeCode() but also that of getPackageName() must be checked 
      as follows:


          void example (const SBase *sb)
          {
            cons std::string pkgName = sb->getPackageName();
            if (pkgName == "core")
            {
              switch (sb->getTypeCode())
              {
                case SBML_MODEL:
                   ....
                   break;
                case SBML_REACTION:
                   ....
              }
            } 
            else if (pkgName == "layout")
            {
              switch (sb->getTypeCode())
              {
                case SBML_LAYOUT_LAYOUT:
                   ....
                   break;
                case SBML_LAYOUT_REACTIONGLYPH:
                   ....
              }
            } 
            ...
          } 


   --------------------------------------------------------------------------------
   1-4) Define a list of typecode strings, which is used in getStringFromTypeCode() 
        function
   --------------------------------------------------------------------------------

      For example, a list of typecode strings for groups extension
      is defined as follows (in GroupsExtension.cpp):

           static
           const char* SBML_GROUPS_TYPECODE_STRINGS[] =
           {
               "Group"
             , "Member"
           };


   --------------------------------------------------------------------------------
   1-5) Override the following virtual functions 
   --------------------------------------------------------------------------------
   
      - clone() 

      - getName() const 

      - getURI(unsigned int sbmlLevel, unsigned int sbmlVersion, 
               unsigned int pkgVersion) const 

      - unsigned int getLevel(const std::string &uri) 

      - unsigned int getPackageVersion(const std::string &uri)

      - getSBMLExtensionNamespaces(const std::string&)

      - getStringFromTypeCode(int typecode) const

     ----------------------------------------------------------------------
      (NOTE) Constructor, Copy Constructor, destructor must be overridden
             if additional data members are defined.
      ----------------------------------------------------------------------
 
   --------------------------------------------------------------------------------
   1-6) Define a static init() function
   --------------------------------------------------------------------------------

      init() is a function that creates an instance of the SBMLExtension
      derived class and registers the object to the SBMLExtensionRegistry
      class.
      init() function is automatically invoked before main() routine.

      For example, the static init() function of GroupsExtension is implemented
      in GroupsExtension.cpp as follows:


           void 
           GroupsExtension::init()
           {
             //----------------------------------------------------------------------
             //
             // 1. Check if the groups package has already been registered.
             //
             //----------------------------------------------------------------------
           
             if (SBMLExtensionRegistry::getInstance().isRegistered(getPackageName()))
             {
               // do nothing;
               return;
             }
           
             //----------------------------------------------------------------------
             //
             // 2. Create an SBMLExtension derived object.
             //
             //----------------------------------------------------------------------
           
             GroupsExtension groupsExtension;
           
             //----------------------------------------------------------------------
             //
             // 3. Create SBasePluginCreatorBase derived objects required for this 
             //    extension. The derived classes can be instantiated by using the 
             //    following template class.
             //
             //    template<class SBasePluginType> class SBasePluginCreator
             //
             //    The constructor of the creator class has two arguments:
             //
             //        (1) SBaseExtensionPoint
             //            extension point to which the plugin object connected
             //                                  
             //        (2) std::vector<std::string> 
             //            a std::vector object that contains a list of URI 
             //            (package versions) supported by the plugin object.
             //                                       
             //    For example, two plugin objects (plugged in SBMLDocument and Model 
             //    elements) are required for the groups extension.
             //
             //    Since only 'required' attribute is used in SBMLDocument by the groups 
             //    package, existing SBMLDocumentPlugin class can be used as-is for the 
             //    plugin.
             //
             //    Since the lists of supported package versions (currently only 
             //    L3V1-groups-V1 supported ) are equal in the both plugin objects, 
             //    the same vector object is given to each constructor.
             //--------------------------------------------------------------------------
           
             std::vector<std::string> packageURIs;
             packageURIs.push_back(getXmlnsL3V1V1());
           
             SBaseExtensionPoint sbmldocExtPoint("core",SBML_DOCUMENT);
             SBaseExtensionPoint modelExtPoint("core",SBML_MODEL);
           
             SBasePluginCreator<SBMLDocumentPlugin, GroupsExtension> \
                    sbmldocPluginCreator(sbmldocExtPoint,packageURIs);

             SBasePluginCreator<GroupsModelPlugin, GroupsExtension> \
                     modelPluginCreator(modelExtPoint,packageURIs);
           
             //-------------------------------------------------------------------------------
             //
             // 3. Add the above SBasePluginCreatorBase derived objects to the SBMLExtension 
             // derived object.
             //
             //-------------------------------------------------------------------------------
           
             groupsExtension.addSBasePluginCreator(&sbmldocPluginCreator);
             groupsExtension.addSBasePluginCreator(&modelPluginCreator);
           
             //-------------------------------------------------------------------------
             //
             // 4. Register the SBMLExtension derived object to SBMLExtensionRegistry
             //
             //-------------------------------------------------------------------------
           
             int result = SBMLExtensionRegistry::getInstance().addExtension(&groupsExtension);
           
             if (result != LIBSBML_OPERATION_SUCCESS)
             {
               std::cerr << "[Error] GroupsExtension::init() failed." << std::endl;
             }



   --------------------------------------------------------------------------------
    1-7) Define a static global object (an instance of SBMLExtensionRegister template
         class) 
   --------------------------------------------------------------------------------

       Add an SBMLExtension derived object to the SBMLExtensionRegistry class
       by defining an instance of SBMLExtensionRegister template class as follows:
       (The example below in implemnted in GroupsExtension.cpp)


         static SBMLExtensionRegister<GroupsExtension> groupsExtensionRegistry;


       The above init() function is automatically invoked when this object is 
       instantiated before main() routine called.


--------------------------------------------------------------------------------
2. Implement SBase derived classes of the package extension
--------------------------------------------------------------------------------

Secondly, SBase derived classes for your package need to be implemented
based on the following steps:

   --------------------------------------------------------------------------------  
   2-1) Identify elements defined in the package extension
   --------------------------------------------------------------------------------

   For example, the following elements are defined in the groups package:

     1) Group
     2) Member
     3) ListOfMembers

   --------------------------------------------------------------------------------
   2-2) Identify which subelements and/or attributes are defined in each element
   --------------------------------------------------------------------------------

   For example, the following subelements and attributes are defined in 
   the Group element in the groups package.

     [subelements]

       1. ListOfMembers  mMembers  ('listOfMembers' element)

     [attributes]

       1. std::string         mId  ('id'   attribute)
       2. std::string       mName  ('name' attribute)


   --------------------------------------------------------------------------------
   2-3) Implement each SBase derived class
   --------------------------------------------------------------------------------

     ----------------------------------------------------------------------------
     2-3-1) Define protected data members that store identified subelements 
            and/or attributes 
     ----------------------------------------------------------------------------

       For example, the following protected data members are defined in
       Group class ('src/packages/groups/sbml/Group.h'):


               class LIBSBML_EXTERN Group : public SBase
               {
               protected:
                 std::string   mId;
                 std::string   mName;
                 ListOfMembers mMembers;

                 ....
                                  
               };    

         Basically, the attribute data will have one of the types "std::string", 
         "double", "int", or "bool", and the type of the element data will be 
         ListOf derived classes or SBase derived classes.
 
         The data members must be properly initialized in the constructor, and must 
         be properly copied in the copy constructor and assignment operator.

     ----------------------------------------------------------------------------
     2-3-2) Define the following two constructors
     ----------------------------------------------------------------------------
 
          ----------------------------------------------------------------------
          1) a constructor that accepts three arguments: 
             (1) SBML Level, (2) SBML Version, and (3) Package Version
          ----------------------------------------------------------------------

           For example, this type of constructor of Group class is implemented 
           in 'src/packages/groups/sbml/Group.cpp' as follows:


               Group::Group (unsigned int level, unsigned int version, 
                             unsigned int pkgVersion)
                 : SBase (level,version)   // <-- invokes parent's constructor
                  ,mId("")
                  ,mName("")
                  ,mMembers(level,version,pkgVersion)
               {
                 // set an SBMLNamespaces derived object (GroupsPkgNamespaces) of 
                 //this package.
                 setSBMLNamespacesAndOwn(new GroupsPkgNamespaces(level,version,
                                                                 pkgVersion));
                  
                 // connects child elements to this element.
                 connectToChild(); 
               }


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

             - default level, default version, and default pacakge version
               should be given as default arguments.
               (This may change in the future release).

             - the corresponding constructor of the parent class must be properly 
               invoked by using initializer of the constructor.
         
             - setSBMLNamespacesAndOwn() function must be invoked with a newly
	           created SBMLNamespaces derived object with the given level, version,
               and package version.

             - connectToChild() function must be invoked if the element has one
               or more child elements.
           ----------------------------------------------------------------------  

           For example, an instance of the SBase derived object is created by this
           constructor as follows:

   
               Layout layout(3,1,1);


          -----------------------------------------------------------------------
          2) a constructor that accepts an SBMLNamespaces derived object
          -----------------------------------------------------------------------
           For example, this type of constructor of Group class is implemented 
           in 'src/packages/groups/sbml/Group.cpp' as follows:
           (GroupsPkgNamespaces is the type of SBMLNamespaces derived class for
            groups package)


               Group::Group(GroupsPkgNamespaces* groupsns)
                : SBase(groupsns)
                 ,mId("")
                 ,mName("")
                 ,mMembers(groupsns)
               {
                 // set the element namespace of this object
                 setElementNamespace(groupsns->getURI());

                 // connect child elements to this element
                 connectToChild();

                 // load pacakge extensions bound with this object (if any)
                 loadPlugins(groupsns);
               }

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

             - SBMLNamespaces and its derived class throws an SBMLExtensionException
               if the given combination is invalid (undefined).

             - the corresponding constructor of the parent class must be properly 
               invoked by initializer.
         
             - setElementNamespace() function must be invoked with the URI
               of the package in the constructor.

             - connectToChild() function must be invoked if the element has one
               or more child elements.

             - loadPlugins() function should be invoked if the element can be
               extended by other package extensions.
           ----------------------------------------------------------------------  

           For example, an instance of the SBase derived object is created by 
           this constructor as follows:
	
   
               try
               {
                 LayputPkgNamespaces layoutns(3,1,1);
                 Layout              layout(&layoutns); 
               }
               catch (SBMLExtensionException e)
               {
                 cerr << "Caught " << e.what() << endl;
               }


       ===========================================================================
       (NOTE) 
 
       In the layout extension, additional constructors that accept one or more 
       attributes of the element have been implemented for backward compatibility
       (support for L2 model).
       (validation check of the given arguments of attributes are not performed.)
       ===========================================================================

    ----------------------------------------------------------------------------
    2-3-3) Override the following functions in the SBase class 
    ----------------------------------------------------------------------------

          - Copy Constructor

          - Assignment operator (operator=)

          - clone() function
            (basically implemented by using the copy constructor)


    ----------------------------------------------------------------------------
    2-3-4) Override the following virtual functions if one or more attributes 
           (except for those defined in its ancestors) are defined in this 
           element
    ----------------------------------------------------------------------------       

          - addExpectedAttributes()

          - readAttributes()

          - hasRequiredAttributes()

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

            - corresponding function of the parent class must be invoked
	          in  addExpectedAttributes() and readAttributes() functions
              as follows:


                Group::addExpectedAttributes(ExpectedAttributes& attributes)
                {
                   SBase::addExpectedAttributes(attributes);
                   ....
                }


               void
               Group::readAttributes (const XMLAttributes& attributes,
                                      const ExpectedAttributes& expectedAttributes)
               {
                 SBase::readAttributes(attributes,expectedAttributes);
                  ...
               }
         
                (SBase class is a parent of Group class.)


            - the following attributes don't need to be added in 
              the addExpectedAttributes() function because they are added
              in SBase::addExpectedAttributes() function.

                1) metaid  (L2V1 or later)
                2) sboTerm (L2V3 or later)


            - "src/packages/groups/sbml/{Group,Member}.{h,cpp}" are simple example
               files in which these functions are implemented.
          ----------------------------------------------------------------------


    ----------------------------------------------------------------------------
    2-3-5] Override the following virtual functions if one or more subelements 
           are defined in this element
    ----------------------------------------------------------------------------       

          - createObject()

          - writeElements()

          - hasRequiredElements()

          - setSBMLDocument()

          - enablePackageInternal()
	   
          - connectToChild()

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

            - corresponding function of the parent class must be invoked
	          in writeElements(), setSBMLDocument(), and enablePackageInternal()
              functions

            - 'src/packages/groups/sbml/{Group,Member}.{h,cpp} are simple example
               files in which these functions are implemented.
          ----------------------------------------------------------------------


    ----------------------------------------------------------------------------
    2-3-6] Override the following virtual functions if the element is a top-level 
           element of the package
    ----------------------------------------------------------------------------           

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

            - For example, this function is implemented in the following top-level
              elements:

                 1) SBMLDocument   (SBML Core)
                 2) ListOfLayouts  (Layout extension)
                 3) ListOfGroups   (Groups extension)


            - In package extensions, writeXMLNS() function writes an xmlns="..."
              attribute if the top-level element of the package extension 
              belongs to default XML namespace.
              This behaviour can be enabled/disabled by the following function:

                SBMLDocument::enableDefaultNS(const std::string& package, bool flag)
          ----------------------------------------------------------------------


      ----------------------------------------------------------------------------           
      2-3-7] Override the following virtual functions if 'id' attribute is defined 
             in the element
      ---------------------------------------------------------------------------- 

           1) setId()

           2) getId()

           3) isSetId()

           4) unsetId()

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

            - Basically, implementation of these functions are almost the same
              between elements defining the 'id' attribute

            - setId() function can be easily implemented as follows (one line):

                 return SyntaxChecker::checkAndSetSId(id,mId);
          ----------------------------------------------------------------------

      ---------------------------------------------------------------------------- 
      2-3-8] Override the following virtual functions if 'name' attribute is defined 
             in the element
      ---------------------------------------------------------------------------- 

           1) setName()

           2) getName()

           3) isSetName()

           4) unsetName()

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

            - Basically, implementation of these functions are almost the same
              between elements defining the 'id' attribute
          ----------------------------------------------------------------------


      ---------------------------------------------------------------------------- 
      2-3-9]  Add function calls of loadPlugins() in the constructor which accepts 
              an SBMLNamespaces derived class for supporting package extensions.
      ---------------------------------------------------------------------------- 

            (loadPlugins() doesn't need to be invoked in an abstract class.) 

      ---------------------------------------------------------------------------- 
      2-3-10]  Add function calls of connectToChild() in constructor, 
               copy constructor, and assignment operator.
      ---------------------------------------------------------------------------- 

      ---------------------------------------------------------------------------- 
      2-3-11] Implement additional (package developer-defined) functions for
              manipulating the attributes and/or subelements
      ---------------------------------------------------------------------------- 

        For example, getMember(), addMember(), getNumMembers(), createMember(),
        removeMember() and etc. are implemented in Group class of the groups package.

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

           - when implementing setXXXX(const XXXX&) / addXXXX(const XXXX&) 
             functions that set/add the given SBase derived object, the following
             check should be done for the given object:

	           1) check if the given object is not NULL

               2) check if the SBML Level, Version, and Package Version 
                  of the given object matches those of target element

               3) check if an object with the id of the given object
                  already exists (i.e. checks an error of duplicated object id


           - one of status codes, which is defined in 

                "src/common/operationReturnValues.h"

             should be returned based on the result of functions except for
	         getter functions and functions returning a bool value


           -  In setXXXX(const XXXX&) function,  connectToParent() function 
              must be invoked if the given object is valid.

               (for detail, please check existing implementation such as
                setKineticLaw() function in  "src/sbml/Reaction.cpp")

          ----------------------------------------------------------------------

--------------------------------------------------------------------------------
3. Implement one or more SBasePlugin derived classes 
--------------------------------------------------------------------------------

Thirdly, SBasePlugin derived classes for the pacakge needs to be implemented.

   ------------------------------------------------------------------------------
   3-1) Identify which core SBML elements (e.g. Model, Reaction,..) to be extended 
        (i.e. adding attributes and/or elements) for your package extensions.
   ------------------------------------------------------------------------------

    For example, the following SBML elementes are extended by groups and layout
    packages, respectively:


      1) groups package

          1. SBMLDocument
              - Add 'required' attribute

          2. Model
              - Add 'listOfGroups' element 


      2) layout package

          1. SBMLDocument
              - Add 'required' attribute

          2. Model
              - Add 'listOfLayouts' element 

          3. SpeciesReferences (only for L2V1 for backward compatibility)
              - Add 'id' attribute
     
   ------------------------------------------------------------------------------
   3-2) Implement SBasePlugin derived objects for each identified 
        core SBML element based on the following policy:
   ------------------------------------------------------------------------------

       For example, to extend the identified classes, the following SBasePlugin 
       derived classes are newly implemnted in the groups and layout packages:

          1) groups

              - LayoutModelPlugin 
              - LayoutSpeciesReferencesPlugin

          2) groups

              - GroupsModelPlugin

         ----------------------------------------------------------------------
         (NOTE) Package developers can use existing SBMLDocumentPlugin class
                as-is for extending the SBMLDocument class if only 'required' 
                attribute is added the class in their packages, otherwise package 
                developers must implement a new SBMLDocumentPlugin derived class 
                for extending the SBMLDocument class.

                Since the both of groups and layout packages require only 
                'required' attribute for extending the SBMLDocument class, 
                the SBMLDocumentPlugin is used as-is for the packages.
         ----------------------------------------------------------------------


      ----------------------------------------------------------------------------
      3-2-1] Define additional protected data members that store additional 
             elements and/or attributes if one ore more elemnets and/or attributes 
             are added to the target core element.
      -----------------------------------------------------------------------------
         
         Basically, the attribute data will have one of the types "std::string", 
         "double", "int", or "bool", and the type of the element data will be 
         ListOf derived classes or SBase derived classes.
 
         The additional data members must be properly initialized in the constructor,
         and must be properly copied in the copy constructor and assignment operator.

         For example, the following data member is defined in the GroupsModelPlugin 
         class (in GroupsModelPlugin.h):

             ListOfGroups mGroups;

      -----------------------------------------------------------------------------
      3-2-2] Override the following functions in the SBasePlugin class
      -----------------------------------------------------------------------------

            - Constructor 
              ( SBasePlugin(const std::string& uri, const std::string &prefix) )

            - Copy Constructor

            - Assignment operator (operator=)

            - clone() (virtual) function 
              (basically implemented by using the copy constructor)


          ----------------------------------------------------------------------
          (NOTE) 'src/extension/SBMLDocumentPlugin.{h,cpp} is a simple example
                  files in which these functions are implemented.
          ----------------------------------------------------------------------

      -----------------------------------------------------------------------------
      3-2-3] Override the following virtual functions if one or more attributes 
             are added to the target core element
      -----------------------------------------------------------------------------

          - addExpectedAttributes()

          - readAttributes()

          - hasRequiredAttributes()

      -----------------------------------------------------------------------------
      3-2-4] Override the following virtual functions if one or more top-level 
             elements are added to the target core element
      -----------------------------------------------------------------------------

          - createObject()

          - writeElements()

          - hasRequiredElements()

          - setSBMLDocument()
 
          - connectToParent()

          - enablePackageInternal()

          ----------------------------------------------------------------------
          (NOTE) 'src/packages/groups/extension/GroupsModelPlugin.{h,cpp}' and
                 'src/packages/layout/extension/LayoutModelPlugin.{h,cpp}'
                  are example files in which the functions are implemented.
          ----------------------------------------------------------------------

      -----------------------------------------------------------------------------
      3-2-5] The following virtual functions must be overridden if one or more 
             additional xmlns attributes need to be added to the target element
      -----------------------------------------------------------------------------

          - writeXMLNS()
      
          ----------------------------------------------------------------------
	  (NOTE) Currently, no example files implementing this function
          ----------------------------------------------------------------------

      -----------------------------------------------------------------------------
       3-2-6] Implement additional (package developer-defined) functions for
              manipulating the additional attributes and/or top-level elements
      -----------------------------------------------------------------------------
          
          For example, the following manipulation functions are implemented in 
          LayoutModelPlugin class (a class for the extension of the model element 
          in layout package) for manipulating the additional <listOfLayouts> element
          in the list element:


              1) const ListOfLayouts* getListOfLayouts() const
              2) ListOfLayouts*       getListOfLayouts()
              3) Layout*              getLayout(unsigned int index)
              4) Layout*              getLayout(const std::string &sid)
              5) int                  addLayout(const Layout* layout)
              6) Layout*              createLayout()
              7) Layout*              removeLayout(unsigned int n)
              8) int                  getNumLayouts() const


          Similarly, the following manipulation functions are implemented in 
          GroupsModelPlugin class (a class for the extension of the model element 
          in groups package) for manipulating the additional <listOfGroups> element
          in the list element:


              1) const ListOfGroups* getListOfGroups() const
              2) ListOfGroups*       getListOfGroups()
              3) Group*              getGroup(unsigned int index)
              4) Group*              getGroup(const std::string &sid)
              5) int                 addGroup(const Group* group)
              6) Group*              createGroup()
              7) Group*              removeGroup(unsigned int n)
              8) int                 getNumGroups() const
            

--------------------------------------------------------------------------------
4. Implement a forward declaration file
--------------------------------------------------------------------------------

A header file in which forward declarations for all classes defined in the
package extension should be implemented.

For example, please see "src/common/sbmlfwd.h" (forward declaration of SBML Core),  
"src/packages/groups/common/groupsfwd.h" (forward declaration of Groups package), 
and "src/packages/layout/common/layoutfwd.h" (forward declaration of Layout package)

--------------------------------------------------------------------------------
5. Implement a header file which includes all SBML types defined in the extension
--------------------------------------------------------------------------------

A header file in which all SBML types defined in the extension should be implemented.
For example, please see "src/packages/groups/common/GroupsExtensionTypes.h" of the
groups extension and "src/packages/layout/common/LayoutExtensionTypes.h" of the
layout extension.

--------------------------------------------------------------------------------------
6. Defines a macro vaule of the package extension 
--------------------------------------------------------------------------------------

   (NOTE) A new package extension can be implemented and built outside the 
          source tree of libSBML. So, this step is not mandatory if you don't
          want to import your package extension into the source tree of libSBML.


USE_%%PACKAGE_NAME%% macro variable needs to be defined in the following files:
     
    1]  "src/common/libsbml-config-unix.h.in"
    2]  "src/common/libsbml-config-win.h"

       (%%PACKAGE_NAME%% is a place holder of the package name.
        For example, USE_LAYOUT is defined for the layout package.)

--------------------------------------------------------------------------------     
7. How to import a source tree of a package extension into the source 
   tree of libSBML-5
--------------------------------------------------------------------------------     

   (NOTE) A new package extension can be implemented and built outside the 
          source tree of libSBML. So, this step is not mandatory if you don't 
          want to import your package extension into the source tree of libSBML.

   -----------------------------------------------------------------------------
   7-1) Add configurations for make system in the current libSBML-5
   -----------------------------------------------------------------------------

    (The following example configuration is that of groups extension)

      ----------------------------------------------------------------------
      7-1-1) configure.ac
      ----------------------------------------------------------------------

        1) Add --enable-XXXX 


          =========================================================================
          dnl -------------------------------------------------------
          dnl Groups extension
          dnl -------------------------------------------------------
  
          AC_ARG_ENABLE([groups],
          AC_HELP_STRING([--enable-groups@<:@=ARG@:>@],
                         [Build the SBML groups extension (default=no)]),
            [enable_groups=$enableval],
            [enable_groups=no])
  
          if test "$enable_group" != no; then
            AC_DEFINE([USE_GROUPS], 1, [Define to 1 to build the SBML groups extension.])
            AC_SUBST(USE_GROUPS, 1)
          fi
          =========================================================================


        2) Add AC_CONFIG_FILES for additional Makefile.in files


          =========================================================================
          AC_CONFIG_FILES([src/packages/groups/Makefile])
          AC_CONFIG_FILES([src/packages/groups/common/Makefile])
          AC_CONFIG_FILES([src/packages/groups/extension/Makefile])
          AC_CONFIG_FILES([src/packages/groups/sbml/Makefile])
          =========================================================================

  
        3) Add the code for noticing the enabled package

   
          ===========================================================================
           if test "$enable_groups" != "no" ; then
             echo "  Using groups extension  = yes"
           fi
          ===========================================================================


        4) Run a shell script "autogen.sh" in the top directory of the libsbml-5
           as follows (for updating configure script):

              % ./autogen.sh
         
      ----------------------------------------------------------------------
      7-1-2) src/packages/Makefile.in
      ----------------------------------------------------------------------

        Add the name of package to 'subdirs' variable based on existing code.

   -----------------------------------------------------------------------------
   7-2) Create a directory tree of the package
   -----------------------------------------------------------------------------

      -----------------------------------------------------------------------------
      7-2-1) Create a top directory of the package in "src/packages/"
      -----------------------------------------------------------------------------

        Currently, "src/packages/groups" (groups package) and 
        "src/packages/layout" (layout package) exist in the directory.


      -----------------------------------------------------------------------------
      7-2-2) Create the following sub directories in the "src/packages/PKGNAME"
      -----------------------------------------------------------------------------

        1) common

           common header and/or class files (e.g. sbmlfwd.h) are located

        2) extension

           SBMLExtension and SBasePlugin derived classes of the package 
           extension are located

        3) sbml

           SBase derived classes of the package extension are located.

        4) util (if needed)

           Utility class files are located (e.g. LayoutAnnotation.{h,cpp} in
           layout package).

        5) other directories (if needed)


   -----------------------------------------------------------------------------
   7-3) Create Makefile.in in each sub directory based on existing 
        Makefile.in in layout or groups extensions
   -----------------------------------------------------------------------------

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