public class SyntaxChecker extends java.lang.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.
This utility class provides static methods for checking the syntax of identifiers and other text used in an SBML model. The methods allow callers to verify that strings such as SBML identifiers and XHTML notes text conform to the SBML specifications.
Constructor and Description |
---|
SyntaxChecker()   |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
static boolean |
hasExpectedXHTMLSyntax(XMLNode xhtml)
|
static boolean |
hasExpectedXHTMLSyntax(XMLNode xhtml,
SBMLNamespaces sbmlns)
|
static boolean |
isValidSBMLSId(java.lang.String sid)
Returns true
true or false depending on whether the argument
string conforms to the syntax of SBML identifiers. |
static boolean |
isValidUnitSId(java.lang.String units)
Returns
true or false depending on whether the argument string
conforms to the syntax of SBML unit identifiers. |
static boolean |
isValidXMLanyURI(java.lang.String uri)
Returns
true or false depending on whether the uri argument string
conforms to the XML data type anyURI . |
static boolean |
isValidXMLID(java.lang.String id)
Returns
true or false depending on whether the argument string
conforms to the XML data type ID . |
public SyntaxChecker()
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 SyntaxChecker.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 SyntaxChecker.delete()
themselves.
public static boolean hasExpectedXHTMLSyntax(XMLNode xhtml)
true
or false
depending on whether the given XMLNode
object contains valid XHTML content.
The optional SBML element named 'notes', present on every major SBML
component type (and in SBML Level 3, the 'message' subelement of
Constraint
), is intended as a place for storing optional information
intended to be seen by humans. An example use of the 'notes' element
would be to contain formatted user comments about the model element in
which the 'notes' element is enclosed. Every object derived directly or
indirectly from type SBase
can have a separate value for 'notes', allowing
users considerable freedom when adding comments to their models.
The format of 'notes' elements conform to the definition of XHTML 1.0.
However, the content cannot be entirely free-form it must satisfy
certain requirements defined in the SBML specifications
for specific SBML Levels. To help verify the formatting of 'notes'
content, libSBML provides the static utility method
SyntaxChecker.hasExpectedXHTMLSyntax(XMLNode xhtml)
The
method implements a verification process that lets callers check whether
the content of a given XMLNode
object conforms to the SBML requirements
for 'notes' and 'message' structure. Developers are urged to consult the
appropriate SBML specification
document for the Level and Version of their model for more in-depth
explanations of using 'notes' in SBML. The SBML Level 2 and  3
specifications have considerable detail about how 'notes' element content
must be structured.
An aspect of XHTML validity is that the content is declared to be in the XML namespace for XHTML 1.0. There is more than one way in which this can be done in XML. In particular, a model might not contain the declaration within the 'notes' or 'message' subelement itself, but might instead place the declaration on an enclosing element and use an XML namespace prefix within the 'notes' element to refer to it. In other words, the following is valid:
<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' xmlns:xhtml='http://www.w3.org/1999/xhtml'> <model> <notes> <xhtml:body> <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> </xhtml:body> </notes> ... rest of model ... </sbml>
<notes>
element itself:
<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> <model> <notes> <html xmlns='http://www.w3.org/1999/xhtml'> <head> <title/> </head> <body> <center><h2>A Simple Mitotic Oscillator</h2></center> A minimal cascade model for the mitotic oscillator.</p> </body> </html> </notes> ... rest of model ... </sbml>
Both of the above are valid XML. The purpose of the sbmlns
argument to this method is to allow callers to check the validity of
'notes' and 'message' subelements whose XML namespace declarations
have been put elsewhere in the manner illustrated above. Callers can
can pass in the SBMLNamespaces
object of a higher-level model
component if the XMLNode
object does not itself have the XML namespace
declaration for XHTML 1.0.
xhtml
- the XMLNode
to be checked for conformance.sbmlns
- the SBMLNamespaces
associated with the object.
true
if the XMLNode
content conforms, false
otherwise.
public static boolean hasExpectedXHTMLSyntax(XMLNode xhtml, SBMLNamespaces sbmlns)
true
or false
depending on whether the given XMLNode
object contains valid XHTML content.
The optional SBML element named 'notes', present on every major SBML
component type (and in SBML Level 3, the 'message' subelement of
Constraint
), is intended as a place for storing optional information
intended to be seen by humans. An example use of the 'notes' element
would be to contain formatted user comments about the model element in
which the 'notes' element is enclosed. Every object derived directly or
indirectly from type SBase
can have a separate value for 'notes', allowing
users considerable freedom when adding comments to their models.
The format of 'notes' elements conform to the definition of XHTML 1.0.
However, the content cannot be entirely free-form it must satisfy
certain requirements defined in the SBML specifications
for specific SBML Levels. To help verify the formatting of 'notes'
content, libSBML provides the static utility method
SyntaxChecker.hasExpectedXHTMLSyntax(XMLNode xhtml)
The
method implements a verification process that lets callers check whether
the content of a given XMLNode
object conforms to the SBML requirements
for 'notes' and 'message' structure. Developers are urged to consult the
appropriate SBML specification
document for the Level and Version of their model for more in-depth
explanations of using 'notes' in SBML. The SBML Level 2 and  3
specifications have considerable detail about how 'notes' element content
must be structured.
An aspect of XHTML validity is that the content is declared to be in the XML namespace for XHTML 1.0. There is more than one way in which this can be done in XML. In particular, a model might not contain the declaration within the 'notes' or 'message' subelement itself, but might instead place the declaration on an enclosing element and use an XML namespace prefix within the 'notes' element to refer to it. In other words, the following is valid:
<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3' xmlns:xhtml='http://www.w3.org/1999/xhtml'> <model> <notes> <xhtml:body> <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center> <xhtml:p>A minimal cascade model for the mitotic oscillator.</xhtml:p> </xhtml:body> </notes> ... rest of model ... </sbml>
<notes>
element itself:
<sbml xmlns='http://www.sbml.org/sbml/level2/version3' level='2' version='3'> <model> <notes> <html xmlns='http://www.w3.org/1999/xhtml'> <head> <title/> </head> <body> <center><h2>A Simple Mitotic Oscillator</h2></center> A minimal cascade model for the mitotic oscillator.</p> </body> </html> </notes> ... rest of model ... </sbml>
Both of the above are valid XML. The purpose of the sbmlns
argument to this method is to allow callers to check the validity of
'notes' and 'message' subelements whose XML namespace declarations
have been put elsewhere in the manner illustrated above. Callers can
can pass in the SBMLNamespaces
object of a higher-level model
component if the XMLNode
object does not itself have the XML namespace
declaration for XHTML 1.0.
xhtml
- the XMLNode
to be checked for conformance.sbmlns
- the SBMLNamespaces
associated with the object.
true
if the XMLNode
content conforms, false
otherwise.
public static boolean isValidSBMLSId(java.lang.String sid)
true
or false
depending on whether the argument
string conforms to the syntax of SBML identifiers.
In SBML, identifiers that are the values of 'id' attributes on objects
must conform to a data type called SId
in the SBML
specifications. LibSBML does not provide an explicit SId
data type it uses ordinary character strings, which is easier for
applications to support. (LibSBML does, however, test for identifier
validity at various times, such as when reading in models from files
and data streams.)
This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.
sid
- string to be checked for conformance to SBML identifier
syntax.
true
if the string conforms to type SBML data type
SId
, false
otherwise.
SBML has strict requirements for the syntax of identifiers, that is, the
values of the 'id' attribute present on most types of SBML objects.
The following is a summary of the definition of the SBML identifier type
SId
, which defines the permitted syntax of identifiers. We
express the syntax using an extended form of BNF notation:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*The characters
(
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. In addition, there are a few
conditions for the uniqueness of identifiers in an SBML model. Please
consult the SBML specifications for the exact details of the uniqueness
requirements.
SyntaxChecker.isValidUnitSId(String sid)
,
SyntaxChecker.isValidXMLID(String sid)
public static boolean isValidUnitSId(java.lang.String units)
true
or false
depending on whether the argument string
conforms to the syntax of SBML unit identifiers.
In SBML, the identifiers of units (of both the predefined units and
user-defined units) must conform to a data type called
UnitSId
in the SBML specifications. LibSBML does not
provide an explicit UnitSId
data type it uses ordinary
character strings, which is easier for applications to support.
LibSBML does, however, test for identifier validity at various times,
such as when reading in models from files and data streams.
This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.
units
- string to be checked for conformance to SBML unit
identifier syntax.
true
if the string conforms to type SBML data type
UnitSId
, false
otherwise.
SyntaxChecker.isValidSBMLSId(String sid)
,
SyntaxChecker.isValidXMLID(String sid)
UnitSId
, which defines the permitted syntax of identifiers.
We express the syntax using an extended form of BNF notation:
letter ::= 'a'..'z','A'..'Z'
digit ::= '0'..'9'
idChar ::= letter | digit | '_'
SId ::= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
"zero or more times", and the character
|
indicates logical "or". The equality of SBML unit
identifiers is determined by an exact character sequence match i.e.,
comparisons must be performed in a case-sensitive manner. In addition,
there are a few conditions for the uniqueness of unit identifiers in an
SBML model. Please consult the SBML specifications for the exact
formulations.
public static boolean isValidXMLanyURI(java.lang.String uri)
true
or false
depending on whether the uri
argument string
conforms to the XML data type anyURI
.
Type anyURI is defined by XML Schema 1.0. It is a character string
data type whose values are interpretable as URIs (Universal Resource
Identifiers) as described by the W3C document RFC 3986. LibSBML
does not provide an explicit XML anyURI
data type it uses
ordinary character strings, which is easier for applications to
support. LibSBML does, however, test for anyURI validity at
various times, such as when reading in models from files and data
streams.
This method provides programs with the ability to test explicitly that the strings they create conform to the XML anyURI syntax.
public static boolean isValidXMLID(java.lang.String id)
true
or false
depending on whether the argument string
conforms to the XML data type ID
.
The optional attribute named 'metaid', present on every major SBML
component type, is for supporting metadata annotations using RDF (Resource Description Format). The
attribute value has the data type XML ID
, the XML
identifier type, which means each 'metaid' value must be globally unique
within an SBML file. The latter point is important, because the
uniqueness criterion applies across any attribute with type
ID
anywhere in the file, not just the 'metaid' attribute used
by SBML&mdashsomething to be aware of if your application-specific XML
content inside the 'annotation' subelement happens to use the XML
ID
type. Although SBML itself specifies the use of XML ID
only for
the 'metaid' attribute, SBML-compatible applications should be careful if
they use XML ID
's in XML portions of a model that are not
defined by SBML, such as in the application-specific content of the
'annotation' subelement. Finally, note that LibSBML does not provide an
explicit XML ID
data type it uses ordinary character
strings, which is easier for applications to support.
This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.
id
- string to be checked for conformance to the syntax of
XML ID.
true
if the string is a syntactically-valid value for the
XML type ID, false
otherwise.
SyntaxChecker.isValidSBMLSId(String sid)
,
SyntaxChecker.isValidUnitSId(String sid)
NCNameChar ::= letter | digit | '.' | '-' | '_' | ':' | CombiningChar | Extender
ID ::= ( letter | '_' | ':' ) NCNameChar*
The characters (
and )
are used for grouping, the
character *
means "zero or more times", and the character
|
indicates logical "or". The production letter
consists of the basic upper and lower case alphabetic characters of the
Latin alphabet along with a large number of related characters defined by
Unicode 2.0 similarly, the production digit
consists of
the numerals 0..9
along with related Unicode 2.0
characters. The CombiningChar
production is a list of
characters that add such things as accents to the preceding character. (For
example, the Unicode character \#x030A
when combined with
a
produces a
.) The Extender
production is a list of characters that extend the shape of the preceding
character. Please consult the XML 1.0
specification for the complete definitions of letter
,
digit
, CombiningChar
, and Extender
.