public class SBMLDocument extends SBase
LibSBML uses the class SBMLDocument
as a top-level
container for storing SBML content and data associated with it (such as
warnings and error messages). The two primary means of reading an SBML
model, SBMLReader.readSBML(String filename)
and
SBMLReader.readSBMLFromString(String xml)
, both return an SBMLDocument
object. From there, callers can inquire about any errors encountered
(e.g., using SBMLDocument.getNumErrors()
), access the Model
object, and
perform other actions such as consistency-checking and model
translation.
When creating fresh models programmatically, the starting point is
typically the creation of an SBMLDocument
object instance. The
SBMLDocument
constructor accepts arguments for the SBML Level and
Version of the model to be created. After creating the SBMLDocument
object, calling programs then typically call SBMLDocument.createModel()
almost immediately, and then proceed to call the methods on the Model
object to fill out the model's contents.
SBMLDocument
corresponds roughly to the class Sbml defined in the
SBML Level 2 specification and SBML in the Level 3
specification. It does not have a direct correspondence in SBML
Level 1. (However, to make matters simpler for applications,
libSBML creates an SBMLDocument
no matter whether the model is
Level 1, Level 2 or Level 3.) In its barest form, when written out in
XML format for (e.g.) SBML Level 2 Version 4, the corresponding
structure is the following:
<sbml xmlns='http://www.sbml.org/sbml/level2/version4' level='2' version='4'> ... </sbml>
SBMLDocument
is derived from SBase
, and therefore contains the usual SBase
attributes (in SBML Level 2 and Level 3) of 'metaid' and 'sboTerm', as
well as the subelements 'notes' and 'annotation'. It also contains the
attributes 'level' and 'version' indicating the Level and Version of the
SBML data structure. These can be accessed using the methods defined by
the SBase
class for that purpose.
One of the most important features of libSBML is its ability to perform
SBML validation to ensure that a model adheres to the SBML specification
for whatever Level+Version combination the model uses. SBMLDocument
provides the methods for running consistency-checking and validation
rules on the SBML content.
First, a brief explanation of the rationale is in order. In libSBML versions up to and including the version 3.3.x series, the individual methods for creating and setting attributes and other components were quite lenient, and allowed a caller to compose SBML entities that might not, in the end, represent valid SBML. This allowed applications the freedom to do things such as save incomplete models (which is useful when models are being developed over long periods of time). In the version 4.x series, libSBML is somewhat stricter, but still permits structures to be created independently and the results to be combined in a separate step. In all these cases, it means that a separate validation step is necessary when a calling program finally wants to finish a complete SBML document.
The primary interface to this validation facility is SBMLDocument
's
SBMLDocument.checkInternalConsistency()
and
SBMLDocument.checkConsistency()
. The former verifies the basic
internal consistency and syntax of an SBML document, and the latter
implements more elaborate validation rules (both those defined by the
SBML specifications, as well as additional rules offered by libSBML).
The checks performed by SBMLDocument.checkInternalConsistency()
are
hardwired and cannot be changed by calling programs, but the validation
performed by SBMLDocument.checkConsistency()
is under program control
using the method SBMLDocument.setConsistencyChecks(int categ, boolean
onoff)
. Applications can selectively disable specific kinds of checks
that they may not be interested by calling
SBMLDocument.setConsistencyChecks(int categ, boolean onoff)
with
appropriate parameters.
These methods have slightly different relevance depending on whether a model is created programmaticaly from scratch, or whether it is read in from a file or data stream. The following list summarizes the possible scenarios.
Scenario 1: Creating a model from scratch. Before writing out the model,
SBMLDocument.checkInternalConsistency()
, then inquire about
the results by calling SBMLDocument.getNumErrors()
SBMLDocument.setConsistencyChecks(int categ, boolean
onoff)
to configure
which checks will be performed by SBMLDocument.checkConsistency()
SBMLDocument.checkConsistency()
, then inquire about the results by
calling SBMLDocument.getNumErrors()
Scenario 2: Reading a model from a file or data stream. After reading the model,
SBMLDocument.getNumErrors()
SBMLDocument.setConsistencyChecks(int categ, boolean
onoff)
to configure
which checks are performed by SBMLDocument.checkConsistency()
SBMLDocument.checkConsistency()
, then inquire about the results
by calling SBMLDocument.getNumErrors()
LibSBML provides facilities for limited translation of SBML between
Levels and Versions of the SBML specifications. The method for doing is
is SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
. In
general, models can be converted upward without difficulty (e.g., from
SBML Level 1 to Level 2, or from an earlier Version of
Level 2 to the latest Version of Level 2). Sometimes models
can be translated downward as well, if they do not use constructs
specific to more advanced Levels of SBML.
Calling SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
will not necessarily lead
to a successful conversion. The method will return a boolean value
to indicate success or failure. Callers must check the error log (see
next section) attached to the SBMLDocument
object after calling
SBMLDocument.setLevelAndVersion(long lev, long ver)
in order to assess whether any
problems arose.
If an application is interested in translating to a lower Level and/or Version of SBML within a Level, the following methods allow for prior assessment of whether there is sufficient compatibility to make a translation possible:
SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
, and
SBMLDocument.checkL3v1Compatibility()
.
Some changes between Versions of SBML Level 2 may lead to unexpected behaviors when attempting conversions in either direction. For example, SBML Level 2 Version 4 relaxed the requirement for consistency in units of measurement between expressions annd quantities in a model. As a result, a model written in Version 4, if converted to Version 3 with no other changes, may fail validation as a Version 3 model because Version 3 imposed stricter requirements on unit consistency.
Other changes between SBML Level 2 and Level 3 make downward conversions challenging. In some cases, it means that a model converted to Level 2 from Level 3 will contain attributes that were not explicitly given in the Level 3 model, because in Level 2 these attributes may have been optional or have default values.
Upon reading a model, SBMLDocument
logs any problems encountered while
reading the model from the file or data stream. The log contains
objects that record diagnostic information about any notable issues that
arose. Whether the problems are warnings or errors, they are both
reported through a single common interface involving the object class
SBMLError
.
The methods SBMLDocument.getNumErrors()
, SBMLDocument.getError(long n)
and
SBMLDocument.printErrors()
allow callers to interact with the warnings
or errors logged. Alternatively, callers may retrieve the entire log as
an SBMLErrorLog
object using the method SBMLDocument.getErrorLog()
.
The SBMLErrorLog
object provides some alternative methods for
interacting with the set of errors and warnings. In either case,
applications typically should first call SBMLDocument.getNumErrors()
to
find out if any issues have been logged after specific libSBML
operations such as the ones discussed in the sections above. If they
have, then an application will should proceed to inspect the individual
reports using either the direct interfaces on SBMLDocument
or using the
methods on the SBMLErrorLog
object.
Constructor and Description |
---|
SBMLDocument()
Creates a new
SBMLDocument , optionally with given values for the SBML
Level and Version. |
SBMLDocument(long level)
Creates a new
SBMLDocument , optionally with given values for the SBML
Level and Version. |
SBMLDocument(long level,
long version)
Creates a new
SBMLDocument , optionally with given values for the SBML
Level and Version. |
SBMLDocument(SBMLDocument orig)
Copy constructor creates a copy of this
SBMLDocument . |
SBMLDocument(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
long |
checkConsistency()
Performs consistency checking and validation on this SBML document.
|
long |
checkInternalConsistency()
Performs consistency checking on libSBML's internal representation of
an SBML
Model . |
long |
checkL1Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 1 and can be converted
to Level 1.
|
long |
checkL2v1Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 2 Version 1 and can
be converted to Level 2 Version 1.
|
long |
checkL2v2Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 2 Version 2 and can
be converted to Level 2 Version 2.
|
long |
checkL2v3Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 2 Version 3 and can
be converted to Level 2 Version 3.
|
long |
checkL2v4Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 2 Version 4 and can
be converted to Level 2 Version 4.
|
long |
checkL3v1Compatibility()
Performs a set of consistency checks on the document to establish
whether it is compatible with SBML Level 3 Version 1 and can
be converted to Level 3 Version 1.
|
SBMLDocument |
cloneObject()
Creates and returns a deep copy of this
SBMLDocument . |
Model |
createModel()
Creates a new
Model inside this SBMLDocument , and returns a pointer to
it. |
Model |
createModel(java.lang.String sid)
Creates a new
Model inside this SBMLDocument , and returns a pointer to
it. |
void |
delete()
Explicitly deletes the underlying native object.
|
int |
enableDefaultNS(java.lang.String arg0,
boolean flag)
Set/unset default namespace to each top-level element defined in the
given package extension.
|
boolean |
expandFunctionDefinitions()
Removes
FunctionDefinition constructs from the document and expands
any instances of their use within <math> elements. |
boolean |
expandInitialAssignments()
Removes
InitialAssignment constructs from the document and
replaces them with appropriate values. |
static long |
getDefaultLevel()
The default SBML Level of new
SBMLDocument objects. |
static long |
getDefaultVersion()
The default Version of new
SBMLDocument objects. |
SBase |
getElementByMetaId(java.lang.String metaid)
Returns the first child element it can find with the given
metaid , or
itself if it has the given metaid , or null if no such object is
found. |
SBase |
getElementBySId(java.lang.String id)
Returns the first child element found that has the given
id in the
model-wide SId namespace, or null if no such object is found. |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
SBMLDocument ,
is always 'sbml'. |
SBMLError |
getError(long n)
Returns the nth error or warning encountered during parsing,
consistency checking, or attempted translation of this model.
|
SBMLErrorLog |
getErrorLog()
Returns the list of errors or warnings logged during parsing,
consistency checking, or attempted translation of this model.
|
java.lang.String |
getLocationURI()
Get the location of this
SBMLDocument . |
Model |
getModel()
Returns the
Model object stored in this SBMLDocument . |
XMLNamespaces |
getNamespaces()
Returns a list of XML Namespaces associated with the XML content
of this SBML document.
|
long |
getNumErrors()
Returns the number of errors or warnings encountered during parsing,
consistency checking, or attempted translation of this model.
|
long |
getNumErrors(long severity)
Returns the number of errors or warnings encountered with the given
severity during parsing,
consistency checking, or attempted translation of this model.
|
boolean |
getPackageRequired(java.lang.String arg0)
Returns the
required attribute of the given package
extension. |
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
boolean |
isDisabledIgnoredPackage(java.lang.String pkgURI)
Returns
true if the given package extension is one of an ignored
packages that has been disabled, otherwise returns false. |
boolean |
isEnabledDefaultNS(java.lang.String arg0)
Returns
true if a default namespace is added to each top-level
element defined in the given package extension, otherwise returns
false. |
boolean |
isIgnoredPackage(java.lang.String pkgURI)
Returns
true if the given package extension is one of an ignored
packages, otherwise returns false. |
boolean |
isSetPackageRequired(java.lang.String arg0)
Returns
true if the required attribute of the given package extension
is defined, otherwise returns false. |
void |
printErrors()
Prints all the errors or warnings encountered trying to parse,
check, or translate this SBML document.
|
void |
printErrors(OStream stream)
Prints all the errors or warnings encountered trying to parse,
check, or translate this SBML document.
|
void |
setConsistencyChecks(int category,
boolean apply)
Controls the consistency checks that are performed when
SBMLDocument.checkConsistency() is called. |
void |
setConsistencyChecksForConversion(int category,
boolean apply)
Controls the consistency checks that are performed when
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict) is called. |
boolean |
setLevelAndVersion(long level,
long version)
Sets the SBML Level and Version of this
SBMLDocument instance,
attempting to convert the model as needed. |
boolean |
setLevelAndVersion(long level,
long version,
boolean strict)
Sets the SBML Level and Version of this
SBMLDocument instance,
attempting to convert the model as needed. |
boolean |
setLevelAndVersion(long level,
long version,
boolean strict,
boolean ignorePackages)
Sets the SBML Level and Version of this
SBMLDocument instance,
attempting to convert the model as needed. |
void |
setLocationURI(java.lang.String uri)
Sets the location of this
SBMLDocument . |
int |
setModel(Model m)
|
int |
setPackageRequired(java.lang.String arg0,
boolean flag)
Sets the
required attribute value of the given package
extension. |
long |
validateSBML()
Performs consistency checking and validation on this SBML document.
|
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModelHistory, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm
public SBMLDocument() throws SBMLConstructorException
SBMLDocument
, optionally with given values for the SBML
Level and Version.
If both the SBML Level and Version attributes are not
specified, the SBML document is treated as having the latest Level and
Version of SBML as determined by SBMLDocument.getDefaultLevel()
and
SBMLDocument.getDefaultVersion()
however, the SBMLDocument
object is otherwise left blank. In particular, the blank SBMLDocument
object has no associated XML attributes, including (but not limited
to) an XML namespace declaration. The XML namespace declaration is
not added until the model is written out, or the method
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
is called. This may be important to keep in mind
if an application needs to add additional XML namespace declarations
on the <sbml>
element. Application writers should
either provide values for level
and version
on the call to this
constructor, or else call
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
shortly after creating the SBMLDocument
object.
level
- an integer for the SBML Level
version
- an integer for the Version within the SBML Level
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
,
SBMLDocument.getDefaultLevel()
,
SBMLDocument.getDefaultVersion()
public SBMLDocument(long level) throws SBMLConstructorException
SBMLDocument
, optionally with given values for the SBML
Level and Version.
If both the SBML Level and Version attributes are not
specified, the SBML document is treated as having the latest Level and
Version of SBML as determined by SBMLDocument.getDefaultLevel()
and
SBMLDocument.getDefaultVersion()
however, the SBMLDocument
object is otherwise left blank. In particular, the blank SBMLDocument
object has no associated XML attributes, including (but not limited
to) an XML namespace declaration. The XML namespace declaration is
not added until the model is written out, or the method
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
is called. This may be important to keep in mind
if an application needs to add additional XML namespace declarations
on the <sbml>
element. Application writers should
either provide values for level
and version
on the call to this
constructor, or else call
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
shortly after creating the SBMLDocument
object.
level
- an integer for the SBML Level
version
- an integer for the Version within the SBML Level
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
,
SBMLDocument.getDefaultLevel()
,
SBMLDocument.getDefaultVersion()
public SBMLDocument(long level, long version) throws SBMLConstructorException
SBMLDocument
, optionally with given values for the SBML
Level and Version.
If both the SBML Level and Version attributes are not
specified, the SBML document is treated as having the latest Level and
Version of SBML as determined by SBMLDocument.getDefaultLevel()
and
SBMLDocument.getDefaultVersion()
however, the SBMLDocument
object is otherwise left blank. In particular, the blank SBMLDocument
object has no associated XML attributes, including (but not limited
to) an XML namespace declaration. The XML namespace declaration is
not added until the model is written out, or the method
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
is called. This may be important to keep in mind
if an application needs to add additional XML namespace declarations
on the <sbml>
element. Application writers should
either provide values for level
and version
on the call to this
constructor, or else call
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
shortly after creating the SBMLDocument
object.
level
- an integer for the SBML Level
version
- an integer for the Version within the SBML Level
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
,
SBMLDocument.getDefaultLevel()
,
SBMLDocument.getDefaultVersion()
public SBMLDocument(SBMLDocument orig) throws SBMLConstructorException
SBMLDocument
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public SBMLDocument(SBMLNamespaces sbmlns) throws SBMLConstructorException
SBMLDocument
using the given SBMLNamespaces
object
sbmlns
.
The SBMLNamespaces
object encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and (in
Level 3) packages used in addition to SBML Level 3 Core. A
common approach to using libSBML's SBMLNamespaces
facilities is to create an
SBMLNamespaces
object somewhere in a program once, then hand that object
as needed to object constructors that accept SBMLNamespaces
as arguments.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.public long checkConsistency()
If this method returns a nonzero value (meaning, one or more
consistency checks have failed for SBML document), the failures may be
due to warnings or errors. Callers should inspect the severity
flag in the individual SBMLError
objects returned by
SBMLDocument.getError(long n)
to determine the nature of the failures.
SBMLDocument.checkInternalConsistency()
public long checkInternalConsistency()
Model
.
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
The distinction between this method and
SBMLDocument.checkConsistency()
is that this method reports on
fundamental syntactic and structural errors that violate the XML
Schema for SBML by contrast, SBMLDocument.checkConsistency()
performs more elaborate model verifications and also validation
according to the validation rules written in the appendices of the
SBML Level 2 Versions 2&ndash4 specification documents.
SBMLDocument.checkConsistency()
public long checkL1Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public long checkL2v1Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public long checkL2v2Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public long checkL2v3Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public long checkL2v4Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public long checkL3v1Compatibility()
Callers should query the results of the consistency check by calling
SBMLDocument.getError(long n)
.
public SBMLDocument cloneObject()
SBMLDocument
.
cloneObject
 in class SBase
SBMLDocument
.public Model createModel()
Model
inside this SBMLDocument
, and returns a pointer to
it.
In SBML Level 2, the use of an identifier on a Model
object is
optional. This method takes an optional argument, sid
, for setting
the identifier. If not supplied, the identifier attribute on the
Model
instance is not set.
sid
- the identifier of the new Model
to create.
SBMLDocument.getModel()
,
SBMLDocument.setModel(Model m)
public Model createModel(java.lang.String sid)
Model
inside this SBMLDocument
, and returns a pointer to
it.
In SBML Level 2, the use of an identifier on a Model
object is
optional. This method takes an optional argument, sid
, for setting
the identifier. If not supplied, the identifier attribute on the
Model
instance is not set.
sid
- the identifier of the new Model
to create.
SBMLDocument.getModel()
,
SBMLDocument.setModel(Model m)
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 SBMLDocument.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 SBMLDocument.delete()
themselves.
public int enableDefaultNS(java.lang.String arg0, boolean flag)
This works by adding a xmlns="..."
attribute. No
prefix will be written when writing elements defined in the given
package extension if true
is given as second argument.
package
- the name or URI of the package extension.flag
- boolean value to indicate whether to write a namespace
prefix.
public boolean expandFunctionDefinitions()
FunctionDefinition
constructs from the document and expands
any instances of their use within <math>
elements.
For example, suppose a Model
contains a FunctionDefinition
with
identifier 'f'
representing the math expression: f(x, y) = x *
y. Suppose further that there is a reaction in which the
<math>
element of the KineticLaw
object contains
f(s, p)
, where s
and p
are other identifiers
defined in the model. The outcome of invoking this method is that the
<math>
of the KineticLaw
now represents the
expression s * p and the model no longer contains any
FunctionDefinition
objects.
true
if the transformation was successful,
false
, otherwise.
false.
public boolean expandInitialAssignments()
InitialAssignment
constructs from the document and
replaces them with appropriate values.
For example, suppose a Model
contains a InitialAssignment
to a symbol
'k'
where 'k'
is the identifier of a Parameter
. The outcome of
invoking this method is that the 'value' attribute of the Parameter
definition is set to the result calculated using the InitialAssignment
object's <math>
formula, and the corresponding
InitialAssignment
is then removed from the Model
.
true
if the transformation was successful,
false
, otherwise.
false.
As part of that process, this method will check that it has
values for any components referred to by the <math>
elements of InitialAssignment
objects. In cases where not all of the
values have been declared (e.g., if the mathematical expression refers
to model entities that have no declared values), the InitialAssignment
in question will not be removed and this method will return
false.
public static long getDefaultLevel()
SBMLDocument
objects.
This 'default Level' corresponds to the most recent SBML specification
Level available at the time libSBML version 5.10.0
was released. The default Level is used by
SBMLDocument
if no Level is explicitly specified at the time of the
construction of an SBMLDocument
instance.
SBMLDocument.getDefaultVersion()
public static long getDefaultVersion()
SBMLDocument
objects.
This 'default Version' corresponds to the most recent Version within the
most recent Level of SBML available at the time libSBML version
5.10.0
was released. The default Version is
used by SBMLDocument
if no Version is explicitly specified at the time of
the construction of an SBMLDocument
instance.
SBMLDocument.getDefaultLevel()
public SBase getElementByMetaId(java.lang.String metaid)
metaid
, or
itself if it has the given metaid
, or null
if no such object is
found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of objects to find
metaid
.public SBase getElementBySId(java.lang.String id)
id
in the
model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of objects to find
id
.public java.lang.String getElementName()
SBMLDocument
,
is always 'sbml'.
getElementName
 in class SBase
'sbml'.
public SBMLError getError(long n)
Callers can use method XMLError.getSeverity()
on the result to assess
the severity of the problem. The possible severity levels range from
informational messages to fatal errors.
n
- the integer index of the error sought.
n
, or return
null
if n > (getNumErrors() - 1)
.
SBMLDocument.getNumErrors()
public SBMLErrorLog getErrorLog()
SBMLErrorLog
used for this SBMLDocument
SBMLDocument.getNumErrors()
public java.lang.String getLocationURI()
SBMLDocument
.
If this document was read from a file or had its location set manually, that filename or set location will be returned, otherwise, an empty string is returned.
public Model getModel()
Model
object stored in this SBMLDocument
.
It is important to note that this method does not create a
Model
instance. The model in the SBMLDocument
must have been created
at some prior time, for example using SBMLDocument.createModel()
or SBMLDocument.setModel(Model m)
.
This method returns null
if a model does not yet exist.
getModel
 in class SBase
Model
contained in this SBMLDocument
.
SBMLDocument.createModel()
public XMLNamespaces getNamespaces()
getNamespaces
 in class SBase
SBase.getLevel()
,
SBase.getVersion()
public long getNumErrors()
SBMLDocument.getError(long n)
public long getNumErrors(long severity)
severity
- the severity of the error sought.
SBMLDocument.getError(long n)
public boolean getPackageRequired(java.lang.String arg0)
required
attribute of the given package
extension.
package
- the name or URI of the package extension.
public int getTypeCode()
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters &ldquoSBML_
&rdquo.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the getPackageName()
method on the object.
getTypeCode
 in class SBase
SBML_DOCUMENT
(default).
SBMLDocument.getElementName()
,
SBase.getPackageName()
public boolean isDisabledIgnoredPackage(java.lang.String pkgURI)
true
if the given package extension is one of an ignored
packages that has been disabled, otherwise returns false.
An ignored package is one that is defined to be used in this SBML document, but the package is not enabled in this copy of libSBML. It may have been disabled to avoid reproducing the package information when writing out the file.
pkgURI
- the URI of the package extension.
true
if the package is being ignored and
false
otherwise.public boolean isEnabledDefaultNS(java.lang.String arg0)
true
if a default namespace is added to each top-level
element defined in the given package extension, otherwise returns
false.
This basically checks if the attribute
xmlns="..."
is present.
package
- the name or URI of the package extension.
public boolean isIgnoredPackage(java.lang.String pkgURI)
true
if the given package extension is one of an ignored
packages, otherwise returns false.
An ignored package is one that is defined to be used in this SBML document, but the package is not enabled in this copy of libSBML.
pkgURI
- the URI of the package extension.
true
if the package is being ignored and
false
otherwise.public boolean isSetPackageRequired(java.lang.String arg0)
true
if the required attribute of the given package extension
is defined, otherwise returns false.
package
- the name or URI of the package extension.
public void printErrors()
It prints the text to the stream given by the optional parameter
stream
. If no parameter is given, it prints the output to the
standard error stream.
If no errors have occurred, i.e., getNumErrors() == 0
, no
output will be sent to the stream.
The format of the output is:
N error(s): line NNN: (id) message
stream
- the ostream or ostringstream object indicating where
the output should be printed.
SBMLDocument.getNumErrors()
,
SBMLDocument.getErrorLog()
,
SBMLDocument.getError(long n)
public void printErrors(OStream stream)
It prints the text to the stream given by the optional parameter
stream
. If no parameter is given, it prints the output to the
standard error stream.
If no errors have occurred, i.e., getNumErrors() == 0
, no
output will be sent to the stream.
The format of the output is:
N error(s): line NNN: (id) message
stream
- the ostream or ostringstream object indicating where
the output should be printed.
SBMLDocument.getNumErrors()
,
SBMLDocument.getErrorLog()
,
SBMLDocument.getError(long n)
public void setConsistencyChecks(int category, boolean apply)
SBMLDocument.checkConsistency()
is called.
This method works by adding or subtracting consistency checks from the
set of all possible checks that SBMLDocument.checkConsistency()
knows
how to perform. This method may need to be called multiple times in
order to achieve the desired combination of checks. The first
argument (category
) in a call to this method indicates the category
of consistency/error checks that are to be turned on or off, and the
second argument (apply
, a boolean) indicates whether to turn it on
(value of true
) or off (value of false
).
* The possible categories (values to the argument category
) are the
set of constants whose names begin with the characters LIBSBML_CAT_
in the interface class libsbmlConstants
.
The following are the possible choices:
LIBSBML_CAT_GENERAL_CONSISTENCY
: Correctness and consistency
of specific SBML language constructs. Performing this set of checks
is highly recommended. With respect to the SBML specification, these
concern failures in applying the validation rules numbered 2xxxx in
the Level 2 Versions 2&ndash4 and Level 3 Version 1
specifications.
LIBSBML_CAT_IDENTIFIER_CONSISTENCY
: Correctness and
consistency of identifiers used for model entities. An example of
inconsistency would be using a species identifier in a reaction rate
formula without first having declared the species. With respect to
the SBML specification, these concern failures in applying the
validation rules numbered 103xx in the Level 2 Versions 2&ndash4
and Level 3 Version 1 specifications.
LIBSBML_CAT_UNITS_CONSISTENCY
: Consistency of measurement
units associated with quantities in a model. With respect to the SBML
specification, these concern failures in applying the validation rules
numbered 105xx in the Level 2 Versions 2&ndash4 and Level 3
Version 1 specifications.
LIBSBML_CAT_MATHML_CONSISTENCY
: Syntax of MathML constructs.
With respect to the SBML specification, these concern failures in
applying the validation rules numbered 102xx in the Level 2
Versions 2&ndash4 and Level 3 Version 1 specifications.
LIBSBML_CAT_SBO_CONSISTENCY
: Consistency and validity of SBO
identifiers (if any) used in the model. With respect to the SBML
specification, these concern failures in applying the validation rules
numbered 107xx in the Level 2 Versions 2&ndash4 and Level 3
Version 1 specifications.
LIBSBML_CAT_OVERDETERMINED_MODEL
: Static analysis of whether
the system of equations implied by a model is mathematically
overdetermined. With respect to the SBML specification, this is
validation rule #10601 in the Level 2 Versions 2&ndash4 and
Level 3 Version 1 specifications.
LIBSBML_CAT_MODELING_PRACTICE
: Additional checks for
recommended good modeling practice. (These are tests performed by
libSBML and do not have equivalent SBML validation rules.)
By default, all validation checks are applied to the model in
an SBMLDocument
object unless
SBMLDocument.setConsistencyChecks(int categ, boolean onoff)
is called to indicate that only a subset should be applied. Further,
this default (i.e., performing all checks) applies separately to
each new SBMLDocument
object created. In other words, each
time a model is read using SBMLReader.readSBML(String filename)
,
SBMLReader.readSBMLFromString(String xml)
,
or the global functions readSBML() and readSBMLFromString(), a new
SBMLDocument
is created and for that document, a call to
SBMLDocument.checkConsistency()
will default to applying all possible checks.
Calling programs must invoke
SBMLDocument.setConsistencyChecks(int categ, boolean onoff)
for each such new model if they wish to change the consistency checks
applied.
category
- a value drawn from * the set of SBML error categories indicating the
consistency checking/validation to be turned on or off.
apply
- a boolean indicating whether the checks indicated by
category
should be applied or not.
SBMLDocument.checkConsistency()
public void setConsistencyChecksForConversion(int category, boolean apply)
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
is called.
This method works by adding or subtracting consistency checks from the
set of all possible checks that may be performed to avoid conversion
to or from an invalid document. This method may need to be called
multiple times in
order to achieve the desired combination of checks. The first
argument (category
) in a call to this method indicates the category
of consistency/error checks that are to be turned on or off, and the
second argument (apply
, a boolean) indicates whether to turn it on
(value of true
) or off (value of false
).
* The possible categories (values to the argument category
) are the
set of constants whose names begin with the characters LIBSBML_CAT_
in the interface class libsbmlConstants
.
The following are the possible choices:
LIBSBML_CAT_GENERAL_CONSISTENCY
: Correctness and consistency
of specific SBML language constructs. Performing this set of checks
is highly recommended. With respect to the SBML specification, these
concern failures in applying the validation rules numbered 2xxxx in
the Level 2 Versions 2&ndash4 and Level 3 Version 1
specifications.
LIBSBML_CAT_IDENTIFIER_CONSISTENCY
: Correctness and
consistency of identifiers used for model entities. An example of
inconsistency would be using a species identifier in a reaction rate
formula without first having declared the species. With respect to
the SBML specification, these concern failures in applying the
validation rules numbered 103xx in the Level 2 Versions 2&ndash4
and Level 3 Version 1 specifications.
LIBSBML_CAT_UNITS_CONSISTENCY
: Consistency of measurement
units associated with quantities in a model. With respect to the SBML
specification, these concern failures in applying the validation rules
numbered 105xx in the Level 2 Versions 2&ndash4 and Level 3
Version 1 specifications.
LIBSBML_CAT_MATHML_CONSISTENCY
: Syntax of MathML constructs.
With respect to the SBML specification, these concern failures in
applying the validation rules numbered 102xx in the Level 2
Versions 2&ndash4 and Level 3 Version 1 specifications.
LIBSBML_CAT_SBO_CONSISTENCY
: Consistency and validity of SBO
identifiers (if any) used in the model. With respect to the SBML
specification, these concern failures in applying the validation rules
numbered 107xx in the Level 2 Versions 2&ndash4 and Level 3
Version 1 specifications.
LIBSBML_CAT_OVERDETERMINED_MODEL
: Static analysis of whether
the system of equations implied by a model is mathematically
overdetermined. With respect to the SBML specification, this is
validation rule #10601 in the Level 2 Versions 2&ndash4 and
Level 3 Version 1 specifications.
LIBSBML_CAT_MODELING_PRACTICE
: Additional checks for
recommended good modeling practice. (These are tests performed by
libSBML and do not have equivalent SBML validation rules.)
By default, all validation checks are applied to the model in
an SBMLDocument
object unless
SBMLDocument.setConsistencyChecks(int categ, boolean onoff)
is called to indicate that only a subset should be applied. Further,
this default (i.e., performing all checks) applies separately to
each new SBMLDocument
object created. In other words, each
time a model is read using SBMLReader.readSBML(String filename)
,
SBMLReader.readSBMLFromString(String xml)
,
or the global functions readSBML() and readSBMLFromString(), a new
SBMLDocument
is created and for that document, a call to
SBMLDocument.checkConsistency()
will default to applying all possible checks.
Calling programs must invoke
SBMLDocument.setConsistencyChecks(int categ, boolean onoff)
for each such new model if they wish to change the consistency checks
applied.
category
- a value drawn from * the set of SBML error categories indicating the consistency
checking/validation to be turned on or off.
apply
- a boolean indicating whether the checks indicated by
category
should be applied or not.
SBMLDocument.setLevelAndVersion(long lev, long ver, boolean strict)
public boolean setLevelAndVersion(long level, long version)
SBMLDocument
instance,
attempting to convert the model as needed.
This method is the principal way in libSBML to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.
Before calling this method, callers may check compatibility directly
using the methods SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
, and
SBMLDocument.checkL3v1Compatibility()
.
The valid combinations of SBML Level and Version as of this release of libSBML are the following:
Strict conversion applies the additional criteria that both the
source and the target model must be consistent SBML. Users can
control the consistency checks that are applied using the
SBMLDocument.setConsistencyChecksForConversion(int categ, boolean onoff)
method. If either
the source or the potential target model have validation errors, the
conversion is not performed. When a strict conversion is successful,
the underlying SBML object model is altered to reflect the new level
and version. Thus, information that cannot be converted
(e.g. sboTerms) will be lost.
level
- the desired SBML Level
version
- the desired Version within the SBML Level
strict
- boolean indicating whether to check consistency
of both the source and target model when performing
conversion (defaults to true
)
ignorePackages
- boolean indicating whether the presence of
packages should be ignored by the conversion routine
(defaults to false
)
true
if the level and version of the document were
successfully set to the requested values (which may have required
conversion of the model), false
otherwise.
SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
SBMLDocument
. Callers should consult
getNumErrors() to find out if the conversion succeeded without
problems. For conversions from Level 2 to Level 1, callers
can also check the Level of the model after calling this method to
find out whether it is Level 1. (If the conversion to
Level 1 failed, the Level of this model will be left unchanged.)
public boolean setLevelAndVersion(long level, long version, boolean strict)
SBMLDocument
instance,
attempting to convert the model as needed.
This method is the principal way in libSBML to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.
Before calling this method, callers may check compatibility directly
using the methods SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
, and
SBMLDocument.checkL3v1Compatibility()
.
The valid combinations of SBML Level and Version as of this release of libSBML are the following:
Strict conversion applies the additional criteria that both the
source and the target model must be consistent SBML. Users can
control the consistency checks that are applied using the
SBMLDocument.setConsistencyChecksForConversion(int categ, boolean onoff)
method. If either
the source or the potential target model have validation errors, the
conversion is not performed. When a strict conversion is successful,
the underlying SBML object model is altered to reflect the new level
and version. Thus, information that cannot be converted
(e.g. sboTerms) will be lost.
level
- the desired SBML Level
version
- the desired Version within the SBML Level
strict
- boolean indicating whether to check consistency
of both the source and target model when performing
conversion (defaults to true
)
ignorePackages
- boolean indicating whether the presence of
packages should be ignored by the conversion routine
(defaults to false
)
true
if the level and version of the document were
successfully set to the requested values (which may have required
conversion of the model), false
otherwise.
SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
SBMLDocument
. Callers should consult
getNumErrors() to find out if the conversion succeeded without
problems. For conversions from Level 2 to Level 1, callers
can also check the Level of the model after calling this method to
find out whether it is Level 1. (If the conversion to
Level 1 failed, the Level of this model will be left unchanged.)
public boolean setLevelAndVersion(long level, long version, boolean strict, boolean ignorePackages)
SBMLDocument
instance,
attempting to convert the model as needed.
This method is the principal way in libSBML to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.
Before calling this method, callers may check compatibility directly
using the methods SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
, and
SBMLDocument.checkL3v1Compatibility()
.
The valid combinations of SBML Level and Version as of this release of libSBML are the following:
Strict conversion applies the additional criteria that both the
source and the target model must be consistent SBML. Users can
control the consistency checks that are applied using the
SBMLDocument.setConsistencyChecksForConversion(int categ, boolean onoff)
method. If either
the source or the potential target model have validation errors, the
conversion is not performed. When a strict conversion is successful,
the underlying SBML object model is altered to reflect the new level
and version. Thus, information that cannot be converted
(e.g. sboTerms) will be lost.
level
- the desired SBML Level
version
- the desired Version within the SBML Level
strict
- boolean indicating whether to check consistency
of both the source and target model when performing
conversion (defaults to true
)
ignorePackages
- boolean indicating whether the presence of
packages should be ignored by the conversion routine
(defaults to false
)
true
if the level and version of the document were
successfully set to the requested values (which may have required
conversion of the model), false
otherwise.
SBMLDocument.checkL1Compatibility()
,
SBMLDocument.checkL2v1Compatibility()
,
SBMLDocument.checkL2v2Compatibility()
,
SBMLDocument.checkL2v3Compatibility()
,
SBMLDocument.checkL2v4Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
,
SBMLDocument.checkL3v1Compatibility()
SBMLDocument
. Callers should consult
getNumErrors() to find out if the conversion succeeded without
problems. For conversions from Level 2 to Level 1, callers
can also check the Level of the model after calling this method to
find out whether it is Level 1. (If the conversion to
Level 1 failed, the Level of this model will be left unchanged.)
public void setLocationURI(java.lang.String uri)
SBMLDocument
.
Called automatically when readSBMLFromFile is used, but may be set manually as well.
public int setModel(Model m)
m
- the new Model
to use.
SBMLDocument.createModel()
,
SBMLDocument.getModel()
public int setPackageRequired(java.lang.String arg0, boolean flag)
required
attribute value of the given package
extension.
package
- the name or URI of the package extension.flag
- Boolean value indicating whether the package is required.
public long validateSBML()
If this method returns a nonzero value (meaning, one or more
consistency checks have failed for SBML document), the failures may be
due to warnings or errors. Callers should inspect the severity
flag in the individual SBMLError
objects returned by
SBMLDocument.getError(long n)
to determine the nature of the failures.
SBMLDocument.checkConsistency()