public class SBMLExtension extends Object
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 SBMLExtension
class is a component of the libSBML package extension
mechanism. It is an abstract class that is extended by each package
extension implementation.
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.)
Due to the historical background of the SBML Layout package, libSBML implements special behavior for that package: it always creates a Layout plugin object for any SBML Level 2 document it reads in, regardless of whether that document actually uses Layout constructs. This is unlike the case for SBML Level 3 documents that use Layout for them, libSBML will not create a plugin object unless the document actually declares the use of the Layout package (via the usual Level 3 namespace declaration for Level 3 packages).
This has the following consequence. If an application queries for the presence of Layout in an SBML Level 2 document by testing only for the existence of the plugin object, it will always get a positive result in other words, the presence of a Layout extension object is not an indication of whether a read-in Level 2 document does or does not use SBML Layout. Instead, callers have to query explicitly for the existence of layout information. An example of such a query is the following code:
// Assume 'doc' below is anSBMLDocument
object.Model
m = doc.getModel()LayoutModelPlugin
lmp = (LayoutModelPlugin) m.getPlugin('layout') if (lmp != null) { int numLayouts = lmp.getNumLayouts() // If numLayouts is greater than zero, then the model usesLayout
. }
The special, always-available Level 2 Layout behavior was motivated by a desire to support legacy applications. In SBML Level 3, the Layout package uses the normal SBML Level 3 scheme of requiring declarations on the SBML document element. This means that upon reading a model, libSBML knows right away whether it contains layout information. In SBML Level 2, there is no top-level declaration because layout is stored as annotations in the body of the model. Detecting the presence of layout information when reading a Level 2 model requires parsing the annotations. For efficiency reasons, libSBML normally does not parse annotations automatically when reading a model. However, applications that predated the introduction of Level 3 Layout and the updated version of libSBML never had to do anything special to enable parsing layout the facilities were always available for every Level 2 model as long as libSBML was compiled with Layout support. To avoid burdening developers of legacy applications with the need to modify their software, libSBML provides backward compatibility by always preloading the Layout package extension when reading Level 2 models. The same applies to the creation of Level 2 models: with the plugin-oriented libSBML, applications normally would have to take deliberate steps to activate package code, instantiate objects, manage namespaces, and so on. LibSBML again loads the Layout package plugin automatically when creating a Level 2 model, thereby making the APIs available to legacy applications without further work on their part.
Modifier and Type | Method and Description |
---|---|
SBMLExtension |
cloneObject()
Creates and returns a deep copy of this
SBMLExtension object. |
void |
delete()
Explicitly deletes the underlying native object.
|
long |
getLevel(String uri)
Returns the SBML Level associated with the given XML namespace URI.
|
String |
getName()
Returns the nickname of this package.
|
int |
getNumOfSBasePlugins()
Returns the number of SBasePluginCreatorBase objects stored in this
object.
|
long |
getNumOfSupportedPackageURI()
Returns the number of supported package namespace URIs.
|
long |
getPackageVersion(String uri)
Returns the package version associated with the given XML namespace URI.
|
SBMLNamespaces |
getSBMLExtensionNamespaces(String uri)
Returns a specialized
SBMLNamespaces object corresponding to a given
namespace URI. |
String |
getStringFromTypeCode(int typeCode)
Returns a string representation of a type code.
|
String |
getSupportedPackageURI(long n)
Returns the nth XML namespace URI.
|
String |
getURI(long sbmlLevel,
long sbmlVersion,
long pkgVersion)
Returns the XML namespace URI for a given Level and Version.
|
long |
getVersion(String uri)
Returns the SBML Version associated with the given XML namespace URI.
|
boolean |
isEnabled()
Returns
true if this package is enabled. |
boolean |
isInUse(SBMLDocument doc)
Indicates whether this extension is being used by the given
SBMLDocument . |
boolean |
isSupported(String uri)
Returns
true if the given XML namespace URI is supported by this
package extension. |
boolean |
setEnabled(boolean isEnabled)
Enable or disable this package.
|
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the SBMLExtension.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke SBMLExtension.delete()
themselves.
public int getNumOfSBasePlugins()
SBMLExtension
-derived object.public long getNumOfSupportedPackageURI()
public boolean isSupported(String uri)
true
if the given XML namespace URI is supported by this
package extension.
true
if the given XML namespace URI (equivalent to a package
version) is supported by this package extension, false
otherwise.public String getSupportedPackageURI(long n)
n
- the index number of the namespace URI being sought.
public SBMLExtension cloneObject()
SBMLExtension
object.
SBMLExtension
object.
public String getName()
This returns the short-form name of an SBML Level 3 package
implemented by a given SBMLExtension
-derived class. Examples of
such names are 'layout', 'fbc', etc.
public String getURI(long sbmlLevel, long sbmlVersion, long pkgVersion)
sbmlLevel
- the SBML Level.sbmlVersion
- the SBML Version.pkgVersion
- the version of the package.
public long getLevel(String uri)
uri
- the string of URI that represents a version of the package.
public long getVersion(String uri)
uri
- the string of URI that represents a version of the package.
public long getPackageVersion(String uri)
uri
- the string of URI that represents a version of this package.
public String getStringFromTypeCode(int typeCode)
This method takes a numerical type code typeCode
for a component
object implemented by this package extension, and returns a string
representing that type code.
typeCode
- the type code to turn into a string.
typeCode
.
public SBMLNamespaces getSBMLExtensionNamespaces(String uri)
SBMLNamespaces
object corresponding to a given
namespace URI.
LibSBML package extensions each define a subclass of
SBMLNamespaces
.
The present method returns the appropriate object corresponding
to the given XML namespace URI in argument uri
.
uri
- the namespace URI that represents one of versions of the
package implemented in this extension.
SBMLNamespaces
object, or null
if the given uri
is not defined in the
corresponding package.
public boolean setEnabled(boolean isEnabled)
isEnabled
- flag indicating whether to enable (if true
) or
disable (false
) this package extension.
true
if this call succeeded false
otherwise.public boolean isEnabled()
true
if this package is enabled.
true
if this package is enabled, false
otherwise.public boolean isInUse(SBMLDocument doc)
SBMLDocument
.
The default implementation returns true.
This means that when a
document had this extension enabled, it will not be possible to convert
it to SBML Level 2 as we cannot make sure that the extension can be
converted.
doc
- the SBML document to test.