libSBML C# API
libSBML 5.8.0 C# API
|
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.
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)
Define the following static functions in the extended class: (examples of groups extension are shown respectively)
A string of package name (label) (The function name must be 'getPackageName'.)
string GroupsExtension::getPackageName () { static string pkgName = 'groups'; return pkgName; }
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; }
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; }
Strings that represent the other URI needed in this package (if any)
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.
Define typedef and template instantiation code for the package specific SBMLExtensionNamespaces template class
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;
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.
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; }
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: .... } } ... }
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]; }
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; } }
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 |
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.
|
virtual |
Reimplemented in libsbmlcs.CompExtension, libsbmlcs.FbcExtension, and libsbmlcs.LayoutExtension.
|
virtual |
Reimplemented in libsbmlcs.CompExtension, libsbmlcs.LayoutExtension, and libsbmlcs.FbcExtension.
|
virtual |
Reimplemented in libsbmlcs.CompExtension, libsbmlcs.FbcExtension, and libsbmlcs.LayoutExtension.
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.
doc | the sbml document to test. |
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.
doc | the sbml document to test. |
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.
doc | the sbml document to test. |
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.
doc | the sbml document to test. |
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.
uri | the string of URI that represents a versions of the 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.
doc | the sbml document to test. |
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').
int libsbmlcs.SBMLExtension.getNumOfSBasePlugins | ( | ) |
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.
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.
uri | the string of URI that represents a versions 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.
uri | the string of URI that represents one of versions of the 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.
doc | the sbml document to test. |
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.
doc | the sbml document to test. |
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)
i | the index of the list of URI (the list of supporeted pacakge versions) |
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.
sbmlLevel | the level of SBML |
sbmlVersion | the version of SBML |
pkgVersion | the version of package |
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.
uri | the string of URI that represents a versions of the package |
bool libsbmlcs.SBMLExtension.isEnabled | ( | ) |
Check if this package is enabled (true) or disabled (false).
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.
doc | the sbml document to test. |
bool libsbmlcs.SBMLExtension.isSupported | ( | string | uri | ) |
Returns a flag indicating, whether the given URI (package version) is supported by this package extension.
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.
isEnabled | the bool value: true (enabled) or false (disabled) |
|
protected |