public class SyntaxChecker 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.
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(String sid)
Returns true
true or false depending on whether the argument
string conforms to the syntax of SBML identifiers. |
static boolean |
isValidUnitSId(String units)
Returns
true or false depending on whether the argument string
conforms to the syntax of SBML unit identifiers. |
static boolean |
isValidXMLID(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.
In SBML, the content of the 'notes' subelement available on SBase
, as
well as the 'message' subelement available on Constraint
, must conform
to XHTML 1.0 (which is
simply an XML-ized version of HTML). However, the content cannot be
entirely free-form it must satisfy certain requirements defined in
the SBML
specifications for specific SBML Levels. This 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.
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.
SyntaxChecker
), and the
other will be a standalone top-level function with the name
SyntaxChecker_hasExpectedXHTMLSyntax(). They are functionally
identical.
public static boolean hasExpectedXHTMLSyntax(XMLNode xhtml, SBMLNamespaces sbmlns)
true
or false
depending on whether the given XMLNode
object contains valid XHTML content.
In SBML, the content of the 'notes' subelement available on SBase
, as
well as the 'message' subelement available on Constraint
, must conform
to XHTML 1.0 (which is
simply an XML-ized version of HTML). However, the content cannot be
entirely free-form it must satisfy certain requirements defined in
the SBML
specifications for specific SBML Levels. This 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.
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.
SyntaxChecker
), and the
other will be a standalone top-level function with the name
SyntaxChecker_hasExpectedXHTMLSyntax(). They are functionally
identical.
public static boolean isValidSBMLSId(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.
SyntaxChecker.isValidUnitSId(String sid)
,
SyntaxChecker.isValidXMLID(String sid)
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 formulations.
, Because this is a static method, the
non-C++ language interfaces for libSBML will contain two variants. One
will be a static method on the class (i.e., SyntaxChecker
), and the
other will be a standalone top-level function with the name
SyntaxChecker_isValidSBMLSId(). They are functionally
identical.
public static boolean isValidUnitSId(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.
, Because this is a static method, the
non-C++ language interfaces for libSBML will contain two variants. One
will be a static method on the class (i.e., SyntaxChecker
), and the
other will be a standalone top-level function with the name
SyntaxChecker_isValidUnitSId(). They are functionally
identical.
public static boolean isValidXMLID(String id)
true
or false
depending on whether the argument string
conforms to the XML data type ID
.
In SBML, identifiers that are the values of 'metaid' attributes on
objects must conform to the XML ID data type. LibSBML
does not provide an explicit XML ID
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.
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
.
, Because this is a static method, the
non-C++ language interfaces for libSBML will contain two variants. One
will be a static method on the class (i.e., SyntaxChecker
), and the
other will be a standalone top-level function with the name
SyntaxChecker_isValidXMLID(). They are functionally
identical.