public class XMLOutputStream 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.
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.
XMLOutputStream
provides a wrapper above output streams to facilitate
writing XML. XMLOutputStream
keeps track of start and end elements,
indentation, XML namespace prefixes, and more. The interface provides
features for converting non-text data types into appropriate textual form
this takes the form of overloaded writeAttribute(...)
methods
that allow users to simply use the same method with any data type. For
example, suppose an element testElement
has two attributes, size
and
id
, and the attributes are variables in your code as follows:
double size = 3.2 String id = 'id'
Then, the element and the attributes can be written to the
standard output stream (provided as cout
in the libSBML
language bindings) as follows:
import org.sbml.libsbml.XMLOutputStream import org.sbml.libsbml.libsbml public class test { public static void main (String[] args) { double size = 3.2 String id = 'id' // Create anXMLOutputStream
object that will write to the // standard output stream, which is provide in libSBML's // Java language interface as the object 'libsbml.cout'.XMLOutputStream
xos = newXMLOutputStream
(libsbml.cout) // Create the start element, write the attributes, and close // the element. The output will be written immediately as // each method is called. xos.startElement('testElement') xos.writeAttribute('size', size) xos.writeAttribute('id', id) xos.endElement('testElement') } static { System.loadLibrary('sbmlj') } }
Other classes in SBML take XMLOutputStream
objects as arguments, and use
that to write elements and attributes seamlessly to the XML output stream.
It is also worth noting that unlike XMLInputStream
, XMLOutputStream
is
actually independent of the underlying XML parsers. It does not use the
XML parser libraries at all.
XMLInputStream
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 |
---|
XMLOutputStream(OStream stream)
Creates a new
XMLOutputStream that wraps the given stream . |
XMLOutputStream(OStream stream,
java.lang.String encoding)
Creates a new
XMLOutputStream that wraps the given stream . |
XMLOutputStream(OStream stream,
java.lang.String encoding,
boolean writeXMLDecl)
Creates a new
XMLOutputStream that wraps the given stream . |
XMLOutputStream(OStream stream,
java.lang.String encoding,
boolean writeXMLDecl,
java.lang.String programName)
Creates a new
XMLOutputStream that wraps the given stream . |
XMLOutputStream(OStream stream,
java.lang.String encoding,
boolean writeXMLDecl,
java.lang.String programName,
java.lang.String programVersion)
Creates a new
XMLOutputStream that wraps the given stream . |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Explicitly deletes the underlying native object.
|
void |
downIndent()
Decreases the indentation level for this
XMLOutputStream . |
void |
endElement(java.lang.String name)
Writes the given XML end element name to this
XMLOutputStream . |
void |
endElement(java.lang.String name,
java.lang.String prefix)
Writes the given XML end element name to this
XMLOutputStream . |
void |
endElement(XMLTriple triple)
Writes the given element to the stream.
|
boolean |
equals(java.lang.Object sb)
Equality comparison method for XMLOutputStream.
|
static java.lang.String |
getLibraryName()   |
static java.lang.String |
getLibraryVersion()   |
SBMLNamespaces |
getSBMLNamespaces()
Returns the
SBMLNamespaces object attached to this output stream. |
static boolean |
getWriteComment()   |
static boolean |
getWriteTimestamp()   |
int |
hashCode()
Returns a hashcode for this XMLOutputStream object.
|
void |
setAutoIndent(boolean indent)
Turns automatic indentation on or off for this
XMLOutputStream . |
static void |
setLibraryName(java.lang.String libraryName)
sets the name of the library writing the XML
|
static void |
setLibraryVersion(java.lang.String libraryVersion)
sets the name of the library writing the output
|
void |
setSBMLNamespaces(SBMLNamespaces sbmlns)
Sets the
SBMLNamespaces object associated with this output stream. |
static void |
setWriteComment(boolean writeComment)
sets a flag, whether the output stream will write an XML
comment at the top of the file.
|
static void |
setWriteTimestamp(boolean writeTimestamp)
sets a flag, whether the output stream will write an XML
comment with a timestamp at the top of the file.
|
void |
startElement(java.lang.String name)
Writes the given XML start element name to this
XMLOutputStream . |
void |
startElement(java.lang.String name,
java.lang.String prefix)
Writes the given XML start element name to this
XMLOutputStream . |
void |
startElement(XMLTriple triple)
Writes the given XML start element
prefix:name on this output stream. |
void |
startEndElement(java.lang.String name)
Writes the given XML start and end element name to this
XMLOutputStream . |
void |
startEndElement(java.lang.String name,
java.lang.String prefix)
Writes the given XML start and end element name to this
XMLOutputStream . |
void |
startEndElement(XMLTriple triple)
Writes the given start element to this output stream.
|
void |
upIndent()
Increases the indentation level for this
XMLOutputStream . |
void |
writeAttribute(java.lang.String name,
boolean value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(java.lang.String name,
double value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(java.lang.String name,
int value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String prefix,
boolean value)
Writes the given namespace-prefixed attribute value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String prefix,
double value)
Writes the given namespace-prefixed attribute value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String prefix,
int value)
Writes the given namespace-prefixed attribute value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String prefix,
long value)
Writes the given namespace-prefixed attribute value to this output stream.
|
void |
writeAttribute(java.lang.String name,
java.lang.String prefix,
java.lang.String value)
Writes the given namespace-prefixed attribute value to this output stream.
|
void |
writeAttribute(XMLTriple triple,
boolean value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(XMLTriple triple,
double value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(XMLTriple triple,
int value)
Writes the given attribute and value to this output stream.
|
void |
writeAttribute(XMLTriple triple,
java.lang.String value)
Writes the given attribute and value to this output stream.
|
void |
writeComment(java.lang.String programName,
java.lang.String programVersion)
Writes an XML comment with the name and version of this program.
|
void |
writeComment(java.lang.String programName,
java.lang.String programVersion,
boolean writeTimestamp)
Writes an XML comment with the name and version of this program.
|
void |
writeXMLDecl()
Writes a standard XML declaration to this output stream.
|
public XMLOutputStream(OStream stream, java.lang.String encoding, boolean writeXMLDecl, java.lang.String programName, java.lang.String programVersion) throws XMLConstructorException
XMLOutputStream
that wraps the given stream
.
The functionality associated with the programName
and
programVersion
arguments concerns an optional comment that libSBML can
write at the beginning of the output stream. The comment is intended
for human readers of the XML file, and has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
stream
- the input stream to wrap.
encoding
- the XML encoding to declare in the output. This value
should be 'UTF-8'
for SBML documents. The default value
is 'UTF-8'
if no value is supplied for this parameter.
writeXMLDecl
- whether to write a standard XML declaration at
the beginning of the content written on stream
. The default is
true.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
XMLConstructorException
public XMLOutputStream(OStream stream, java.lang.String encoding, boolean writeXMLDecl, java.lang.String programName) throws XMLConstructorException
XMLOutputStream
that wraps the given stream
.
The functionality associated with the programName
and
programVersion
arguments concerns an optional comment that libSBML can
write at the beginning of the output stream. The comment is intended
for human readers of the XML file, and has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
stream
- the input stream to wrap.
encoding
- the XML encoding to declare in the output. This value
should be 'UTF-8'
for SBML documents. The default value
is 'UTF-8'
if no value is supplied for this parameter.
writeXMLDecl
- whether to write a standard XML declaration at
the beginning of the content written on stream
. The default is
true.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
XMLConstructorException
public XMLOutputStream(OStream stream, java.lang.String encoding, boolean writeXMLDecl) throws XMLConstructorException
XMLOutputStream
that wraps the given stream
.
The functionality associated with the programName
and
programVersion
arguments concerns an optional comment that libSBML can
write at the beginning of the output stream. The comment is intended
for human readers of the XML file, and has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
stream
- the input stream to wrap.
encoding
- the XML encoding to declare in the output. This value
should be 'UTF-8'
for SBML documents. The default value
is 'UTF-8'
if no value is supplied for this parameter.
writeXMLDecl
- whether to write a standard XML declaration at
the beginning of the content written on stream
. The default is
true.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
XMLConstructorException
public XMLOutputStream(OStream stream, java.lang.String encoding) throws XMLConstructorException
XMLOutputStream
that wraps the given stream
.
The functionality associated with the programName
and
programVersion
arguments concerns an optional comment that libSBML can
write at the beginning of the output stream. The comment is intended
for human readers of the XML file, and has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
stream
- the input stream to wrap.
encoding
- the XML encoding to declare in the output. This value
should be 'UTF-8'
for SBML documents. The default value
is 'UTF-8'
if no value is supplied for this parameter.
writeXMLDecl
- whether to write a standard XML declaration at
the beginning of the content written on stream
. The default is
true.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
XMLConstructorException
public XMLOutputStream(OStream stream) throws XMLConstructorException
XMLOutputStream
that wraps the given stream
.
The functionality associated with the programName
and
programVersion
arguments concerns an optional comment that libSBML can
write at the beginning of the output stream. The comment is intended
for human readers of the XML file, and has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
stream
- the input stream to wrap.
encoding
- the XML encoding to declare in the output. This value
should be 'UTF-8'
for SBML documents. The default value
is 'UTF-8'
if no value is supplied for this parameter.
writeXMLDecl
- whether to write a standard XML declaration at
the beginning of the content written on stream
. The default is
true.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
XMLConstructorException
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 XMLOutputStream.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 XMLOutputStream.delete()
themselves.
public boolean equals(java.lang.Object sb)
Because the Java methods for libSBML are actually wrappers around code
implemented in C++ and C, certain operations will not behave as
expected. Equality comparison is one such case. An instance of a
libSBML object class is actually a proxy object
wrapping the real underlying C/C++ object. The normal ==
equality operator in Java will only compare the Java proxy objects,
not the underlying native object. The result is almost never what you
want in practical situations. Unfortunately, Java does not provide a
way to override ==
.
The alternative that must be followed is to use the
equals()
method. The equals
method on this
class overrides the default java.lang.Object one, and performs an
intelligent comparison of instances of objects of this class. The
result is an assessment of whether two libSBML Java objects are truly
the same underlying native-code objects.
The use of this method in practice is the same as the use of any other
Java equals
method. For example,
a.equals(
b)
returns
true
if a and b are references to the
same underlying object.
equals
 in class java.lang.Object
sb
- a reference to an object to which the current object
instance will be comparedtrue
if sb
refers to the same underlying
native object as this one, false
otherwisepublic int hashCode()
hashCode
 in class java.lang.Object
public void endElement(java.lang.String name, java.lang.String prefix)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void endElement(java.lang.String name)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void endElement(XMLTriple triple)
triple
- the XML element to write.public void setAutoIndent(boolean indent)
XMLOutputStream
.
indent
- if true
, automatic indentation is turned on.public void startElement(java.lang.String name, java.lang.String prefix)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void startElement(java.lang.String name)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void startElement(XMLTriple triple)
prefix:name
on this output stream.
triple
- the start element to write.public void startEndElement(java.lang.String name, java.lang.String prefix)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void startEndElement(java.lang.String name)
XMLOutputStream
.
name
- the name of the element.
prefix
- an optional XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.)
public void startEndElement(XMLTriple triple)
triple
- the XML element to write.public void writeAttribute(java.lang.String name, java.lang.String value)
name
- the name of the attribute.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, java.lang.String prefix, java.lang.String value)
name
- the name of the attribute.
prefix
- an XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.) See other versions of
this method for a variant that does not require a prefix.
value
- the value of the attribute.public void writeAttribute(XMLTriple triple, java.lang.String value)
triple
- the attribute, in the form of an XMLTriple
.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, boolean value)
name
- the name of the attribute.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, java.lang.String prefix, boolean value)
name
- the name of the attribute.
prefix
- an XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.) See other versions of
this method for a variant that does not require a prefix.
value
- the value of the attribute.public void writeAttribute(XMLTriple triple, boolean value)
triple
- the attribute, in the form of an XMLTriple
.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, double value)
name
- the name of the attribute.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, java.lang.String prefix, double value)
name
- the name of the attribute.
prefix
- an XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.) See other versions of
this method for a variant that does not require a prefix.
value
- the value of the attribute.public void writeAttribute(XMLTriple triple, double value)
triple
- the attribute, in the form of an XMLTriple
.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, int value)
name
- the name of the attribute.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, java.lang.String prefix, int value)
name
- the name of the attribute.
prefix
- an XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.) See other versions of
this method for a variant that does not require a prefix.
value
- the value of the attribute.public void writeAttribute(XMLTriple triple, int value)
triple
- the attribute, in the form of an XMLTriple
.
value
- the value of the attribute.public void writeAttribute(java.lang.String name, java.lang.String prefix, long value)
name
- the name of the attribute.
prefix
- an XML namespace prefix to write in front of the
element
name. (The result has the form
prefix:name
.) See other versions of
this method for a variant that does not require a prefix.
value
- the value of the attribute.public void writeXMLDecl()
The XML declaration has the form
<?xml version='1.0' encoding='UTF-8'?>Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.
public void writeComment(java.lang.String programName, java.lang.String programVersion, boolean writeTimestamp)
The XML comment has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
See the class constructor for more information about this program comment.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
writeTimestamp
- an optional flag indicating that a timestamp should
be writtenpublic void writeComment(java.lang.String programName, java.lang.String programVersion)
The XML comment has the following form:
<!-- Created by <program name> version <program version> on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->
See the class constructor for more information about this program comment.
programName
- an optional program name to write as a comment
in the output stream.
programVersion
- an optional version identification string to write
as a comment in the output stream.
writeTimestamp
- an optional flag indicating that a timestamp should
be writtenpublic void downIndent()
XMLOutputStream
.
LibSBML tries to produce human-readable XML output by automatically
indenting the bodies of elements. Callers can manually control
indentation further by using the XMLOutputStream.upIndent()
and XMLOutputStream.downIndent()
methods to increase and
decrease, respectively, the current level of indentation in the
XML output.
XMLOutputStream.upIndent()
public void upIndent()
XMLOutputStream
.
LibSBML tries to produce human-readable XML output by automatically
indenting the bodies of elements. Callers can manually control
indentation further by using the XMLOutputStream.upIndent()
and XMLOutputStream.downIndent()
methods to increase and
decrease, respectively, the current level of indentation in the
XML output.
XMLOutputStream.downIndent()
public SBMLNamespaces getSBMLNamespaces()
SBMLNamespaces
object attached to this output stream.
SBMLNamespaces
object, or null
if none has been set.public void setSBMLNamespaces(SBMLNamespaces sbmlns)
SBMLNamespaces
object associated with this output stream.
sbmlns
- the namespace object.public static boolean getWriteComment()
public static void setWriteComment(boolean writeComment)
writeComment
- the flagpublic static boolean getWriteTimestamp()
public static void setWriteTimestamp(boolean writeTimestamp)
writeTimestamp
- the flagpublic static java.lang.String getLibraryName()
public static void setLibraryName(java.lang.String libraryName)
libraryName
- the name of the library to be used in commentspublic static java.lang.String getLibraryVersion()
public static void setLibraryVersion(java.lang.String libraryVersion)
libraryVersion
- the version information as string