libSBML Perl API  5.20.2
Loading...
Searching...
No Matches
SBMLExtension Class Referenceabstract
Inheritance diagram for SBMLExtension:
[legend]

Detailed Description

Base class for SBML Level 3 package plug-ins.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBMLExtension class is a component of the libSBML package extension mechanism. It is an abstract class that is extended by each package extension implementation.

Basic principles of SBML package extensions in libSBML

SBML Level 3's package structure permits modular extensions to the core SBML format. In libSBML, support for SBML Level 3 packages is provided through optional package extensions that can be plugged into libSBML at the time it is built/compiled. Users of libSBML can thus choose which extensions are enabled in their software applications.

LibSBML defines a number of classes that developers of package extensions can use to implement support for an SBML Level 3 package. These classes make it easier to extend libSBML objects with new attributes and/or subobjects as needed by a particular Level 3 package. Three overall categories of classes make up libSBML's facilities for implementing package extensions. There are (1) classes that serve as base classes meant to be subclassed, (2) template classes meant to be instantiated rather than subclassed, and (3) support classes that provide utility features. A given package implementation for libSBML will take the form of code using these and other libSBML classes, placed in a subdirectory of src/sbml/packages/.

The basic libSBML distribution includes a number of package extensions implementing support for officially-endorsed SBML Level 3 packages; among these are Flux Balance Constraints ("fbc"), Hierarchical Model Composition ("comp"), Layout ("layout"), and Qualitative Models ("qual"). They can serve as working examples for developers working to implement other packages.

Extensions in libSBML can currently only be implemented in C++ or C; there is no mechanism to implement them first in languages such as Java or Python. However, once implemented in C++ or C, language interfaces can be generated semi-automatically using the framework in place in libSBML. (The approach is based on using SWIG and facilities in libSBML's build system.)

Special handling for SBML LevelĀ 2

Due to the historical background of the SBML Layout package, libSBML implements special behavior for that package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. This is unlike the case for SBML Level 3 documents that use Layout; for them, libSBML will not create a plugin object unless the document actually declares the use of the Layout package (via the usual Level 3 namespace declaration for Level 3 packages).

This has the following consequence. If an application queries for the presence of Layout in an SBML Level 2 document by testing only for the existence of the plugin object, it will always get a positive result; in other words, the presence of a Layout extension object is not an indication of whether a read-in Level 2 document does or does not use SBML Layout. Instead, callers have to query explicitly for the existence of layout information. An example of such a query is the following code:

The special, always-available Level 2 Layout behavior was motivated by a desire to support legacy applications. In SBML Level 3, the Layout package uses the normal SBML Level 3 scheme of requiring declarations on the SBML document element. This means that upon reading a model, libSBML knows right away whether it contains layout information. In SBML Level 2, there is no top-level declaration because layout is stored as annotations in the body of the model. Detecting the presence of layout information when reading a Level 2 model requires parsing the annotations. For efficiency reasons, libSBML normally does not parse annotations automatically when reading a model. However, applications that predated the introduction of Level 3 Layout and the updated version of libSBML never had to do anything special to enable parsing layout; the facilities were always available for every Level 2 model as long as libSBML was compiled with Layout support. To avoid burdening developers of legacy applications with the need to modify their software, libSBML provides backward compatibility by always preloading the Layout package extension when reading Level 2 models. The same applies to the creation of Level 2 models: with the plugin-oriented libSBML, applications normally would have to take deliberate steps to activate package code, instantiate objects, manage namespaces, and so on. LibSBML again loads the Layout package plugin automatically when creating a Level 2 model, thereby making the APIs available to legacy applications without further work on their part.

Public Member Functions

virtual void addL2Namespaces (XMLNamespaces *xmlns) const
 Adds the package's Level 2 namespace(s).
 
virtual SBMLExtensionclone () const =0
 Creates and returns a deep copy of this SBMLExtension object.
 
virtual void enableL2NamespaceForDocument (SBMLDocument *doc) const
 Called to enable the package on the SBMLDocument object.
 
virtual unsigned int getLevel (const std::string &uri) const =0
 Returns the SBML Level associated with the given XML namespace URI.
 
virtual const std::string & getName () const =0
 Returns the nickname of this package.
 
int getNumOfSBasePlugins () const
 Returns the number of SBasePluginCreatorBase objects stored in this object.
 
unsigned int getNumOfSupportedPackageURI () const
 Returns the number of supported package namespace URIs.
 
virtual unsigned int getPackageVersion (const std::string &uri) const =0
 Returns the package version associated with the given XML namespace URI.
 
virtual SBMLNamespacesgetSBMLExtensionNamespaces (const std::string &uri) const =0
 Returns a specialized SBMLNamespaces object corresponding to a given namespace URI.
 
virtual const char * getStringFromTypeCode (int typeCode) const =0
 Returns a string representation of a type code.
 
const std::string & getSupportedPackageURI (unsigned int n) const
 Returns the nth XML namespace URI.
 
virtual const std::string & getURI (unsigned int sbmlLevel, unsigned int sbmlVersion, unsigned int pkgVersion) const =0
 Returns the XML namespace URI for a given Level and Version.
 
virtual unsigned int getVersion (const std::string &uri) const =0
 Returns the SBML Version associated with the given XML namespace URI.
 
bool isEnabled () const
 Returns true if this package is enabled.
 
virtual bool isInUse (SBMLDocument *doc) const
 Indicates whether this extension is being used by the given SBMLDocument.
 
bool isSupported (const std::string &uri) const
 Returns true if the given XML namespace URI is supported by this package extension.
 
SBMLExtensionoperator= (const SBMLExtension &rhs)
 Assignment operator for SBMLExtension.
 
virtual void removeL2Namespaces (XMLNamespaces *xmlns) const
 Removes the package's Level 2 namespace(s).
 
 SBMLExtension ()
 Constructor; creates a new SBMLExtension object.
 
 SBMLExtension (const SBMLExtension &orig)
 Copy constructor.
 
bool setEnabled (bool isEnabled)
 Enable or disable this package.
 
virtual ~SBMLExtension ()
 Destroy this SBMLExtension object.
 

Constructor & Destructor Documentation

◆ SBMLExtension() [1/2]

SBMLExtension::SBMLExtension ( )

Constructor; creates a new SBMLExtension object.

◆ SBMLExtension() [2/2]

SBMLExtension::SBMLExtension ( const SBMLExtension orig)

Copy constructor.

This creates a copy of an SBMLExtension object.

Parameters
origthe SBMLExtension object to copy.

◆ ~SBMLExtension()

SBMLExtension::~SBMLExtension ( )
virtual

Destroy this SBMLExtension object.

Member Function Documentation

◆ addL2Namespaces()

void SBMLExtension::addL2Namespaces ( XMLNamespaces xmlns) const
virtual

Adds the package's Level 2 namespace(s).

This method is related to special facilities designed to support legacy behaviors surrounding SBML Level 2 models. Due to the historical background of the SBML Layout package, libSBML implements special behavior for that package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. Since Level 2 does not use namespaces on the top level of the SBML document object, libSBML simply keys off the fact that the model is a Level 2 model. To allow the extensions for the Layout and Render (and possibly other) packages to support this behavior, the SBMLExtension class contains special methods to allow packages to hook themselves into the Level 2 parsing apparatus when necessary.
Parameters
xmlnsan XMLNamespaces object that will be used for the annotation. Implementation should override this method with something that adds the package's namespace(s) to the set of namespaces in xmlns. For instance, here is the code from the Layout package extension:
if (!xmlns->containsUri( LayoutExtension::getXmlnsL2()))
xmlns->add(LayoutExtension::getXmlnsL2(), "layout");
static const std::string & getXmlnsL2()
Returns the XML namespace URI of the SBML Level 2 version of the package implemented by this libSBML...
Definition LayoutExtension.cpp:109

Reimplemented in LayoutExtension, and RenderExtension.

◆ clone()

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

Creates and returns a deep copy of this SBMLExtension object.

Returns
a (deep) copy of this SBMLExtension object.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ enableL2NamespaceForDocument()

void SBMLExtension::enableL2NamespaceForDocument ( SBMLDocument doc) const
virtual

Called to enable the package on the SBMLDocument object.

This method is related to special facilities designed to support legacy behaviors surrounding SBML Level 2 models. Due to the historical background of the SBML Layout package, libSBML implements special behavior for that package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. Since Level 2 does not use namespaces on the top level of the SBML document object, libSBML simply keys off the fact that the model is a Level 2 model. To allow the extensions for the Layout and Render (and possibly other) packages to support this behavior, the SBMLExtension class contains special methods to allow packages to hook themselves into the Level 2 parsing apparatus when necessary.
Parameters
docthe SBMLDocument object for the model. Implementations should override this method with something that enables the package based on the package's namespace(s). For example, here is the code from the Layout package extension:
if (doc->getLevel() == 2)
doc->enablePackage(LayoutExtension::getXmlnsL2(), "layout", true);

Reimplemented in LayoutExtension, and RenderExtension.

◆ getLevel()

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

Returns the SBML Level associated with the given XML namespace URI.

Parameters
urithe string of URI that represents a version of the package.
Returns
the SBML Level associated with the given URI of this package.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getName()

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

Returns the nickname of this package.

This returns the short-form name of an SBML Level 3 package implemented by a given SBMLExtension-derived class. Examples of such names are "layout", "fbc", etc.

Returns
a string, the nickname of SBML package.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getNumOfSBasePlugins()

int SBMLExtension::getNumOfSBasePlugins ( ) const

Returns the number of SBasePluginCreatorBase objects stored in this object.

Returns
the total number of SBasePluginCreatorBase objects stored in this SBMLExtension-derived object.

◆ getNumOfSupportedPackageURI()

unsigned int SBMLExtension::getNumOfSupportedPackageURI ( ) const

Returns the number of supported package namespace URIs.

Returns
the number of supported package XML namespace URIs of this package extension.

◆ getPackageVersion()

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

Returns the package version associated with the given XML namespace URI.

Parameters
urithe string of URI that represents a version of this package.
Returns
the package version associated with the given URI of this package.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getSBMLExtensionNamespaces()

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

Returns a specialized SBMLNamespaces object corresponding to a given namespace URI.

LibSBML package extensions each define a subclass of SBMLNamespaces

The present method returns the appropriate object corresponding to the given XML namespace URI in argument uri.

Parameters
urithe namespace URI that represents one of versions of the package implemented in this extension.
Returns
an SBMLNamespaces

object, or NULL if the given uri is not defined in the corresponding package.

Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getStringFromTypeCode()

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

Returns a string representation of a type code.

This method takes a numerical type code typeCode for a component object implemented by this package extension, and returns a string representing that type code.

Parameters
typeCodethe type code to turn into a string.
Returns
the string representation of typeCode.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getSupportedPackageURI()

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

Returns the nth XML namespace URI.

Parameters
nthe index number of the namespace URI being sought.
Returns
a string representing the XML namespace URI understood to be supported by this package. An empty string will be returned if there is no nth URI.

◆ getURI()

virtual const std::string & SBMLExtension::getURI ( unsigned int  sbmlLevel,
unsigned int  sbmlVersion,
unsigned int  pkgVersion 
) const
pure virtual

Returns the XML namespace URI for a given Level and Version.

Parameters
sbmlLevelthe SBML Level.
sbmlVersionthe SBML Version.
pkgVersionthe version of the package.
Returns
a string, the XML namespace URI for the package for the given SBML Level, SBML Version, and package version.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ getVersion()

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

Returns the SBML Version associated with the given XML namespace URI.

Parameters
urithe string of URI that represents a version of the package.
Returns
the SBML Version associated with the given URI of this package.
Note
This is a method that package extension implementations must override. See the libSBML documentation on extending libSBML to support SBML packages for more information on this topic.

Implemented in CompExtension, DistribExtension, FbcExtension, GroupsExtension, LayoutExtension, MultiExtension, QualExtension, RenderExtension, and SpatialExtension.

◆ isEnabled()

bool SBMLExtension::isEnabled ( ) const

Returns true if this package is enabled.

Returns
true if this package is enabled, false otherwise.

◆ isInUse()

bool SBMLExtension::isInUse ( SBMLDocument doc) const
virtual

Indicates 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 SBML Level 2 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 by the document.

Reimplemented in LayoutExtension, and RenderExtension.

◆ isSupported()

bool SBMLExtension::isSupported ( const std::string &  uri) const

Returns true if the given XML namespace URI is supported by this package extension.

Returns
true if the given XML namespace URI (equivalent to a package version) is supported by this package extension, false otherwise.

◆ operator=()

SBMLExtension & SBMLExtension::operator= ( const SBMLExtension rhs)

Assignment operator for SBMLExtension.

Parameters
rhsthe object whose values are used as the basis of the assignment.

◆ removeL2Namespaces()

void SBMLExtension::removeL2Namespaces ( XMLNamespaces xmlns) const
virtual

Removes the package's Level 2 namespace(s).

This method is related to special facilities designed to support legacy behaviors surrounding SBML Level 2 models. Due to the historical background of the SBML Layout package, libSBML implements special behavior for that package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. Since Level 2 does not use namespaces on the top level of the SBML document object, libSBML simply keys off the fact that the model is a Level 2 model. To allow the extensions for the Layout and Render (and possibly other) packages to support this behavior, the SBMLExtension class contains special methods to allow packages to hook themselves into the Level 2 parsing apparatus when necessary.
Parameters
xmlnsan XMLNamespaces object that will be used for the annotation. Implementations should override this method with something that removes the package's namespace(s) from the set of namespaces in xmlns. For instance, here is the code from the Layout package extension:
for (int n = 0; n < xmlns->getNumNamespaces(); n++)
{
if (xmlns->getURI(n) == LayoutExtension::getXmlnsL2())
xmlns->remove(n);
}

Reimplemented in LayoutExtension, and RenderExtension.

◆ setEnabled()

bool SBMLExtension::setEnabled ( bool  isEnabled)

Enable or disable this package.

Parameters
isEnabledflag indicating whether to enable (if true) or disable (false) this package extension.
Returns
true if this call succeeded; false otherwise.