public class XMLNode extends XMLToken
LibSBML implements an XML abstraction layer. This layer presents a
uniform XML interface to calling programs regardless of which underlying
XML parser libSBML has actually been configured to use. The basic data
object in the XML abstraction is a node, represented by XMLNode
.
An XMLNode
can contain any number of children. Each child is another
XMLNode
, thereby forming a tree. The methods XMLNode.getNumChildren()
and XMLNode.getChild(long)
can be used to access the tree
structure starting from a given node.
Each XMLNode
is subclassed from XMLToken
, and thus has the same methods
available as XMLToken
. These methods include XMLToken.getNamespaces()
,
XMLToken.getPrefix()
, XMLToken.getName()
, XMLToken.getURI()
, and
XMLToken.getAttributes()
.
XMLNode
LibSBML provides the following utility functions for converting an XML
string (e.g., <annotation>...</annotation>
)
to/from an XMLNode
object.
XMLNode.toXMLString()
returns a string representation of the XMLNode
object.
XMLNode.convertXMLNodeToString(XMLNode)
(static
function) returns a string representation of the given XMLNode
object.
XMLNode.convertStringToXMLNode(String)
(static
function) returns an XMLNode
object converted from the given XML string.
The returned XMLNode
object by XMLNode.convertStringToXMLNode(String)
is a dummy root (container) XMLNode
if the given XML string
has two or more top-level elements (e.g.,
"<p>...</p><p>...</p>
"). In
the dummy root node, each top-level element in the given XML string is
contained as a child XMLNode
. XMLToken.isEOF()
can be used to identify
if the returned XMLNode
object is a dummy node or not. Here is an
example:
// Checks if the returnedXMLNode
object is a dummy root node: String str = '...'XMLNode
xn =XMLNode
.convertStringToXMLNode(str) if ( xn == null ) { // returned value is null (error) ... } else if ( xn.isEOF() ) { // Root node is a dummy node. for ( int i = 0 i < xn.getNumChildren() i++ ) { // access to each child node of the dummy node.XMLNode
xnChild = xn.getChild(i) ... } } else { // Root node is NOT a dummy node. ... }
Constructor and Description |
---|
XMLNode()
Creates a new empty
XMLNode with no children. |
XMLNode(String chars)
Creates a text
XMLNode . |
XMLNode(String chars,
long line)
Creates a text
XMLNode . |
XMLNode(String chars,
long line,
long column)
Creates a text
XMLNode . |
XMLNode(XMLNode orig)
Copy constructor creates a copy of this
XMLNode . |
XMLNode(XMLToken token)
|
XMLNode(XMLTriple triple)
Creates an end element
XMLNode . |
XMLNode(XMLTriple triple,
long line)
Creates an end element
XMLNode . |
XMLNode(XMLTriple triple,
long line,
long column)
Creates an end element
XMLNode . |
XMLNode(XMLTriple triple,
XMLAttributes attributes)
Creates a start element
XMLNode with the given set of attributes. |
XMLNode(XMLTriple triple,
XMLAttributes attributes,
long line)
Creates a start element
XMLNode with the given set of attributes. |
XMLNode(XMLTriple triple,
XMLAttributes attributes,
long line,
long column)
Creates a start element
XMLNode with the given set of attributes. |
XMLNode(XMLTriple triple,
XMLAttributes attributes,
XMLNamespaces namespaces)
Creates a new start element
XMLNode with the given set of attributes and
namespace declarations. |
XMLNode(XMLTriple triple,
XMLAttributes attributes,
XMLNamespaces namespaces,
long line)
Creates a new start element
XMLNode with the given set of attributes and
namespace declarations. |
XMLNode(XMLTriple triple,
XMLAttributes attributes,
XMLNamespaces namespaces,
long line,
long column)
Creates a new start element
XMLNode with the given set of attributes and
namespace declarations. |
Modifier and Type | Method and Description |
---|---|
int |
addChild(XMLNode node)
Adds a copy of
node as a child of this XMLNode . |
XMLNode |
cloneObject()
Creates and returns a deep copy of this
XMLNode object. |
static XMLNode |
convertStringToXMLNode(String xmlstr)
Returns an
XMLNode which is derived from a string containing XML
content. |
static XMLNode |
convertStringToXMLNode(String xmlstr,
XMLNamespaces xmlns)
Returns an
XMLNode which is derived from a string containing XML
content. |
static String |
convertXMLNodeToString(XMLNode node)
Returns a string representation of a given
XMLNode . |
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(Object sb)
Equality comparison method for XMLNode.
|
XMLNode |
getChild(long n)
Returns the
n th child of this XMLNode . |
XMLNode |
getChild(String name)
Returns the first child of this
XMLNode with the corresponding name. |
int |
getIndex(String name)
Return the index of the first child of this
XMLNode with the given name. |
long |
getNumChildren()
Returns the number of children for this
XMLNode . |
boolean |
hasChild(String name)
Return a boolean indicating whether this
XMLNode has a child with the
given name. |
int |
hashCode()
Returns a hashcode for this XMLNode object.
|
XMLNode |
insertChild(long n,
XMLNode node)
Inserts a copy of the given node as the
n th child of this
XMLNode . |
XMLNode |
removeChild(long n)
Removes the
n th child of this XMLNode and returns the
removed node. |
int |
removeChildren()
Removes all children from this node.
|
String |
toXMLString()
Returns a string representation of this
XMLNode . |
boolean |
xmlEquals(XMLNode other)
|
boolean |
xmlEquals(XMLNode other,
boolean ignoreURI)
|
addAttr, addAttr, addAttr, addAttr, addNamespace, addNamespace, append, clearAttributes, clearNamespaces, getAttributes, getAttributesLength, getAttrIndex, getAttrIndex, getAttrIndex, getAttrName, getAttrPrefix, getAttrPrefixedName, getAttrURI, getAttrValue, getAttrValue, getAttrValue, getAttrValue, getCharacters, getColumn, getLine, getName, getNamespaceIndex, getNamespaceIndexByPrefix, getNamespacePrefix, getNamespacePrefix, getNamespaces, getNamespacesLength, getNamespaceURI, getNamespaceURI, getNamespaceURI, getPrefix, getURI, hasAttr, hasAttr, hasAttr, hasAttr, hasNamespaceNS, hasNamespacePrefix, hasNamespaceURI, isAttributesEmpty, isElement, isEnd, isEndFor, isEOF, isNamespacesEmpty, isStart, isText, removeAttr, removeAttr, removeAttr, removeAttr, removeNamespace, removeNamespace, setAttributes, setEnd, setEOF, setNamespaces, setTriple, toString, unsetEnd
public XMLNode() throws XMLConstructorException
XMLNode
with no children.XMLConstructorException
public XMLNode(XMLToken token) throws XMLConstructorException
token
- XMLToken
to be copied to XMLNode
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line, long column) throws XMLConstructorException
XMLNode
with the given set of attributes and
namespace declarations.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.namespaces
- XMLNamespaces
, the namespaces to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line) throws XMLConstructorException
XMLNode
with the given set of attributes and
namespace declarations.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.namespaces
- XMLNamespaces
, the namespaces to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces) throws XMLConstructorException
XMLNode
with the given set of attributes and
namespace declarations.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.namespaces
- XMLNamespaces
, the namespaces to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes, long line, long column) throws XMLConstructorException
XMLNode
with the given set of attributes.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes, long line) throws XMLConstructorException
XMLNode
with the given set of attributes.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, XMLAttributes attributes) throws XMLConstructorException
XMLNode
with the given set of attributes.
triple
- XMLTriple
.attributes
- XMLAttributes
, the attributes to set.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, long line, long column) throws XMLConstructorException
XMLNode
.
triple
- XMLTriple
.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple, long line) throws XMLConstructorException
XMLNode
.
triple
- XMLTriple
.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLTriple triple) throws XMLConstructorException
XMLNode
.
triple
- XMLTriple
.line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(String chars, long line, long column) throws XMLConstructorException
XMLNode
.
chars
- a string, the text to be added to the XMLToken
line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(String chars, long line) throws XMLConstructorException
XMLNode
.
chars
- a string, the text to be added to the XMLToken
line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(String chars) throws XMLConstructorException
XMLNode
.
chars
- a string, the text to be added to the XMLToken
line
- a long integer, the line number (default = 0).column
- a long integer, the column number (default = 0).
XMLConstructorException
public XMLNode(XMLNode orig) throws XMLConstructorException
XMLNode
.
orig
- the XMLNode
instance to copy.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 XMLNode.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 XMLNode.delete()
themselves.
public boolean equals(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.
public int hashCode()
public XMLNode cloneObject()
XMLNode
object.
cloneObject
 in class XMLToken
XMLNode
object.public int addChild(XMLNode node)
node
as a child of this XMLNode
.
The given node
is added at the end of the list of children.
node
- the XMLNode
to be added as child.
public XMLNode insertChild(long n, XMLNode node)
n
th child of this
XMLNode
.
If the given index n
is out of range for this XMLNode
instance,
the node
is added at the end of the list of children. Even in
that situation, this method does not throw an error.
n
- an integer, the index at which the given node is insertednode
- an XMLNode
to be inserted as n
th child.
node
public XMLNode removeChild(long n)
n
th child of this XMLNode
and returns the
removed node.
It is important to keep in mind that a given XMLNode
may have more
than one child. Calling this method erases all existing references to
child nodes after the given position n
. If the index n
is
greater than the number of child nodes in this XMLNode
, this method
takes no action (and returns null
).
n
- an integer, the index of the node to be removed
null
if n
is greater than the number
of children in this node
public int removeChildren()
public XMLNode getChild(long n)
n
th child of this XMLNode
.
If the index n
is greater than the number of child nodes,
this method returns an empty node.
n
- a long integereger, the index of the node to return
n
th child of this XMLNode
.public XMLNode getChild(String name)
XMLNode
with the corresponding name.
If no child with corrsponding name can be found, this method returns an empty node.
name
- the name of the node to return
XMLNode
with given name.public int getIndex(String name)
XMLNode
with the given name.
name
- a string, the name of the child for which the
index is required.
XMLNode
with the given
name, or -1 if not present.public boolean hasChild(String name)
XMLNode
has a child with the
given name.
name
- a string, the name of the child to be checked.
XMLNode
has a child with the
given name.public long getNumChildren()
XMLNode
.
XMLNode
.public String toXMLString()
XMLNode
.
XMLNode
.public static String convertXMLNodeToString(XMLNode node)
XMLNode
.
node
- the XMLNode
to be represented as a string
node
public static XMLNode convertStringToXMLNode(String xmlstr, XMLNamespaces xmlns)
XMLNode
which is derived from a string containing XML
content.
The XML namespace must be defined using argument xmlns
if the
corresponding XML namespace attribute is not part of the string of the
first argument.
xmlstr
- string to be converted to a XML node.xmlns
- XMLNamespaces
the namespaces to set (default value is null
).
XMLNode
which is converted from string xmlstr
. If the
conversion failed, this method returns null.
XMLNode
and is reponsible for
deleting it. The returned XMLNode
object is a dummy root (container)
XMLNode
if the top-level element in the given XML string is NOT
<html>
, <body>
,
<annotation>
, or <notes>
. In
the dummy root node, each top-level element in the given XML string is
contained as a child XMLNode
. XMLToken.isEOF()
can be used to
identify if the returned XMLNode
object is a dummy node.
public static XMLNode convertStringToXMLNode(String xmlstr)
XMLNode
which is derived from a string containing XML
content.
The XML namespace must be defined using argument xmlns
if the
corresponding XML namespace attribute is not part of the string of the
first argument.
xmlstr
- string to be converted to a XML node.xmlns
- XMLNamespaces
the namespaces to set (default value is null
).
XMLNode
which is converted from string xmlstr
. If the
conversion failed, this method returns null.
XMLNode
and is reponsible for
deleting it. The returned XMLNode
object is a dummy root (container)
XMLNode
if the top-level element in the given XML string is NOT
<html>
, <body>
,
<annotation>
, or <notes>
. In
the dummy root node, each top-level element in the given XML string is
contained as a child XMLNode
. XMLToken.isEOF()
can be used to
identify if the returned XMLNode
object is a dummy node.