libSBML C++ API  libSBML 5.8.0 C++ API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
SBMLExtension Class Referenceabstract
Inheritance diagram for SBMLExtension:
[legend]

Detailed Description

The core component of SBML's package extension.

SBMLExtension class (abstract class) is a core component of 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 package extension when the library of the package is loaded.

How to implement an SBMLExtension extended class for each package extension

Package developers must implement an SBMLExtension extended class for their packages (e.g. GroupsExtension class is implemented for groups extension). The extended class is 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. Define the following static functions in the extended class: (examples of groups extension are shown respectively)

    1. A string of package name (label) (The function name must be "getPackageName".)

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

    2. Methods returning an integer of Default SBML level, version, and package version (The method names must be "getDefaultLevel()", "getDefaultVersion()", and "getDefaultPackageVersion()" respectively.)

        unsigned int GroupsExtension::getDefaultLevel()
        {
      	return 3;
        }  
        unsigned int GroupsExtension::getDefaultVersion()
        {
      	return 1; 
        }
        unsigned int GroupsExtension::getDefaultPackageVersion()
        {
      	return 1;
        }  
      
    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. Strings that represent the other URI needed in this package (if any)

  2. Override the following pure virtual functions

    • virtual const std::string& getName () const =0. This function returns the name of the package (e.g., "layout", "groups").
    • 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 unsigned int getURI (unsigned int sbmlLevel, unsigned int sbmlVersion, unsigned int pkgVersion) const =0. This function returns the URI (namespace) of the package corresponding to the combination of the given sbml level, sbml version, and pacakege version
    • virtual SBMLExtension* clone () const = 0. This function creates and returns a deep copy of this derived object.

    For example, the above functions are overridden in the groups package ("src/packages/groups/extension/GroupsExtension.cpp") as follows:

    const std::string&
    GroupsExtension::getName() const
    {
      return getPackageName();
    }
    
    unsigned int 
    GroupsExtension::getLevel(const std::string &uri) const
    {
      if (uri == getXmlnsL3V1V1())
      {
        return 3;
      }
      
      return 0;
    }
    
    unsigned int 
    GroupsExtension::getVersion(const std::string &uri) const
    {
      if (uri == getXmlnsL3V1V1())
      {
        return 1;
      }
    
      return 0;
    }
    
    unsigned int
    GroupsExtension::getPackageVersion(const std::string &uri) const
    {
      if (uri == getXmlnsL3V1V1())
      {
        return 1;
      }
    
      return 0;
    }
    
    const std::string& 
    GroupsExtension::getURI(unsigned int sbmlLevel, unsigned int sbmlVersion, unsigned int pkgVersion) const
    {
      if (sbmlLevel == 3)
      {
        if (sbmlVersion == 1)
        {
          if (pkgVersion == 1)
          {
            return getXmlnsL3V1V1();
          }
        }
      }
    
      static std::string empty = "";
    
      return empty;
    }
    
    GroupsExtension* 
    GroupsExtension::clone () const
    {
      return new GroupsExtension(*this);  
    }
    

    Constructor, copy Constructor, and destructor also must be overridden if additional data members are defined in the derived class.

  3. Define typedef and template instantiation code for the package specific SBMLExtensionNamespaces template class

    1. typedef for the package specific SBMLExtensionNamespaces template class

      For example, the typedef for GroupsExtension (defined in the groups package) is implemented in GroupsExtension.h as follows:

        // GroupsPkgNamespaces is derived from the SBMLNamespaces class and used when creating an object of 
        // SBase derived classes defined in groups package.
        typedef SBMLExtensionNamespaces<GroupsExtension> GroupsPkgNamespaces;
      

    2. template instantiation code for the above typedef definition in the implementation file (i.e., *.cpp file).

      For example, the template instantiation code for GroupsExtension is implemented in GroupsExtension.cpp as follows:

        // Instantiate SBMLExtensionNamespaces<GroupsExtension> (GroupsPkgNamespaces) for DLL.
        template class LIBSBML_EXTERN SBMLExtensionNamespaces<GroupsExtension>;
      

    The SBMLExtensionNamespaces template class is a derived class of SBMLNamespaces and 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.
    

  4. Override the following pure virtual function which returns the SBMLNamespaces derived object

           virtual SBMLNamespaces* getSBMLExtensionNamespaces (const std::string &uri) const =0
    

    For example, the function is overridden in GroupsExtension class as follows:

    SBMLNamespaces*
    GroupsExtension::getSBMLExtensionNamespaces(const std::string &uri) const
    {
      GroupsPkgNamespaces* pkgns = NULL;
      if ( uri == getXmlnsL3V1V1())
      {
        pkgns = new GroupsPkgNamespaces(3,1,1);    
      }  
      return pkgns;
    }
    

  5. Define an enum type for representing the typecode of elements (SBase extended classes) defined in the package extension

    For example, SBMLGroupsTypeCode_t for groups package is defined in GroupsExtension.h as follows:

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

    SBML_GROUPS_GROUP corresponds to the Group class (<group>) and SBML_GROUPS_MEMBER corresponds to the Member (<member>) class, respectively.

    Similarly, SBMLLayoutTypeCode_t for layout package is defined in LayoutExtension.h as follows:

          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;
    

    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() function but also that of getPackageName() function should be checked as follows:

              void example (const SBase *sb)
              {
                const 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:
                       ....
                  }
                } 
                else if (pkgName == "groups") {
                  switch (sb->getTypeCode()) {
                    case SBML_GROUPS_GROUP:
                       ....
                       break;
                    case SBML_GROUPS_MEMBER:
                       ....
                  }
                }
                ...
              } 
    

  6. Override the following pure virtual function which returns a string corresponding to the given typecode:

           virtual const char* SBMLExtension::getStringFromTypeCode(int typeCode) const;
    

    For example, the function for groups extension is implemented as follows:

    static
    const char* SBML_GROUPS_TYPECODE_STRINGS[] =
    {
        "Group"
      , "Member"
    };
    
    const char* 
    GroupsExtension::getStringFromTypeCode(int typeCode) const
    {
      int min = SBML_GROUPS_GROUP;
      int max = SBML_GROUPS_MEMBER;
    
      if ( typeCode < min || typeCode > max)
      {
        return "(Unknown SBML Groups Type)";  
      }
    
      return SBML_GROUPS_TYPECODE_STRINGS[typeCode - min];
    }
    

  7. Implements a "static void init()" function in the derived class

    In the init() function, initialization code which creates an instance of the derived class and registering code which registers the instance to SBMLExtensionRegistry class are implemented.

    For example, the init() function for groups package is implemented as follows:

    void 
    GroupsExtension::init()
    {
      //-------------------------------------------------------------------------
      //
      // 1. Checks if the groups pacakge has already been registered.
      //
      //-------------------------------------------------------------------------
    
      if (SBMLExtensionRegistry::getInstance().isRegistered(getPackageName()))
      {
        // do nothing;
        return;
      }
    
      //-------------------------------------------------------------------------
      //
      // 2. Creates an SBMLExtension derived object.
      //
      //-------------------------------------------------------------------------
    
      GroupsExtension groupsExtension;
    
      //-------------------------------------------------------------------------------------
      //
      // 3. Creates SBasePluginCreatorBase derived objects required for this 
      //    extension. The derived classes can be instantiated by using the following 
      //     template class.
      //
      //    temaplate<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, and
      //    the 'required' flag must always be 'false', the existing
      //    SBMLDocumentPluginNotRequired 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<SBMLDocumentPluginNotRequired, GroupsExtension> sbmldocPluginCreator(sbmldocExtPoint,packageURIs);
      SBasePluginCreator<GroupsModelPlugin,   GroupsExtension> modelPluginCreator(modelExtPoint,packageURIs);
    
      //--------------------------------------------------------------------------------------
      //
      // 3. Adds the above SBasePluginCreatorBase derived objects to the SBMLExtension derived object.
      //
      //--------------------------------------------------------------------------------------
    
      groupsExtension.addSBasePluginCreator(&sbmldocPluginCreator);
      groupsExtension.addSBasePluginCreator(&modelPluginCreator);
    
      //-------------------------------------------------------------------------
      //
      // 4. Registers 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;
      }
    }
    

  8. Instantiate a global SBMLExtensionRegister variable in appropriate implementation file

    For example, the global variable for the groups extension is instantiated in GroupsExtension.cpp as follows:

      static SBMLExtensionRegister<GroupsExtension> groupsExtensionRegister;
    

    The init() function is invoked when the global variable is instantiated, by which initialization and registering the package extension are performed.

Public Member Functions

virtual void addL2Namespaces (XMLNamespaces *xmlns) const
 adds all L2 Extension namespaces to the namespace list. More...
 
virtual SBMLExtensionclone () const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual void enableL2NamespaceForDocument (SBMLDocument *doc) const
 Adds the L2 Namespace to the document and enables the extension. More...
 
virtual unsigned int getLevel (const std::string &uri) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual const std::string & getName () const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
int getNumOfSBasePlugins () const
 Returns the number of SBasePlugin objects stored in this object. More...
 
unsigned int getNumOfSupportedPackageURI () const
 Returns the number of supported package Namespace (package versions) of this package extension. More...
 
virtual unsigned int getPackageVersion (const std::string &uri) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual SBMLNamespacesgetSBMLExtensionNamespaces (const std::string &uri) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual const char * getStringFromTypeCode (int typeCode) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
const std::string & getSupportedPackageURI (unsigned int i) const
 Returns the ith URI (the supported package version) More...
 
virtual const std::string & getURI (unsigned int sbmlLevel, unsigned int sbmlVersion, unsigned int pkgVersion) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual unsigned int getVersion (const std::string &uri) const =0
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
bool isEnabled () const
 Check if this package is enabled (true) or disabled (false). More...
 
virtual bool isInUse (SBMLDocument *doc) const
 Determines whether this extension is being used by the given SBMLDocument. More...
 
bool isSupported (const std::string &uri) const
 Returns a flag indicating, whether the given URI (package version) is supported by this package extension. More...
 
SBMLExtensionoperator= (const SBMLExtension &)
 Assignment operator for SBMLExtension. More...
 
virtual void removeL2Namespaces (XMLNamespaces *xmlns) const
 Removes the L2 Namespaces. More...
 
 SBMLExtension ()
 Constructor. More...
 
 SBMLExtension (const SBMLExtension &)
 Copy constructor. More...
 
bool setEnabled (bool isEnabled)
 enable/disable this package. More...
 
virtual ~SBMLExtension ()
 Destroy this object. More...
 

Constructor & Destructor Documentation

SBMLExtension::SBMLExtension ( )

Constructor.

SBMLExtension::SBMLExtension ( const SBMLExtension orig)

Copy constructor.

SBMLExtension::~SBMLExtension ( )
virtual

Destroy this object.

Member Function Documentation

void SBMLExtension::addL2Namespaces ( XMLNamespaces xmlns) const
virtual

adds all L2 Extension namespaces to the namespace list.

adds the L2 Namespace

This method should be overridden by all extensions that want to serialize to an L2 annotation.

virtual SBMLExtension* SBMLExtension::clone ( ) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Creates and returns a deep copy of this SBMLExtension object.

Returns
a (deep) copy of this SBase object

Implemented in CompExtension.

void SBMLExtension::enableL2NamespaceForDocument ( SBMLDocument doc) const
virtual

Adds the L2 Namespace to the document and enables the extension.

If the extension supports serialization to SBML L2 Annotations, this method should be overrridden, so it will be activated.

virtual unsigned int SBMLExtension::getLevel ( const std::string &  uri) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns the SBML level associated with the given URI of this package.

Parameters
urithe string of URI that represents a versions of the package
Returns
the SBML level associated with the given URI of this package.

Implemented in CompExtension.

virtual const std::string& SBMLExtension::getName ( ) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns the name of this package (e.g. "layout", "multi").

Returns
the name of package extension

Implemented in CompExtension.

int SBMLExtension::getNumOfSBasePlugins ( ) const

Returns the number of SBasePlugin objects stored in this object.

Returns
the number of SBasePlugin objects stored in this object.
unsigned int SBMLExtension::getNumOfSupportedPackageURI ( ) const

Returns the number of supported package Namespace (package versions) of this package extension.

Returns
the number of supported package Namespace (package versions) of this package extension.
virtual unsigned int SBMLExtension::getPackageVersion ( const std::string &  uri) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns the package version associated with the given URI of this package.

Parameters
urithe string of URI that represents a versions of this package
Returns
the package version associated with the given URI of this package.

Implemented in CompExtension.

virtual SBMLNamespaces* SBMLExtension::getSBMLExtensionNamespaces ( const std::string &  uri) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns an SBMLExtensionNamespaces<class SBMLExtensionType> object (e.g. SBMLExtensionNamespaces<LayoutExtension> whose alias type is LayoutPkgNamespaces) corresponding to the given uri. Null will be returned if the given uri is not defined in the corresponding package.

Parameters
urithe string of URI that represents one of versions of the package
Returns
an SBMLExtensionNamespaces<class SBMLExtensionType> object. NULL will be returned if the given uri is not defined in the corresponding package.

Implemented in CompExtension.

virtual const char* SBMLExtension::getStringFromTypeCode ( int  typeCode) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

This method takes a type code of this package and returns a string representing the code.

Implemented in CompExtension.

const std::string & SBMLExtension::getSupportedPackageURI ( unsigned int  i) const

Returns the ith URI (the supported package version)

Parameters
ithe index of the list of URI (the list of supporeted pacakge versions)
Returns
the URI of supported package version with the given index.
virtual const std::string& SBMLExtension::getURI ( unsigned int  sbmlLevel,
unsigned int  sbmlVersion,
unsigned int  pkgVersion 
) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns the uri corresponding to the given SBML level, SBML version, and package version.

Parameters
sbmlLevelthe level of SBML
sbmlVersionthe version of SBML
pkgVersionthe version of package
Returns
a string of the package URI

Implemented in CompExtension.

virtual unsigned int SBMLExtension::getVersion ( const std::string &  uri) const
pure virtual

(NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class.

Returns the SBML version associated with the given URI of this package.

Parameters
urithe string of URI that represents a versions of the package
Returns
the SBML version associated with the given URI of this package.

Implemented in CompExtension.

bool SBMLExtension::isEnabled ( ) const

Check if this package is enabled (true) or disabled (false).

Returns
true if this package is enabled, otherwise false is returned.
bool SBMLExtension::isInUse ( SBMLDocument doc) const
virtual

Determines whether this extension is being used by the given SBMLDocument.

The default implementation returns true. This means that when a document had this extension enabled, it will not be possible to convert it to L2 as we cannot make sure that the extension can be converted.

Parameters
docthe sbml document to test.
Returns
a boolean indicating whether the extension is actually being used byy the document.
bool SBMLExtension::isSupported ( const std::string &  uri) const

Returns a flag indicating, whether the given URI (package version) is supported by this package extension.

Returns
true if the given URI (package version) is supported by this package extension, otherwise false is returned.
SBMLExtension & SBMLExtension::operator= ( const SBMLExtension orig)

Assignment operator for SBMLExtension.

void SBMLExtension::removeL2Namespaces ( XMLNamespaces xmlns) const
virtual

Removes the L2 Namespaces.

Removes the L2 Namespace.

This method should be overridden by all extensions that want to serialize to an L2 annotation.

bool SBMLExtension::setEnabled ( bool  isEnabled)

enable/disable this package.

Returned value is the result of this function.

Parameters
isEnabledthe bool value: true (enabled) or false (disabled)
Returns
true if this function call succeeded, otherwise false is returned.