Inheritance diagram for SBMLExtension:

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. The SBMLExtension class provides methods for managing common attributes of package extensions (e.g., package name, package version), registration of instantiated SBasePluginCreator objects, and initialization/registration of package extensions when the library code for the package is loaded.

How to extend SBMLExtension for a package implementation

: Each package implementation must contain a class that extends SBMLExtension. For example, the class GroupsExtension serves this purpose for the SBML Level 3 Groups package extension in libSBML. The following subsections detail the basic steps involved in implementing such an extended class.

1. Define the getPackageName() method

Define a method named getPackageName() that returns the name of the package as a string. The following is an example from the implementation of the Groups package extension:

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

2. Define methods returning package version information

Define a set of methods that return the default SBML Level, SBML Version and version of the package. These methods must be named getDefaultLevel(), getDefaultVersion() and getDefaultPackageVersion(), respectively. The following are examples drawn from the Groups package implementation:

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

3. Define methods returning the package namespace URIs

Define methods that return strings representing the XML namespace URI for the package. One method should be defined for each SBML Level/Version combination for which the package can be used. For instance, if a package is only usable in SBML Level 3 Version 1, and the libSBML extension for the package implements version 1 of the package, the necessary method is getXmlnsL3V1V1().

const std::string& GroupsExtension::getXmlnsL3V1V1 ()
{
      static const std::string xmlns = "http://www.sbml.org/sbml/level3/version1/groups/version1";
      return xmlns;
}

Define other similar methods to return additional namespace URIs if the package extension implements other package versions or supports other SBML Level/Version combinations.

4. Override basic pure virtual methods

Override the following pure virtual methods on SBMLExtension:

virtual const std::string& getName() const =0. This method returns the nickname of the package (e.g., "layout", "groups").

virtual unsigned int getLevel(const std::string &uri) const =0. This method returns the SBML Level with the given URI of this package.

virtual unsigned int getVersion(const std::string &uri) const =0. This method returns the SBML Version with the given URI of this package.

virtual unsigned int getPackageVersion(const std::string &uri) const =0. This method 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 method returns the URI (namespace) of the package corresponding to the combination of the given SBML Level, SBML Version, and package version

virtual SBMLExtension* clone() const = 0. This method creates and returns a deep copy of this derived object.

As an example, the following are the versions of these methods for the Groups package:

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

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

5. Create SBMLExtensionNamespaces-related definitions

Define typedef and template instantiation code for a package-specific subclass of the SBMLExtensionNamespaces template class. 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.

Define a typedef. For example, the typedef for GroupsExtension is implemented in the file GroupsExtension.h as follows:
// GroupsPkgNamespaces is derived from the SBMLNamespaces class.
// It is used when creating a Groups package object of a class
// derived from SBase.
typedef SBMLExtensionNamespaces<GroupsExtension> GroupsPkgNamespaces;
Define a template instantiation for the typedef. For example, the template instantiation code for GroupsExtension is implemented in the file GroupsExtension.cpp as follows:
template class LIBSBML_EXTERN SBMLExtensionNamespaces<GroupsExtension>;

Here is example of how the resulting class is used. The definitions above allow a GroupsPkgNamespaces object to be used when creating a new Group object. The GroupsPkgNamespaces is handed to the constructor as an argument, as shown below:

GroupPkgNamespaces gpns(3, 1, 1); // SBML Level, Version, & pkg version.

Group g = new Group(&gpns); // Creates a Group object.

The GroupsPkgNamespaces object can also be used when creating an SBMLDocument object with the Groups package. The code fragment below shows an example of this:

GroupsPkgNamespaces gpns(3, 1, 1);
SBMLDocument* doc;
doc  = new SBMLDocument(&gnps);

6. Override the method getSBMLExtensionNamespaces()

Override the pure virtual method getSBMLExtensionNamespaces(), which returns an SBMLNamespaces derived object. For example, the method is overridden in the class GroupsExtension as follows:

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

7. Define an enumeration for the package object type codes

Define an enum type for representing the type code of the objects defined in the package extension. For example, the enumeration SBMLGroupsTypeCode_t for the Groups package is defined in GroupsExtension.h as follows:

typedef enum
{
   SBML_GROUPS_GROUP  = 500
 , SBML_GROUPS_MEMBER = 501
} SBMLGroupsTypeCode_t;

In the enumeration above, SBML_GROUPS_GROUP corresponds to the Group class (for the <group> element defined by the SBML Level 3 Groups package) and SBML_GROUPS_MEMBER corresponds to the Member class (for the <member> element defined by the Level 3 Groups package), respectively.

Similarly, SBMLLayoutTypeCode_t for the Layout package is defined in the file 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() methods. (E.g., SBML_GROUPS_GROUP is returned in Group::getTypeCode().)

Note that libSBML does not require that type codes are unique across all packages—the same type codes may be used within individual package extensions. LibSBML development must permit this because package implementations are developed by separate groups at different times; coordinating the type codes used is impractical. It does mean that callers must check two things when identifying objects: to distinguish the type codes of different packages, callers much check not only the return value of the method getTypeCode() method but also that of the method getPackageName(). Here is an example of doing that:

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:
         ....
    }
  }
  ...
}

Readers may have noticed that in the SBMLLayoutTypeCode_t and SBMLGroupsTypeCode_t enumerations above, unique values are in fact assigned to the enumeration values. This can be convenient when it can be arranged, but it is not required by libSBML.

8. Override the method getStringFromTypeCode()

Override the pure virtual method getStringFromTypeCode(), which returns a string corresponding to the given type code. Here is an example, again drawn from the implementation of the Groups package:

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

For example, the method for the Groups extension is implemented as shown below:

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];
}

9. Implement an init() method

Implement a static void init() method in the derived class. This method serves to encapsulate initialization code that creates an instance of the derived class and registration code that registers the instance with the SBMLExtensionRegistry class.

For example, the init() method for the Groups package is implemented as follows:

void GroupsExtension::init()
{
  // 1. Check if the Groups package has already been registered.
  if ( SBMLExtensionRegistry::getInstance().isRegistered(getPackageName()) )
  {
    // do nothing;
    return;
  }
  // 2. Create an SBMLExtension derived object.
  GroupsExtension gext;
  // 3. Create SBasePluginCreator-derived objects. The derived classes
  // can be instantiated by using the following template class:
  //
  //   template<class SBasePluginType> class SBasePluginCreator
  //
  // The constructor of the creator class takes two arguments:
  //
  // 1) SBaseExtensionPoint: extension point to which the plugin connects
  // 2) std::vector<std::string>: a vector that contains a list of URI
  // (package versions) supported by the plugin object.
  //
  // For example, two plugin objects are required as part of the Groups
  // implementation: one plugged into SBMLDocument and one into Model.
  // For the former, since the specification for the SBML Groups package
  // mandates that the 'required' flag is always 'false', the existing
  // SBMLDocumentPluginNotRequired class can be used as-is as part of
  // the implementation.  For Model, since the lists of supported
  // package versions (currently only SBML L3V1 Groups V1) are equal
  // in the both plugin objects, the same vector can be handed to each
  // constructor.
  std::vector<std::string> pkgURIs;
  pkgURIs.push_back(getXmlnsL3V1V1());
  SBaseExtensionPoint docExtPoint("core", SBML_DOCUMENT);
  SBaseExtensionPoint modelExtPoint("core", SBML_MODEL);
  SBasePluginCreator<GroupsSBMLDocumentPlugin, GroupsExtension> docPluginCreator(docExtPoint, pkgURIs);
  SBasePluginCreator<GroupsModelPlugin, GroupsExtension> modelPluginCreator(modelExtPoint, pkgURIs);
  // 4. Add the above objects to the SBMLExtension-derived object.
  gext.addSBasePluginCreator(&docPluginCreator);
  gext.addSBasePluginCreator(&modelPluginCreator);
  // 5. Register the SBMLExtension-derived object with the extension
  // registry, SBMLExtensionRegistry.
  int result = SBMLExtensionRegistry::getInstance().addExtension(&gext);
  if (result != LIBSBML_OPERATION_SUCCESS)
  {
    std::cerr << "[Error] GroupsExtension::init() failed." << std::endl;
  }
}

10. Instantiate a SBMLExtensionRegister object

Instantiate a global SBMLExtensionRegister object using the class derived from SBMLExtension (discussed above). Here is an example for the Groups package extension, for the object GroupsExtension. This could is placed in the GroupsExtension.cpp:

static SBMLExtensionRegister<GroupsExtension> groupsExtensionRegister;

The init() method on GroupsExtension is automatically invoked when the "register" object is instantiated. This results in initialization and registration of the package extension with libSBML.

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:

// Assume "m" below is a Model object.
LayoutModelPlugin* lmp = static_cast<LayoutModelPlugin*>(m->getPlugin("layout"));
if (lmp != NULL)
{
  unsigned int numLayouts = lmp->getNumLayouts();
  // If numLayouts is greater than zero, then the model uses Layout.
}

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.

The mechanisms for triggering this Level 2-specific behavior involves a set of virtual methods on the SBMLExtension class that must be implemented by individual package extensions. These methods are SBMLExtension::addL2Namespaces(), SBMLExtension::removeL2Namespaces(), and SBMLExtension::enableL2NamespaceForDocument().

Public Member Functions
virtual void	addL2Namespaces (XMLNamespaces *xmlns) const
	Adds the package's Level 2 namespace(s). More...

virtual SBMLExtension *	clone () const =0
	Creates and returns a deep copy of this SBMLExtension object. More...

virtual void	enableL2NamespaceForDocument (SBMLDocument *doc) const
	Called to enable the package on the SBMLDocument object. More...

virtual unsigned int	getLevel (const std::string &uri) const =0
	Returns the SBML Level associated with the given XML namespace URI. More...

virtual const std::string &	getName () const =0
	Returns the nickname of this package. More...

int	getNumOfSBasePlugins () const
	Returns the number of SBasePluginCreatorBase objects stored in this object. More...

unsigned int	getNumOfSupportedPackageURI () const
	Returns the number of supported package namespace URIs. More...

virtual unsigned int	getPackageVersion (const std::string &uri) const =0
	Returns the package version associated with the given XML namespace URI. More...

virtual SBMLNamespaces *	getSBMLExtensionNamespaces (const std::string &uri) const =0
	Returns a specialized SBMLNamespaces object corresponding to a given namespace URI. More...

virtual const char *	getStringFromTypeCode (int typeCode) const =0
	Returns a string representation of a type code. More...

const std::string &	getSupportedPackageURI (unsigned int n) const
	Returns the nth XML namespace URI. More...

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

virtual unsigned int	getVersion (const std::string &uri) const =0
	Returns the SBML Version associated with the given XML namespace URI. More...

bool	isEnabled () const
	Returns `true` if this package is enabled. More...

virtual bool	isInUse (SBMLDocument *doc) const
	Indicates whether this extension is being used by the given SBMLDocument. More...

bool	isSupported (const std::string &uri) const
	Returns `true` if the given XML namespace URI is supported by this package extension. More...

SBMLExtension &	operator= (const SBMLExtension &rhs)
	Assignment operator for SBMLExtension. More...

virtual void	removeL2Namespaces (XMLNamespaces *xmlns) const
	Removes the package's Level 2 namespace(s). More...

	SBMLExtension ()
	Constructor; creates a new SBMLExtension object. More...

	SBMLExtension (const SBMLExtension &orig)
	Copy constructor. More...

bool	setEnabled (bool isEnabled)
	Enable or disable this package. More...

virtual	~SBMLExtension ()
	Destroy this SBMLExtension object. More...

Constructor & Destructor Documentation

SBMLExtension::SBMLExtension ( )

Constructor; creates a new SBMLExtension object.

SBMLExtension::SBMLExtension ( const SBMLExtension & orig )

Copy constructor.

This creates a copy of an SBMLExtension object.

Parameters

orig	the SBMLExtension object to copy.

SBMLExtension::~SBMLExtension ( )

virtual

Destroy this SBMLExtension object.

Member Function Documentation

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.

This virtual method should be overridden by all package extensions that want to serialize to an SBML Level 2 annotation. In Level 2, the XML namespace declaration for the package is not placed on the top-level SBML document object but rather inside individual annotations. addL2Namespaces() is invoked automatically for Level 2 documents when an SBMLExtensionNamespace object is created; removeL2Namespaces() is automatically invoked by SBMLDocument to prevent the namespace(s) from being put on the top-level SBML Level 2 element (because Level 2 doesn't support namespaces there); and enableL2NamespaceForDocument() is called automatically when any SBML document (of any Level/Version) is read in.

Parameters

xmlns

an 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");

Reimplemented in LayoutExtension, and RenderExtension.

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 LayoutExtension, FbcExtension, CompExtension, MultiExtension, QualExtension, GroupsExtension, and RenderExtension.

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.

This virtual method should be overridden by all package extensions that want to serialize to an SBML Level 2 annotation. In Level 2, the XML namespace declaration for the package is not placed on the top-level SBML document object but rather inside individual annotations. addL2Namespaces() is invoked automatically for Level 2 documents when an SBMLExtensionNamespace object is created; removeL2Namespaces() is automatically invoked by SBMLDocument to prevent the namespace(s) from being put on the top-level SBML Level 2 element (because Level 2 doesn't support namespaces there); and enableL2NamespaceForDocument() is called automatically when any SBML document (of any Level/Version) is read in.

Parameters

doc

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

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

pure virtual

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

Parameters

uri	the 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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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.

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.

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

pure virtual

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

Parameters

uri	the 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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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 SBMLExtensionNamespaces. This object has the form

SBMLExtensionNamespaces<class SBMLExtensionType>

For example, this kind of object for the Layout package is

SBMLExtensionNamespaces<LayoutExtension>

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

Parameters

uri	the namespace URI that represents one of versions of the package implemented in this extension.

Returns: an SBMLExtensionNamespaces 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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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

typeCode the 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 FbcExtension, LayoutExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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

Returns the nth XML namespace URI.

Parameters

n	the 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.

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

sbmlLevel	the SBML Level.
sbmlVersion	the SBML Version.
pkgVersion	the 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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

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

pure virtual

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

Parameters

uri	the 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 LayoutExtension, FbcExtension, MultiExtension, CompExtension, QualExtension, GroupsExtension, and RenderExtension.

bool SBMLExtension::isEnabled ( ) const

Returns true if this package is enabled.

Returns: true if this package is enabled, false otherwise.

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

doc	the SBML document to test.

Returns: a boolean indicating whether the extension is actually being used by the document.

Reimplemented in LayoutExtension, and RenderExtension.

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.

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

Assignment operator for SBMLExtension.

Parameters

rhs	the object whose values are used as the basis of the assignment.

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.

This virtual method should be overridden by all package extensions that want to serialize to an SBML Level 2 annotation. In Level 2, the XML namespace declaration for the package is not placed on the top-level SBML document object but rather inside individual annotations. addL2Namespaces() is invoked automatically for Level 2 documents when an SBMLExtensionNamespace object is created; removeL2Namespaces() is automatically invoked by SBMLDocument to prevent the namespace(s) from being put on the top-level SBML Level 2 element (because Level 2 doesn't support namespaces there); and enableL2NamespaceForDocument() is called automatically when any SBML document (of any Level/Version) is read in.

Parameters

xmlns

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

bool SBMLExtension::setEnabled ( bool isEnabled )

Enable or disable this package.

Parameters

isEnabled flag indicating whether to enable (if true) or disable (false) this package extension.

Returns: true if this call succeeded; false otherwise.

Detailed Description

How to extend SBMLExtension for a package implementation

1. Define the getPackageName() method

2. Define methods returning package version information

3. Define methods returning the package namespace URIs

4. Override basic pure virtual methods

5. Create SBMLExtensionNamespaces-related definitions

6. Override the method getSBMLExtensionNamespaces()

7. Define an enumeration for the package object type codes

8. Override the method getStringFromTypeCode()

9. Implement an init() method

10. Instantiate a SBMLExtensionRegister object

Special handling for SBML Level 2

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation