Loading...
Searching...
No Matches
doc_extension_sbmldocumentplugin Class Reference

## Detailed Description

  The following subsections detail the basic steps necessary to use SBMLDocumentPlugin to extend SBMLDocument for a given package extension.

## 1. Identify the changes necessary to SBMLDocument

The specification for a SBML Level 3 package will define the changes to the SBML `<sbml>` element. Packages typically do not make any changes beyond adding an attribute named "required" (discussed below), so in most cases, the extension of SBMLDocument is very simple. However, some packages do more. For instance, the Hierarchical Model Composition package adds subobjects for lists of model definitions. SBMLDocumentPlugin supports all these cases.

## 2. Create the SBMLDocumentPlugin subclass

A package extension will only define one subclass of SBMLDocumentPlugin. Below, we describe in detail the different parts of a subclass definition.

### 2.1 Override SBasePlugin class-related methods

The derived class must override the constructor, copy constructor, assignment operator (`operator=`) and `clone()` methods from SBasePlugin.

### 2.2 Determine the necessary value of the "required" attribute

At minimum, it is necessary for a package implementation to add the "required" attribute to the SBML `<sbml>` element mandated by SBML for all Level 3 packages, and this is done using this class as a base. If the 'required' attribute is the only addition necessary for a particular SBML Level 3 package, then the subclass of SBMLDocumentPlugin for the package can have a very simple implementation. Some Level 3 packages add additional attributes or elements to `<sbml>`, and their implementations would go into the subclassed SBMLDocumentPlugin.

SBMLDocumentPlugin provides methods with default implementations that support managing the "required" attribute, so package extension code does not need to provide implementations—they only need to set the correct value for the SBML Level 3 package based on its specification. The following are the virtual methods for working with the "required" attribute. Package extensions would only need to override them in special circumstances:

- `setRequired(bool value)`: This method sets the value of the flag.

- `getRequired()`: This method gets the value of the "required" flag.

- `isSetRequired()`: This method tests if the value has been set.

- `unsetRequired()`: This method unsets the value of the "required" flag.

### 2.3 Define protected data members

An extended SBMLDocument object may need more than just the "required" attribute, depending on what is defined in the specification for the package being implemented. Data attributes on the extended `<sbml>` object 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 class or from SBase.

The additional data members must be properly initialized in the class constructor, and must be properly copied in the copy constructor and assignment operator.

### 2.4 Override virtual methods for attributes

If the extended component is defined by the SBML Level 3 package to have attributes, then the extended SBMLDocumentPlugin class definition needs to override the following internal methods that come from SBasePlugin (the base class of SBMLDocumentPlugin) 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& 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& 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 to achieve this.

### 2.5 Override 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 methods on SBasePlugin (the base class of SBMLDocumentPlugin) and provide appropriate implementations:

- `createObject(XMLInputStream& stream)`: Subclasses must override this method to create, store, and then return an SBML object corresponding to the next XMLToken in the XMLInputStream. To do this, implementations can use methods like `peek()` on XMLInputStream to test if the next object in the stream is something expected for the package. For example, LayoutModelPlugin uses `peek()` to examine the next element in the input stream, then tests that element against the Layout namespace and the element name `"listOfLayouts"` to see if it's the single subcomponent (ListOfLayouts) permitted on a Model object using the Layout package. If it is, it returns the appropriate object.

- `connectToParent(SBase *sbase)`: This creates a parent-child relationship between a given extended component and its subcomponent(s).

- `setSBMLDocument(SBMLDocument* d)`: This method should set the parent SBMLDocument object on the subcomponent object instances, so that the subcomponent instances know which SBMLDocument 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& 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* parentObject, XMLInputStream& stream)`: This function should be overridden if elements of annotation, notes, MathML content, etc., need to be directly parsed from the given XMLInputStream 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.6 Override 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 coming from SBasePlugin (the parent class of SBMLDocumentPlugin):

- `writeXMLNS(XMLOutputStream& stream)`: This method should write out any additional XML namespaces that might be needed by a package implementation.

### 2.7 Implement additional methods as needed

Extended SBMLDocumentPlugin implementations can add whatever additional utility methods are useful for their implementation.