libSBML C# API  libSBML 5.8.0 C# API
 All Classes Namespaces Files Functions Variables Properties Pages
libsbmlcs.SBMLExtension Class Reference
Inheritance diagram for libsbmlcs.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'.)

      string GroupsExtension::getPackageName () { static 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.)

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

    3. Methods returning Strings that represent the URI of packages

      string GroupsExtension::getXmlnsL3V1V1 () { static 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 string getName () =0. This function returns the name of the package (e.g., 'layout', 'groups').
    • virtual long getLevel (string uri) =0. This function returns the SBML level with the given URI of this package.
    • virtual long getVersion (string uri) =0. This function returns the SBML version with the given URI of this package.
    • virtual long getPackageVersion (string uri) =0. This function returns the package version with the given URI of this package.
    • virtual long getURI (long sbmlLevel, long sbmlVersion, long pkgVersion) =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 () = 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:

    string GroupsExtension::getName() const { return getPackageName(); }

    long GroupsExtension::getLevel(string uri) const { if (uri == getXmlnsL3V1V1()) { return 3; }

    return 0; }

    long GroupsExtension::getVersion(string uri) const { if (uri == getXmlnsL3V1V1()) { return 1; }

    return 0; }

    long GroupsExtension::getPackageVersion(string uri) const { if (uri == getXmlnsL3V1V1()) { return 1; }

    return 0; }

    string GroupsExtension::getURI(long sbmlLevel, long sbmlVersion, long pkgVersion) const { if (sbmlLevel == 3) { if (sbmlVersion == 1) { if (pkgVersion == 1) { return getXmlnsL3V1V1(); } } }

    static 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 (string uri) =0

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

    SBMLNamespaces GroupsExtension::getSBMLExtensionNamespaces(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 (SBase sb) { 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 string SBMLExtension::getStringFromTypeCode(int typeCode) const;

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

    static string SBML_GROUPS_TYPECODE_STRINGS[] = { 'Group' , 'Member' };

    string 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<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<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

void addL2Namespaces (XMLNamespaces xmlns)
 adds all L2 Extension namespaces to the namespace list. More...
 
SBMLExtension clone ()
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
virtual void Dispose ()
 
virtual SBase DowncastSBase (IntPtr cPtr, bool owner)
 
virtual SBasePlugin DowncastSBasePlugin (IntPtr cPtr, bool owner)
 
void enableL2NamespaceForDocument (SBMLDocument doc)
 Adds the L2 Namespace to the document and enables the extension. More...
 
long getCategory (long index)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
long getErrorIdOffset ()
 Determines whether this extension is being used by the given SBMLDocument. More...
 
SWIGTYPE_p_packageErrorTableEntry getErrorTable (long index)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
long getErrorTableIndex (long errorId)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
long getLevel (string uri)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
string getMessage (long index, long pkgVersion, string details)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
string getName ()
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
int getNumOfSBasePlugins ()
 Returns the number of SBasePlugin objects stored in this object. More...
 
long getNumOfSupportedPackageURI ()
 Returns the number of supported package Namespace (package versions) of this package extension. More...
 
long getPackageVersion (string uri)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
SBMLNamespaces getSBMLExtensionNamespaces (string uri)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
long getSeverity (long index, long pkgVersion)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
string getShortMessage (long index)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
string getStringFromTypeCode (int typeCode)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
string getSupportedPackageURI (long i)
 Returns the ith URI (the supported package version) More...
 
string getURI (long sbmlLevel, long sbmlVersion, long pkgVersion)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
long getVersion (string uri)
 (NOTICE) Package developers MUST OVERRIDE this pure virtual function in their derived class. More...
 
bool isEnabled ()
 Check if this package is enabled (true) or disabled (false). More...
 
bool isInUse (SBMLDocument doc)
 Determines whether this extension is being used by the given SBMLDocument. More...
 
bool isSupported (string uri)
 Returns a flag indicating, whether the given URI (package version) is supported by this package extension. More...
 
void removeL2Namespaces (XMLNamespaces xmlns)
 Removes the L2 Namespaces. More...
 
bool setEnabled (bool isEnabled)
 enable/disable this package. More...
 

Protected Attributes

bool swigCMemOwn
 

Member Function Documentation

void libsbmlcs.SBMLExtension.addL2Namespaces ( XMLNamespaces  xmlns)

adds all L2 Extension namespaces to the namespace list.

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

SBMLExtension libsbmlcs.SBMLExtension.clone ( )

(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
virtual void libsbmlcs.SBMLExtension.Dispose ( )
virtual
virtual SBase libsbmlcs.SBMLExtension.DowncastSBase ( IntPtr  cPtr,
bool  owner 
)
virtual
virtual SBasePlugin libsbmlcs.SBMLExtension.DowncastSBasePlugin ( IntPtr  cPtr,
bool  owner 
)
virtual
void libsbmlcs.SBMLExtension.enableL2NamespaceForDocument ( SBMLDocument  doc)

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.

long libsbmlcs.SBMLExtension.getCategory ( long  index)

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 bool indicating whether the extension is actually being used byy the document.
long libsbmlcs.SBMLExtension.getErrorIdOffset ( )

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 bool indicating whether the extension is actually being used byy the document.
SWIGTYPE_p_packageErrorTableEntry libsbmlcs.SBMLExtension.getErrorTable ( long  index)

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 bool indicating whether the extension is actually being used byy the document.
long libsbmlcs.SBMLExtension.getErrorTableIndex ( long  errorId)

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 bool indicating whether the extension is actually being used byy the document.
long libsbmlcs.SBMLExtension.getLevel ( string  uri)

(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.
string libsbmlcs.SBMLExtension.getMessage ( long  index,
long  pkgVersion,
string  details 
)

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 bool indicating whether the extension is actually being used byy the document.
string libsbmlcs.SBMLExtension.getName ( )

(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
int libsbmlcs.SBMLExtension.getNumOfSBasePlugins ( )

Returns the number of SBasePlugin objects stored in this object.

Returns
the number of SBasePlugin objects stored in this object.
long libsbmlcs.SBMLExtension.getNumOfSupportedPackageURI ( )

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.
long libsbmlcs.SBMLExtension.getPackageVersion ( string  uri)

(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.
SBMLNamespaces libsbmlcs.SBMLExtension.getSBMLExtensionNamespaces ( string  uri)

(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.
long libsbmlcs.SBMLExtension.getSeverity ( long  index,
long  pkgVersion 
)

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 bool indicating whether the extension is actually being used byy the document.
string libsbmlcs.SBMLExtension.getShortMessage ( long  index)

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 bool indicating whether the extension is actually being used byy the document.
string libsbmlcs.SBMLExtension.getStringFromTypeCode ( int  typeCode)

(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.

string libsbmlcs.SBMLExtension.getSupportedPackageURI ( long  i)

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.
string libsbmlcs.SBMLExtension.getURI ( long  sbmlLevel,
long  sbmlVersion,
long  pkgVersion 
)

(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
long libsbmlcs.SBMLExtension.getVersion ( string  uri)

(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.
bool libsbmlcs.SBMLExtension.isEnabled ( )

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

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

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 bool indicating whether the extension is actually being used byy the document.
bool libsbmlcs.SBMLExtension.isSupported ( string  uri)

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.
void libsbmlcs.SBMLExtension.removeL2Namespaces ( XMLNamespaces  xmlns)

Removes the L2 Namespaces.

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

bool libsbmlcs.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.

Member Data Documentation

bool libsbmlcs.SBMLExtension.swigCMemOwn
protected