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