public class XMLInputStream 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.
SBML content is serialized using XML the resulting data can be stored and
read to/from a file or data stream. Low-level XML parsers such as Xerces
provide facilities to read XML data. To permit the use of different XML
parsers (Xerces, Expat or libxml2), libSBML implements an abstraction
layer. XMLInputStream
and XMLOutputStream
are two parts of that
abstraction layer.
XMLInputStream
is an interface to a file or text string containing XML.
It wraps the content to be read, as well as the low-level XML parser to be
used and an XMLErrorLog
to record errors and other issues (if any arise).
Internally, the content will be in the form of either a pointer to a file
name or a character string XMLInputStream
knows the form of the content
and acts appropriately. Other libSBML object classes use XMLInputStream
as their interface for all read operations on the XML data.
XMLInputStream
provides the functionality to extract data in the form of
XMLToken
objects. It logs any errors encountered while reading. It also
keeps track of whether a read operation has failed irrecoverably or
determines whether it is safe to continue reading.
SBMLNamespaces
objects can be associated with an XMLInputStream
this
facilitates logging errors related to reading XML attributes and elements
that may only be relevant to particular Level and Version combinations of
SBML.
XMLOutputStream
XMLInputStream
and XMLOutputStream
abstraction may be useful for developers interested in creating parsers
for other XML formats besides SBML. It can provide developers with a
layer above more basic XML parsers, as well as some useful programmatic
elements such as XMLToken
, XMLError
, etc.
Constructor and Description |
---|
XMLInputStream(String content)
Creates a new
XMLInputStream . |
XMLInputStream(String content,
boolean isFile)
Creates a new
XMLInputStream . |
XMLInputStream(String content,
boolean isFile,
String library)
Creates a new
XMLInputStream . |
XMLInputStream(String content,
boolean isFile,
String library,
XMLErrorLog errorLog)
Creates a new
XMLInputStream . |
Modifier and Type | Method and Description |
---|---|
boolean |
containsChild(String childName,
String container)
Predicate returning
true if a child token of the specified type occurs
within a given container element. |
void |
delete()
Explicitly deletes the underlying native object.
|
long |
determineNumberChildren()
Returns the number of child tokens of the given element in this stream.
|
long |
determineNumberChildren(String elementName)
Returns the number of child tokens of the given element in this stream.
|
long |
determineNumSpecificChildren(String childName,
String container)
Returns the number of child tokens of the specified type within a
given container element.
|
String |
getEncoding()
Returns the encoding of the XML stream.
|
XMLErrorLog |
getErrorLog()
Returns the
XMLErrorLog used to log parsing problems. |
SBMLNamespaces |
getSBMLNamespaces()
Returns the
SBMLNamespaces object attached to this XMLInputStream . |
String |
getVersion()
Returns the version of the XML stream.
|
boolean |
isEOF()
Returns
true if end of file (stream) has been reached. |
boolean |
isError()
Returns
true if a fatal error occurred while reading from this
stream. |
boolean |
isGood()
Returns
true if the stream is in a good state. |
XMLToken |
next()
Returns the next token on this XML input stream.
|
XMLToken |
peek()
Returns the next token without consuming it.
|
int |
setErrorLog(XMLErrorLog log)
Sets the
XMLErrorLog this stream will use to log errors. |
void |
setSBMLNamespaces(SBMLNamespaces sbmlns)
Sets the SBML namespaces associated with this XML input stream.
|
void |
skipPastEnd(XMLToken element)
Consume zero or more tokens up to and including the corresponding end
element or EOF.
|
void |
skipText()
Consume zero or more tokens up to but not including the next XML element
or EOF.
|
String |
toString()
Prints a string representation of the underlying token stream.
|
public XMLInputStream(String content, boolean isFile, String library, XMLErrorLog errorLog)
XMLInputStream
.
content
- the source of the stream.
isFile
- a boolean flag to indicate whether content
is a file
name. If true
, content
is assumed to be the file from which the
XML content is to be read. If false
, content
is taken to be a
string that is the content to be read.
library
- the name of the parser library to use.
errorLog
- the XMLErrorLog
object to use.
public XMLInputStream(String content, boolean isFile, String library)
XMLInputStream
.
content
- the source of the stream.
isFile
- a boolean flag to indicate whether content
is a file
name. If true
, content
is assumed to be the file from which the
XML content is to be read. If false
, content
is taken to be a
string that is the content to be read.
library
- the name of the parser library to use.
errorLog
- the XMLErrorLog
object to use.
public XMLInputStream(String content, boolean isFile)
XMLInputStream
.
content
- the source of the stream.
isFile
- a boolean flag to indicate whether content
is a file
name. If true
, content
is assumed to be the file from which the
XML content is to be read. If false
, content
is taken to be a
string that is the content to be read.
library
- the name of the parser library to use.
errorLog
- the XMLErrorLog
object to use.
public XMLInputStream(String content)
XMLInputStream
.
content
- the source of the stream.
isFile
- a boolean flag to indicate whether content
is a file
name. If true
, content
is assumed to be the file from which the
XML content is to be read. If false
, content
is taken to be a
string that is the content to be read.
library
- the name of the parser library to use.
errorLog
- the XMLErrorLog
object to use.
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 XMLInputStream.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 XMLInputStream.delete()
themselves.
public String getEncoding()
The encoding is indicated by the xml
declaration at the
beginning of an XML document or data stream. The form of this declaration
is
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding, so for SBML documents, the value returned by this method will always be the string
'UTF-8'
.
XMLInputStream.getVersion()
public String getVersion()
The version is indicated by the xml
declaration at the
beginning of an XML document or data stream. The form of this declaration
is
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of version 1.0, so for SBML documents, the value returned by this method will always be the string
'1.0'
.
XMLInputStream.getEncoding()
public XMLErrorLog getErrorLog()
XMLErrorLog
used to log parsing problems.
XMLErrorLog
used to log XML parse errors and other
validation errors (and messages).public boolean isEOF()
true
if end of file (stream) has been reached.
true
if end of file (stream) has been reached, false
otherwise.public boolean isError()
true
if a fatal error occurred while reading from this
stream.
true
if a fatal error occurred while reading from this
stream.public boolean isGood()
true
if the stream is in a good state.
The definition of 'good state' is that isEOF() and isError() both return
false.
true
if the stream is in a good state, false
otherwise.public XMLToken next()
The token is consumed in the process.
XMLToken
, or an EOF token (i.e.,
XMLToken.isEOF() == true
).
XMLInputStream.peek()
public XMLToken peek()
A subsequent call to either peek() or next() will return the same token.
XMLToken
or EOF (XMLToken.isEOF() == true).
XMLInputStream.next()
public void skipPastEnd(XMLToken element)
element
- the element whose end will be sought in the input stream.public void skipText()
public int setErrorLog(XMLErrorLog log)
XMLErrorLog
this stream will use to log errors.
public String toString()
public SBMLNamespaces getSBMLNamespaces()
SBMLNamespaces
object attached to this XMLInputStream
.
SBMLNamespaces
object or null
if none has been set.public void setSBMLNamespaces(SBMLNamespaces sbmlns)
This allows this stream to reference the available SBML namespaces being read.
sbmlns
- the list of namespaces to use.public long determineNumberChildren(String elementName)
This method allows information from the input stream to be determined
without the need to actually read and consume the tokens in the stream.
It returns the number of child elements of the element represented by
the elementName
, i.e., the number of child elements encountered
before the closing tag for the elementName
supplied.
If no elementName
is supplied or it is an empty string, then as a
special case, this method assumes the element is a MathML
apply
element followed by a function name.
elementName
- a string representing the name of the element for
which the number of children are to be determined.
elementName
specified.
elementName
.
public long determineNumberChildren()
This method allows information from the input stream to be determined
without the need to actually read and consume the tokens in the stream.
It returns the number of child elements of the element represented by
the elementName
, i.e., the number of child elements encountered
before the closing tag for the elementName
supplied.
If no elementName
is supplied or it is an empty string, then as a
special case, this method assumes the element is a MathML
apply
element followed by a function name.
elementName
- a string representing the name of the element for
which the number of children are to be determined.
elementName
specified.
elementName
.
public long determineNumSpecificChildren(String childName, String container)
This method allows information from the input stream to be determined
without the need to actually read and consume the tokens in the stream.
It returns the number of child elements of the childName
element
within the element specified by container
. In other words, it counts
the number of childName
elements encountered before the closing tag
for the container
supplied.
childName
- a string representing the name of the child
element whose number is to be determined.
container
- a string representing the name of the element
for which the number of children are to be determined.
childName
within the container
element.
container
.public boolean containsChild(String childName, String container)
true
if a child token of the specified type occurs
within a given container element.
This method allows information from the input stream to be determined
without the need to actually read and consume the tokens in the stream.
It returns true
if the childName
element occurs at any point
within the element specified by container
.
childName
- a string representing the name of the child
element whose presence is to be determined.
container
- a string representing the name of the element
for which the presence of the child element is to be determined.
true
if a child of type childName
occurs within
the container
element, false
otherwise.
container
.