Base class for extending SBML objects in packages.
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 SBasePlugin_t class is libSBML's base class for extensions of core SBML component objects. SBasePlugin_t defines basic virtual methods for reading/writing/checking additional attributes and/or subobjects; these methods should be overridden by subclasses to implement the necessary features of an extended SBML object.
How to extend SBasePlugin_t for a package implementation
- LibSBML package extensions can extend existing libSBML objects such as Model_t using SBasePlugin_t as a base class, to hold attributes and/or subcomponents necessary for the SBML package being implemented. Package developers must implement an SBasePlugin_t extended class for each element to be extended (e.g., Model_t, Reaction_t, and others) where additional attributes and/or top-level objects of the package extension are directly contained. The following subsections detail the basic steps necessary to use SBasePlugin_t for the implementation of a class extension.
1. Identify the SBML components that need to be extended
The specification for a SBML Level 3 package will define the attributes and subojects that make up the package constructs. Those constructs that modify existing SBML components such as Model_t, Reaction_t, etc., will be the ones that need to be extended using SBasePlugin_t.
For example, the Layout_t package makes additions to Model_t, SpeciesReference_t, and the <sbml> element (which is represented in libSBML by SBMLDocument_t). This means that the Layout_t package extension in libSBML needs to define extended versions of Model_t, SpeciesReference_t and SBMLDocument_t. Elements other than the SBML document need to be implemented using SBasePlugin_t; the document component must be implemented using SBMLDocumentPlugin_t instead.
2. Create a SBasePlugin_t subclass for each extended SBML component
A new class definition that subclasses SBasePlugin_t needs to be created for each SBML component to be extended by the package. For instance, the Layout_t package needs LayoutModelPlugin_t and LayoutSpeciesReferencePlugin_t. (As mentioned above, the Layout_t class also needs LayoutSBMLDocumentPlugin_t, but this one is implemented using SBMLDocumentPlugin_t instead of SBasePlugin_t.) Below, we describe in detail the different parts of an SBasePlugin_t subclass definition.
2.1 Define protected data members
Data attributes on each extended class in an SBML package will have one of the data types std::string, double, int, or bool. Subelements/subobjects will normally be derived from the ListOf_t class or from SBase_t.
The additional data members must be properly initialized in the class constructor, and must be properly copied in the copy constructor and assignment operator. For example, the following data member is defined in the GroupsModelPlugin_t class (in the file GroupsModelPlugin.h):
2.2 Override SBasePlugin_t class-related methods
The derived class must override the constructor, copy constructor, assignment operator (operator=) and clone() methods from SBasePlugin_t.
2.3 Override SBasePlugin_t virtual methods for attributes
If the extended component is defined by the SBML Level 3 package to have attributes, then the extended class definition needs to override the following internal methods on SBasePlugin_t and provide appropriate implementations:
addExpectedAttributes(ExpectedAttributes& attributes): This method should add the attributes that are expected to be found on this kind of extended component in an SBML file or data stream.
readAttributes(XMLAttributes_t& attributes, ExpectedAttributes& expectedAttributes): This method should read the attributes expected to be found on this kind of extended component in an SBML file or data stream.
hasRequiredAttributes(): This method should return true if all of the required attribute for this extended component are present on instance of the object.
writeAttributes(XMLOutputStream_t& stream): This method should write out the attributes of an extended component. The implementation should use the different kinds of writeAttribute methods defined by XMLOutputStream_t to achieve this.
2.4 Override SBasePlugin_t virtual methods for subcomponents
If the extended component is defined by the Level 3 package to have subcomponents (i.e., full XML elements rather than mere attributes), then the extended class definition needs to override the following internal SBasePlugin_t methods and provide appropriate implementations:
createObject(XMLInputStream_t& stream): Subclasses must override this method to create, store, and then return an SBML object corresponding to the next XMLToken_t in the XMLInputStream_t. To do this, implementations can use methods like peek() on XMLInputStream_t to test if the next object in the stream is something expected for the package. For example, LayoutModelPlugin_t uses peek() to examine the next element in the input stream, then tests that element against the Layout_t namespace and the element name "listOfLayouts" to see if it's the single subcomponent (ListOfLayouts_t) permitted on a Model_t object using the Layout_t package. If it is, it returns the appropriate object.
connectToParent(SBase_t *sbase): This creates a parent-child relationship between a given extended component and its subcomponent(s).
setSBMLDocument(SBMLDocument_t* d): This method should set the parent SBMLDocument_t object on the subcomponent object instances, so that the subcomponent instances know which SBMLDocument_t contains them.
enablePackageInternal(std::string& pkgURI, std::string& pkgPrefix, bool flag): This method should enable or disable the subcomponent based on whether a given XML namespace is active.
writeElements(XMLOutputStream_t& stream): This method must be overridden to provide an implementation that will write out the expected subcomponents/subelements to the XML output stream.
readOtherXML(SBase_t* parentObject, XMLInputStream_t& stream): This function should be overridden if elements of annotation, notes, MathML content, etc., need to be directly parsed from the given XMLInputStream_t object.
hasRequiredElements(): This method should return true if a given object contains all the required subcomponents defined by the specification for that SBML Level 3 package.
2.5 Override SBasePlugin_t virtual methods for XML namespaces
If the package needs to add additional xmlns attributes to declare additional XML namespace URIs, the extended class should override the following method:
writeXMLNS(XMLOutputStream_t& stream): This method should write out any additional XML namespaces that might be needed by a package implementation.
2.6 Implement additional methods as needed
Extended component implementations can add whatever additional utility methods are useful for their implementation.
|
| SBasePlugin_t * | SBasePlugin_clone (SBasePlugin_t *plugin) |
| | Creates a deep copy of the given SBasePlugin_t structure. More...
|
| |
| int | SBasePlugin_connectToParent (SBasePlugin_t *plugin, SBase_t *sbase) |
| | Sets the parent SBML structure of this plugin structure to this structure and child elements (if any). More...
|
| |
| SBase_t * | SBasePlugin_createObject (SBasePlugin_t *plugin, XMLInputStream_t *stream) |
| | Subclasses must override this method to create, store, and then return an SBML structure corresponding to the next XMLToken_t in the XMLInputStream_t if they have their specific elements. More...
|
| |
| int | SBasePlugin_free (SBasePlugin_t *plugin) |
| | Frees the given SBasePlugin_t structure. More...
|
| |
| unsigned int | SBasePlugin_getLevel (SBasePlugin_t *plugin) |
| | Returns the SBML level of the package extension of this plugin structure. More...
|
| |
| const char * | SBasePlugin_getPackageName (SBasePlugin_t *plugin) |
| | Returns the package name of the given plugin structure. More...
|
| |
| unsigned int | SBasePlugin_getPackageVersion (SBasePlugin_t *plugin) |
| | Returns the package version of the package extension of this plugin structure. More...
|
| |
| SBase_t * | SBasePlugin_getParentSBMLObject (SBasePlugin_t *plugin) |
| | Returns the parent SBase_t structure to which this plugin structure is connected. More...
|
| |
| const char * | SBasePlugin_getPrefix (SBasePlugin_t *plugin) |
| | Returns the prefix of the given plugin structure. More...
|
| |
| SBMLDocument_t * | SBasePlugin_getSBMLDocument (SBasePlugin_t *plugin) |
| | Returns the parent SBMLDocument_t of this plugin structure. More...
|
| |
| const char * | SBasePlugin_getURI (SBasePlugin_t *plugin) |
| | Returns the XML namespace (URI) of the package extension of the given plugin structure. More...
|
| |
| unsigned int | SBasePlugin_getVersion (SBasePlugin_t *plugin) |
| | Returns the SBML version of the package extension of this plugin structure. More...
|
| |
| int | SBasePlugin_hasRequiredAttributes (SBasePlugin_t *plugin) |
| | Checks if the plugin structure has all the required attributes. More...
|
| |
| int | SBasePlugin_hasRequiredElements (SBasePlugin_t *plugin) |
| | Checks if the plugin structure has all the required elements. More...
|
| |
| int | SBasePlugin_readOtherXML (SBasePlugin_t *plugin, SBase_t *parentObject, XMLInputStream_t *stream) |
| | Subclasses should override this method to read (and store) XHTML, MathML, etc. More...
|
| |
| int | SBasePlugin_setSBMLDocument (SBasePlugin_t *plugin, SBMLDocument_t *d) |
| | Sets the parent SBMLDocument_t of th plugin structure. More...
|
| |
| int | SBasePlugin_writeAttributes (SBasePlugin_t *plugin, XMLOutputStream_t *stream) |
| | Subclasses must override this method to write their XML attributes to the XMLOutputStream_t if they have their specific attributes. More...
|
| |
| int | SBasePlugin_writeElements (SBasePlugin_t *plugin, XMLInputStream_t *stream) |
| | Subclasses must override this method to write out their contained SBML structures as XML elements if they have their specific elements. More...
|
| |
| int | SBasePlugin_writeXMLNS (SBasePlugin_t *plugin, XMLOutputStream_t *stream) |
| | Subclasses should override this method to write required xmlns attributes to the XMLOutputStream_t (if any). More...
|
| |
| SBasePluginCreatorBase_t * | SBasePluginCreator_clone (SBasePluginCreatorBase_t *creator) |
| | Creates a deep copy of the given SBasePluginCreatorBase_t structure. More...
|
| |
| SBasePlugin_t * | SBasePluginCreator_createPlugin (SBasePluginCreatorBase_t *creator, const char *uri, const char *prefix, const XMLNamespaces_t *xmlns) |
| | Creates an SBasePlugin_t structure with the given uri and the prefix of the target package extension. More...
|
| |
| int | SBasePluginCreator_free (SBasePluginCreatorBase_t *creator) |
| | Frees the given SBasePluginCreatorBase_t structure. More...
|
| |
| unsigned int | SBasePluginCreator_getNumOfSupportedPackageURI (SBasePluginCreatorBase_t *creator) |
| | Returns the number of supported packages by the given creator structure. More...
|
| |
| char * | SBasePluginCreator_getSupportedPackageURI (SBasePluginCreatorBase_t *creator, unsigned int index) |
| | Returns a copy of the package uri with the specified index. More...
|
| |
| const SBaseExtensionPoint_t * | SBasePluginCreator_getTargetExtensionPoint (SBasePluginCreatorBase_t *creator) |
| | Returns the SBaseExtensionPoint_t tied to this creator structure. More...
|
| |
| const char * | SBasePluginCreator_getTargetPackageName (SBasePluginCreatorBase_t *creator) |
| | Returns the target package name of the creator structure. More...
|
| |
| int | SBasePluginCreator_getTargetSBMLTypeCode (SBasePluginCreatorBase_t *creator) |
| | Returns the SBMLTypeCode_t tied to the creator structure. More...
|
| |
| int | SBasePluginCreator_isSupported (SBasePluginCreatorBase_t *creator, const char *uri) |
| | Returns 1 (true) if a package with the given namespace is supported. More...
|
| |
