libSBML C# API  libSBML 5.8.0 C# API
 All Classes Namespaces Files Functions Variables Properties Pages
Summary of extension support classes

This section describes the summary of extension support classes which are used for implementing a package extension in libSBML-5.

1. Overview of extension support classes

2. Extension support classes
  1. SBMLExtension class
  2. SBasePlugin class
  3. SBaseExtensionPoint
  4. SBasePluginCreator
  5. SBMLExtensionNamespaces
  6. SBMLExtensionRegistry
  7. SBMLExtensionRegister
  8. SBMLExtensionException

1. Overview of extension support classes

The package architecture of SBML Level 3 enables it to develop a package extension which defines additional attributes and/or elements to each pre-defined element in SBML Level 3 Core package.

In libSBML-5, extension support classes are provieded to enable developers to implement their package extensions. Basically, each package extension consists of two set of components; one is classes which are extended or instantiated from the extension support classes, and other is SBase extended classes which represent elements defined in each package extension (e.g., <listOfLayouts>, <layout> and etc. in layout package). In this section, the summary of the extension support classes are described.

Some of the support classes need to be extended (i.e., implementing a subclass) or instantiated (i.e., instantiating a class from a template class) to implement each package specific properties/features. For example, basically, the following classes need to be extended by package developers for each package extension:

  • SBasePlugin is a class plugged in a pre-defined element to be extended. It contains additional attributes and/or elements of a package extension which are directly contained by some pre-defined element to be extended, and it provides functions for accessing the additional attributes and/or elements.
  • SBMLExtension class is a core component of a package extension. It provides functions for getting common attributes of package extension, and functions for initializing/registering the package when the library of the package is loaded.

Also, the following template classes need to be instantiated by package developers for each package extension:

  • SBasePluginCreator is a factory class which creates an SBasePlugin extended object.
  • SBMLExtensionNamespaces is an SBMLNamespaces extended template class which is specific to each package extension. It provides information of the package version, and used when creating an SBase extended objects of the package extension.

The following classes don't need to be extended or instantiated:

  • SBaseExtensionPoint class represents an element to be extended (extension point).

  • SBMLExtensionRegistry class is a central registry class. Each package extension is registered to this registry class.

  • SBMLExtensionRegister class is a simple register class. It is used to automatically register each package extension to the SBMLExtensionRegistry class when each library is loaded.

  • SBMLExtensionException class is a exception class which can be thrown when an exception about pacakge extension occurs.

2. Extension support classes

1. SBMLExtension class

SBMLExtension class (abstract class) is a core component of each package extension which needs to be extended by package developers. The class provides functions for getting common attributes of package extension (e.g. package name, package version, and etc.), functions for adding (registering) each instantiated SBasePluginCreator object, and a static function (defined in each SBMLExtension extended class) for initializing/registering the exntension package when the library of the package is loaded.

Package developer must implement an SBMLExtension extended class (e.g. LayoutExtension class is implemented for layout extension), and the following functions/variables must be implemented in the derived class:

  1. common static functions such as:

    • const std::string getPackageName(), the name (label) of package
    • const unsigned int getDefaultLevel(), default level
    • const unsigned int getDefaultVersion(), default version,
    • const unsigned int getDefaultPackageVersion(), default package_version,
    • const std::string getXMLnsL3V1V1(), URI of package versions,

  2. pure virtual functions for getting common attributes such as:

    • virtual const std::string& getName () const =0. This function returns the name of the package (e.g., "layout", "multi").
    • virtual unsigned int getLevel (const std::string &uri) const =0. This function returns the SBML level with the given URI of this package.
    • virtual unsigned int getVersion (const std::string &uri) const =0. This function returns the SBML version with the given URI of this package.
    • virtual unsigned int getPackageVersion (const std::string &uri) const =0. This function returns the package version with the given URI of this package.
    • virtual const char* getStringFromTypeCode (int typeCode) const =0. This function takes a type code of this package and returns a string representing the code.
    • virtual SBMLNamespaces* getSBMLExtensionNamespaces (const std::string &uri) const =0. This function returns an SBMLNamespaces derived object (e.g., SBMLExtensionNamespaces<LayoutExtension> whose alias type is LayoutPkgNamespaces) corresponding to the given uri.

  3. static int init() function which initializes and registers the package extension to the SBMLExtensionRegistry class (init() function is implemented in each SBMLExtension derived class implemented by package developers.)

SBMLExtension class also provides the following functions for adding/getting SBasePluginCreatorBase derived objects :

  • int addSBasePluginCreator(const SBasePluginCreatorBase* sbaseExt). This function adds the given SBasePluginCreatorBase object to this package extension.
  • SBasePluginCreatorBase* getSBasePluginCreator(const SBaseExtensionPoint& extPoint). This function returns an SBasePluginCreatorBase object of this package extension bound to the given extension point.
  • SBasePluginCreatorBase* getSBasePluginCreator(unsigned int i). This function returns an SBasePluginCreatorBase object of this package extension with the given index.

These functions are used for initializing each package extension in the init() function.

The more detailed information (what virtual functions must be overridden, what static data members must be implemented and etc.) is described in the SBMLExtension class.

2. SBasePlugin class

Additional attributes and/or elements of a package extension which are directly contained by some pre-defined element are contained/accessed by SBasePlugin class which is extended by package developers for each extension point. The extension point, which represents an element to be extended, is identified by a combination of a pakcage name and a typecode of the element, and is represented by SBaseExtensionPoint class.

For example, the layout extension defines <listOfLayouts> element which is directly contained in <model> element of the core package. In the layout package (provided as one of example packages in libSBML-5), the additional element for the model element is implemented as ListOfLayouts class (an SBase derived class) and the object is contained/accessed by a LayoutModelPlugin class (an SBasePlugin derived class).

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 an SBasePlugin exntended class for each element to be extended (e.g. SBMLDocument, Model, ...) in which additional attributes and/or top-level elements of the package extension are directly contained.

To implement reading/writing functions for attributes and/or top-level elements of the SBsaePlugin extended class, package developers should or must override the corresponding virtual functions below provided in the SBasePlugin class:

  • reading elements:

    1. virtual SBase* createObject (XMLInputStream& stream)
    2. virtual bool readOtherXML (SBase* parentObject, XMLInputStream& stream)
  • reading attributes:

    1. virtual void addExpectedAttributes(ExpectedAttributes& attributes)
    2. virtual void readAttributes (const XMLAttributes& attributes, const ExpectedAttributes& expectedAttributes)
  • writing elements:

    1. virtual void writeElements (XMLOutputStream& stream) const
  • writing attributes:

    1. virtual void writeAttributes (XMLOutputStream& stream) const
    2. virtual void writeXMLNS (XMLOutputStream& stream) const

  • checking elements:

    1. virtual bool hasRequiredElements() const

  • checking attributes:

    1. virtual bool hasRequiredAttributes() const

To implement package-specific creating/getting/manipulating functions of the SBasePlugin derived class (e.g., getListOfLayouts(), createLyout(), getLayout(), and etc are implemented in LayoutModelPlugin class of the 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 such as:

  • virtual void setSBMLDocument(SBMLDocument* d) ,
  • virtual void connectToParent(SBase *sbase) ,
  • virtual void enablePackageInternal(const std::string& pkgURI, const std::string& pkgPrefix, bool flag)

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 extended classes are implemented in the layout extension:

  1. SBMLDocumentPlugin class for SBMLDocument element

    • required attribute is added to SBMLDocument object.

    (SBMLDocumentPlugin class is a common SBasePlugin extended 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 (used only for SBML L2V1)

    • 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()

3. SBaseExtensionPoint class

SBaseExtensionPoint represents an element to be extended (extension point) and the extension point is identified by a combination of a pakcage name and a typecode of the element.

For example, an SBaseExtensionPoint object which represents an extension point of the model element defined in the core package can be created as follows:

      SBaseExtensionPoint  modelextp("core", SBML_MODEL);

Similarly, an SBaseExtensionPoint object which represents an extension point of the layout element defined in the layout extension can be created as follows:

      SBaseExtensionPoint  layoutextp("layout", SBML_LAYOUT_LAYOUT);

SBaseExtensionPoint object is required as one of arguments of the constructor of SBasePluginCreator<class SBasePluginType, class SBMLExtensionType> template class to identify an extension poitnt to which the plugin object created by the creator class is plugged in. For example, the SBasePluginCreator class which creates a LayoutModelPlugin object of the layout extension which is plugged in to the model element of the core package can be created with the corresponding SBaseExtensionPoint object as follows:

  // std::vector object that contains a list of URI (package versions) supported 
  // by the plugin object.
  std::vector<std::string> packageURIs;
  packageURIs.push_back(XmlnsL3V1V1);
  packageURIs.push_back(XmlnsL2);  

  // creates an extension point (model element of the "core" package)
  SBaseExtensionPoint  modelExtPoint("core",SBML_MODEL);
   
  // creates an SBasePluginCreator object 
  SBasePluginCreator<LayoutModelPlugin, LayoutExtension>  modelPluginCreator(modelExtPoint,packageURIs);

This kind of code is implemented in init() function of each SBMLExtension derived classes.

4. SBasePluginCreator class

SBasePluginCreator template class is a factory class which creates an SBasePlugin object.

Basically, package developers only have to instantiate the template class for each SBasePlugin extended class of their packages and have to register the instantiated objects to their SBMLExtension extended classes.

The template class is instantiated for each SBasePlugin extended class and used by each SBase class for dynamically internally create and add the corresponding SBasePlugin object. For example, SBasePluginCreator<LayoutModelPlugin, LayoutExtension> is instantiated for creating an LayoutModelPlugin object of the layout extension.

Each SBasePlugin extended object is dynamically internally created and added to the corresponding SBase extended object when the SBase element is read or created (Basically, this behaviour is internally implemented and thus package developers don't have to care the implementation).

For example, a LayoutModelPlugin object of SBML L3V1 Layout V1 is internally/dynamically created and added to a Model object when the Model object is constructed as follows:

     SBMLNamespaces sbmlns(3,1,"layout",1);  // namespace of L3V1 Core with L3V1 Layout V1
     Model model(&sbmlns);                   

On the other hand, no SBasePlugin extended objects are created/added when no package extensions are specified as follows:

     SBMLNamespaces sbmlns(3,1);   // namespace of L3V1 Core 
     Model model(&sbmlns);    

To read/create elements of a package extension in user's program, the followings are required:

  1. a corresponding package extension needs to be registered to SBMLExtensionRegistry class

    (Basically, this is automatically done by linking a shared library of the package extension with a user's program at compile time),

  2. the corresponding package extension needs to be enabled in the target model (i.e., xmlns attribute of the package extension is defined in <sbml> element).

5. SBMLExtensionNamespaces class

SBMLExtensionNamespaces is a template class which is extended from an SBMLNamespaces class and specific to each package extension.

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.

Package developers must define (instantiate) its own SBMLNamespaces derived class from this template class and then define a typedef declaration 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 its 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")

Each SBase derived class of package extensions should implement a constructor that accepts its SBMLNamespaces derived class. For example, Layout class (one of SBase derived classes in the layout extension) defines the following constructor which accepts a LayoutPkgNamespaces object.

  /**
   * Creates a new Layout with the given LayoutPkgNamespaces object.
   */
   Layout(LayoutPkgNamespaces* layoutns);

6. SBMLExtensionRegistry class

SBMLExtensionRegistry class is a central registry class for package extensions. Each package extension is registered to this registry class by using SBMLExtensionRegister class when each library of package extensions is loaded. The registry class is acessed by various classes (e.g. SBase extended class) to retrieve the information of package extensions and to create additional attributes and/or elements by factory objects of package extensions. In other words, libSBML can't parse package extensions which are not registered in the registry class.

This class provide the following features:

  1. registers a package extension (adding an SBMLExtension extended class of a package extension)

  2. returns an SBMLExtension extended object for the caller to get common properties of the target package extension (e.g. the name of package, default level, version, package_version, and URI of package versions)

  3. returns an SBasePluginCreatorBase extended object for the caller (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. enables/disables the registered package extensions.

  5. returns the number of registered package extensions.

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

       static void LayoutExtension::init()
       {
         LayoutExtension layoutExtension;
         ...
         <snip>
         ...
         int result = SBMLExtensionRegistry::getInstance().addExtension(&layoutExtension);
       }

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 (just instantiating an object):

     static SBMLExtensionRegister<LayoutExtension> layoutExtensionRegistry;

This code registers the LayoutExtension to the SBMLExtensionRegistry class when the code is parsed at start-up time.

8. SBMLExtensionException class

SBMLExtensionException class is an 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