This section summarizes the general scheme of SBML Level 3 package extensions in libSBML.
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 package extensions. 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. Users of the libSBML library can also choose which extensions are enabled in their software applications.
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. These are summarized further below.
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/
. Examples already exist in the libSBML distribution; the Level 3 packages Flux Balance Constraints ("fbc"), Hierarchical Model Composition ("comp"), Layout ("layout"), and Qualitative Models ("qual") are now standard with libSBML and can be found in that directory. 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 in language bindings such as Java or Python.
Summary of libSBML package extension classes
Implementing support for a given SBML Level 3 package means creating new SBML component objects (some may be extensions of existing SBML components and others may be entirely new ones), plugging those object implementations into libSBML, and finally, doing some additional chores to make everything work. Here is a summary of the support classes provided by the libSBML extension mechanism for accomplishing these tasks.
Classes to be extended
The following are the classes that typically need to be extended by creating subclasses specific to a given package extension:
- SBMLExtension: For each extension, a subclass of this class is used to implement methodality related to the package extension itself, such as the version(s) of the SBML package it supports. This class provides methods for getting common attributes of package extension, and methods for initializing and registering the package when the package code is loaded into libSBML.
- SBasePlugin: This is the base class of extensions to existing SBML objects derived from SBase. A typical package extension will derive multiple classes from SBasePlugin, each one extending a different SBML object with new features defined by the package. For a given extended SBML object, the derived class will typically be designed to contain additional attributes and/or subobjects of an SBML package, and it will provide methods for accessing the additional attributes and/or elements.
- SBMLDocumentPlugin: This is a base class that a package implementation can either use directly if it adds no attribute other than the "required" attribute to the
<sbml>
element, or else must subclass if the SBML package defines more attributes.
Classes to be instantiated
Some classes in the libSBML package extension facilities are not meant to be subclassed, but rather are designed to be instantiated.
- SBasePluginCreator: This is a template class used to create factory objects that in turn construct new instances of package plugin objects when necessary. These factory objects are invoked when, for example, libSBML encounters an SBML Level 3 package in an SBML document and needs to activate the corresponding libSBML package extension. Package implementations need to use SBasePluginCreator to create factory objects for each class derived from SBasePlugin, and then they have to register these factory objects with the SBMLExtension derived class for the package extension.
- SBMLExtensionNamespaces: This is a template class; it is itself an extension of SBMLNamespaces, and adds information specific to each package implementation. The resulting namespace object is used when creating package objects extended from SBase. Each libSBML package extension must define its own variant using the SBMLExtensionNamespaces template class.
Additional helper classes
The following additional classes do not need to be extended or instantiated; rather, they need to be called by other parts of a package implementation to accomplish bookkeeping or other tasks necessary to make the extension work in libSBML:
- SBMLExtensionRegistry: This class provides a central registry of all extensions known to libSBML. Each package extension is registered with the registry. The registry class is accessed by various classes to retrieve information about known package extensions and to create additional attributes and/or elements by factory objects of the package extensions. LibSBML cannot parse package extensions which are not registered with the registry.
- SBMLExtensionException: As its name implies, this is an exception class. It is the class of exceptions thrown when package extensions encounter exceptions.