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.
- SBMLExtensionRegister: This is a registration template class. It is used by package extensions to register themselves with the SBMLExtensionRegistry (see below) when libSBML starts up. An instance of this class needs to be created by each package extension and used in a call to a method on SBMLExtensionRegistry.
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:
- SBaseExtensionPoint: This class is used as part of the mechanism that connects plugin objects (implemented using SBasePlugin or SBMLDocumentPlugin) to a package extension. For instance, an implementation of an extended version of Model (e.g., LayoutModelPlugin in the Layout package) would involve the creation of an extension point using SBaseExtensionPoint and a mediator object created with SBasePluginCreator, to "plug" the extended Model object (LayoutModelPlugin) into the overall LayoutExtension object.
- 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.