org.sbml.libsbml

Class XMLInputStream

java.lang.Object

org.sbml.libsbml.XMLInputStream

public class XMLInputStream
extends java.lang.Object

An interface to an XML input stream.

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.

See Also:

XMLOutputStream

Note:

The convenience of the 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 Summary

Constructors

Constructor and Description
XMLInputStream(java.lang.String content) Creates a new XMLInputStream.
XMLInputStream(java.lang.String content, boolean isFile) Creates a new XMLInputStream.
XMLInputStream(java.lang.String content, boolean isFile, java.lang.String library) Creates a new XMLInputStream.
XMLInputStream(java.lang.String content, boolean isFile, java.lang.String library, XMLErrorLog errorLog) Creates a new XMLInputStream.

Method Summary

Modifier and Type	Method and Description
boolean	containsChild(java.lang.String childName, java.lang.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(java.lang.String elementName) Returns the number of child tokens of the given element in this stream.
long	determineNumSpecificChildren(java.lang.String childName, java.lang.String container) Returns the number of child tokens of the specified type within a given container element.
java.lang.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.
java.lang.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.
java.lang.String	toString() Prints a string representation of the underlying token stream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLInputStream

public XMLInputStream(java.lang.String content,
                      boolean isFile,
                      java.lang.String library,
                      XMLErrorLog errorLog)

Creates a new XMLInputStream.

Parameters:

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.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

XMLInputStream

public XMLInputStream(java.lang.String content,
                      boolean isFile,
                      java.lang.String library)

Creates a new XMLInputStream.

Parameters:

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.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

XMLInputStream

public XMLInputStream(java.lang.String content,
                      boolean isFile)

Creates a new XMLInputStream.

Parameters:

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.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

XMLInputStream

public XMLInputStream(java.lang.String content)

Creates a new XMLInputStream.

Parameters:

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.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

Method Detail

delete

public void delete()

Explicitly deletes the underlying native object.

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.

getEncoding

public java.lang.String getEncoding()

Returns the encoding of the XML stream.

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'.

Returns:

the encoding of the XML stream.

See Also:

XMLInputStream.getVersion()

getVersion

public java.lang.String getVersion()

Returns the version of the XML stream.

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'.

Returns:

the version of the XML stream.

See Also:

XMLInputStream.getEncoding()

getErrorLog

public XMLErrorLog getErrorLog()

Returns the XMLErrorLog used to log parsing problems.

Returns:

the XMLErrorLog used to log XML parse errors and other validation errors (and messages).

isEOF

public boolean isEOF()

Returns true if end of file (stream) has been reached.

Returns:

true if end of file (stream) has been reached, false otherwise.

isError

public boolean isError()

Returns true if a fatal error occurred while reading from this stream.

Returns:

true if a fatal error occurred while reading from this stream.

isGood

public boolean isGood()

Returns true if the stream is in a good state.

The definition of 'good state' is that isEOF() and isError() both return false.

Returns:

true if the stream is in a good state, false otherwise.

next

public XMLToken next()

Returns the next token on this XML input stream.

The token is consumed in the process.

Returns:

the next XMLToken, or an EOF token (i.e., XMLToken.isEOF() == true).

See Also:

XMLInputStream.peek()

peek

public XMLToken peek()

Returns the next token without consuming it.

A subsequent call to either peek() or next() will return the same token.

Returns:

the next XMLToken or EOF (XMLToken.isEOF() == true).

See Also:

XMLInputStream.next()

skipPastEnd

public void skipPastEnd(XMLToken element)

Consume zero or more tokens up to and including the corresponding end element or EOF.

Parameters:

element - the element whose end will be sought in the input stream.

skipText

public void skipText()

Consume zero or more tokens up to but not including the next XML element or EOF.

setErrorLog

public int setErrorLog(XMLErrorLog log)

Sets the XMLErrorLog this stream will use to log errors.

Returns:

integer value indicating success/failure of the function. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_OPERATION_FAILED

toString

public java.lang.String toString()

Prints a string representation of the underlying token stream.

Overrides:

toString in class java.lang.Object

Returns:

a string representing the underlying XML token stream.

Note:

This method is intended for debugging purposes.

getSBMLNamespaces

public SBMLNamespaces getSBMLNamespaces()

Returns the SBMLNamespaces object attached to this XMLInputStream.

Returns:

the SBMLNamespaces object or null if none has been set.

setSBMLNamespaces

public void setSBMLNamespaces(SBMLNamespaces sbmlns)

Sets the SBML namespaces associated with this XML input stream.

This allows this stream to reference the available SBML namespaces being read.

Parameters:

sbmlns - the list of namespaces to use.

determineNumberChildren

public long determineNumberChildren(java.lang.String elementName)

Returns the number of child tokens of the given element in this stream.

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.

Parameters:

elementName - a string representing the name of the element for which the number of children are to be determined.

Returns:

a long integer giving the number of children of the elementName specified.

Note:

This method assumes the stream has been read up to and including the element elementName.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

determineNumberChildren

public long determineNumberChildren()

Returns the number of child tokens of the given element in this stream.

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.

Parameters:

elementName - a string representing the name of the element for which the number of children are to be determined.

Returns:

a long integer giving the number of children of the elementName specified.

Note:

This method assumes the stream has been read up to and including the element elementName.

Documentation note:

The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

determineNumSpecificChildren

public long determineNumSpecificChildren(java.lang.String childName,
                                         java.lang.String container)

Returns the number of child tokens of the specified type 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 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.

Parameters:

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.

Returns:

a long integer giving the number of children of type childName within the container element.

Note:

This method assumes the stream has been read up to and including the element container.

containsChild

public boolean containsChild(java.lang.String childName,
                             java.lang.String container)

Predicate returning 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.

Parameters:

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.

Returns:

boolean true if a child of type childName occurs within the container element, false otherwise.

Note:

This method assumes the stream has been read up to and including the element container.