org.sbml.jsbml.xml

Class XMLNode

java.lang.Object

org.sbml.jsbml.AbstractTreeNode

org.sbml.jsbml.xml.XMLToken

org.sbml.jsbml.xml.XMLNode

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, javax.swing.tree.TreeNode, TreeNodeWithChangeSupport

public class XMLNode
extends XMLToken

Representation of a node in an XML document tree.

Beginning with version 1.0, JSBML implements an XML abstraction layer, like LibSBML. 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 getChildCount() and getChildAt(int) 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().

Conversion between an XML String and an XMLNode

JSBML provides the following utility functions for converting an XML String (e.g., <annotation>...</annotation>) to/from an XMLNode object.

• toXMLString() returns a String representation of the XMLNode object.
• convertXMLNodeToString(XMLNode) (static function) returns a String representation of the given XMLNode object.
• convertStringToXMLNode(String) (static function) returns an XMLNode object converted from the given XML String.

The returned XMLNode object by 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 returned XMLNode object by convertStringToXMLNode(String) 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 $lt; xn.getChildCount(); i++) {
     // access to each child node of the dummy node.
     XMLNode xnChild = xn.getChild(i);
     // ...
   }
 } else {
   // root node is NOT a dummy node
   // ...
 }
 

Since:

0.8

Author:

Nicolas Rodriguez

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.List<XMLNode>	childElements
private static SBMLReader	notesReader This reader is used to parse all notes-Strings.
private static long	serialVersionUID Generated serial version identifier

Fields inherited from class org.sbml.jsbml.xml.XMLToken

attributes, characters, column, isEndElement, isEOF, isStartElement, isText, line, namespaces, triple

Fields inherited from class org.sbml.jsbml.AbstractTreeNode

listOfListeners, parent, resourceBundle

Constructor Summary

Constructors

Constructor and Description
XMLNode() Creates a new empty XMLNode with no children.
XMLNode(java.lang.String chars) Creates a text XMLNode.
XMLNode(java.lang.String chars, long line) Creates a text XMLNode.
XMLNode(java.lang.String chars, long line, long column) Creates a text XMLNode.
XMLNode(XMLNode orig) Creates a copy of this XMLNode.
XMLNode(XMLToken orig) Creates a new XMLNode by copying 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.

Method Summary

Modifier and Type	Method and Description
int	addChild(XMLNode node) Adds a child to this XMLNode.
XMLNode	clone()
static XMLNode	convertStringToXMLNode(java.lang.String xmlstr) Returns an XMLNode which is derived from a String containing XML content.
static XMLNode	convertStringToXMLNode(java.lang.String xmlstr, XMLNamespaces xmlns) Returns an XMLNode which is derived from a string containing XML content.
static java.lang.String	convertXMLNodeToString(XMLNode node) Returns a string representation of a given XMLNode.
boolean	getAllowsChildren()
XMLNode	getChild(int childIndex) Returns the child XMLNode at index childIndex.
XMLNode	getChildAt(int childIndex)
int	getChildCount()
XMLNode	getChildElement(java.lang.String elementName, java.lang.String elementURI) Gets the first direct child element of this XMLNode with the given local name and namespace.
java.util.List<XMLNode>	getChildElements(java.lang.String elementName, java.lang.String elementURI) Gets all the direct children of this XMLNode with the given local name and namespace.
XMLNode	insertChild(int n, XMLNode node) Inserts a node as the nth child of this XMLNode.
XMLNode	removeChild(int n) Removes the nth child of this XMLNode and returns the removed node.
boolean	removeChild(XMLNode xmlNode) Removes the first occurrence of the specified element from this list.
int	removeChildren() Removes all children from this node.
java.lang.String	toString()
java.lang.String	toXMLString() Returns a string representation of this XMLNode.

Methods inherited from class org.sbml.jsbml.xml.XMLToken

addAttr, addAttr, addAttr, addAttr, addNamespace, addNamespace, append, clearAttributes, clearNamespaces, equals, 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, hashCode, hasNamespaceNS, hasNamespacePrefix, hasNamespaceURI, isAttributesEmpty, isElement, isEnd, isEndFor, isEOF, isNamespacesEmpty, isStart, isText, removeAttr, removeAttr, removeAttr, removeAttr, removeNamespace, removeNamespace, setAttributes, setCharacters, setEnd, setEOF, setNamespaces, setTriple, unsetEnd

Methods inherited from class org.sbml.jsbml.AbstractTreeNode

addAllChangeListeners, addAllChangeListeners, addTreeNodeChangeListener, addTreeNodeChangeListener, children, clearUserObjects, containsUserObjectKey, filter, filter, filter, fireNodeAddedEvent, fireNodeRemovedEvent, firePropertyChange, getIndex, getListOfTreeNodeChangeListeners, getNumChildren, getParent, getRoot, getTreeNodeChangeListenerCount, getUserObject, indexOf, isLeaf, isReadingInProgress, isRoot, isSetParent, isSetUserObjects, notifyChildChange, putUserObject, removeAllTreeNodeChangeListeners, removeAllTreeNodeChangeListeners, removeFromParent, removeTreeNodeChangeListener, removeTreeNodeChangeListener, removeUserObject, setParent, userObjectKeySet

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

private static final long serialVersionUID

Generated serial version identifier

See Also:

Constant Field Values

notesReader

private static SBMLReader notesReader

This reader is used to parse all notes-Strings. It takes a lot of time to re-initialize the SBMLReader every time notes are being set or appended, thus, this instance is static and should be used to parse all notes.

childElements

private java.util.List<XMLNode> childElements

Constructor Detail

XMLNode

public XMLNode()

Creates a new empty XMLNode with no children.

XMLNode

public XMLNode(java.lang.String chars)

Creates a text XMLNode.

Parameters:

chars - a string, the text to be added to the XMLToken

XMLNode

public XMLNode(java.lang.String chars,
               long line)

Creates a text XMLNode.

Parameters:

chars - a string, the text to be added to the XMLToken

line - a long integer, the line number (default = 0).

XMLNode

public XMLNode(java.lang.String chars,
               long line,
               long column)

Creates a text XMLNode.

Parameters:

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

XMLNode

public XMLNode(XMLNode orig)

Creates a copy of this XMLNode.

Parameters:

orig - the XMLNode instance to copy.

XMLNode

public XMLNode(XMLToken orig)

Creates a new XMLNode by copying token.

Parameters:

orig - XMLToken to be copied to XMLNode

XMLNode

public XMLNode(XMLTriple triple)

Creates an end element XMLNode.

Parameters:

triple - XMLTriple.

XMLNode

public XMLNode(XMLTriple triple,
               long line)

Creates an end element XMLNode.

Parameters:

triple - XMLTriple.

line - a long integer, the line number (default = 0).

XMLNode

public XMLNode(XMLTriple triple,
               long line,
               long column)

Creates an end element XMLNode.

Parameters:

triple - XMLTriple.

line - a long integer, the line number (default = 0).

column - a long integer, the column number (default = 0).

XMLNode

public XMLNode(XMLTriple triple,
               XMLAttributes attributes)

Creates a start element XMLNode with the given set of attributes.

Parameters:

triple - XMLTriple.

attributes - XMLAttributes, the attributes to set.

XMLNode

public XMLNode(XMLTriple triple,
               XMLAttributes attributes,
               long line)

Creates a start element XMLNode with the given set of attributes.

Parameters:

triple - XMLTriple.

attributes - XMLAttributes, the attributes to set.

line - a long integer, the line number (default = 0).

XMLNode

public XMLNode(XMLTriple triple,
               XMLAttributes attributes,
               long line,
               long column)

Creates a start element XMLNode with the given set of attributes.

Parameters:

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

XMLNode

public XMLNode(XMLTriple triple,
               XMLAttributes attributes,
               XMLNamespaces namespaces)

Creates a new start element XMLNode with the given set of attributes and namespace declarations.

Parameters:

triple - XMLTriple.

attributes - XMLAttributes, the attributes to set.

namespaces - XMLNamespaces, the namespaces to set.

XMLNode

public XMLNode(XMLTriple triple,
               XMLAttributes attributes,
               XMLNamespaces namespaces,
               long line)

Creates a new start element XMLNode with the given set of attributes and namespace declarations.

Parameters:

triple - XMLTriple.

attributes - XMLAttributes, the attributes to set.

namespaces - XMLNamespaces, the namespaces to set.

line - a long integer, the line number (default = 0).

XMLNode

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

Parameters:

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

Method Detail

convertStringToXMLNode

public static XMLNode convertStringToXMLNode(java.lang.String xmlstr)
                                      throws javax.xml.stream.XMLStreamException

Returns an 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.

Parameters:

xmlstr - String to be converted to a XML node.

Returns:

a XMLNode which is converted from string xmlstr. null is returned if the conversion failed.

Throws:

javax.xml.stream.XMLStreamException

convertStringToXMLNode

public static XMLNode convertStringToXMLNode(java.lang.String xmlstr,
                                             XMLNamespaces xmlns)

Returns an 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.

Parameters:

xmlstr - string to be converted to a XML node.

xmlns - XMLNamespaces the namespaces to set (default value is null). This argument is ignored at the moment.

Returns:

a XMLNode which is converted from string xmlstr. null is returned if the conversion failed.

convertXMLNodeToString

public static java.lang.String convertXMLNodeToString(XMLNode node)
                                               throws javax.xml.stream.XMLStreamException

Returns a string representation of a given XMLNode.

Parameters:

node - the XMLNode to be represented as a string

Returns:

a string-form representation of node

Throws:

javax.xml.stream.XMLStreamException

addChild

public int addChild(XMLNode node)

Adds a child to this XMLNode.

The given node is added at the end of the list of children.

Parameters:

node - the XMLNode to be added as child.

Returns:

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

• JSBML#OPERATION_SUCCESS
• JSBML#OPERATION_FAILED

clone

public XMLNode clone()

Specified by:

clone in class XMLToken

getAllowsChildren

public boolean getAllowsChildren()

getChildAt

public XMLNode getChildAt(int childIndex)

getChild

public XMLNode getChild(int childIndex)

Returns the child XMLNode at index childIndex.

Parameters:

childIndex - the index.

Returns:

the child XMLNode at index childIndex.

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

getChildCount

public int getChildCount()

insertChild

public XMLNode insertChild(int n,
                           XMLNode node)

Inserts a node as the nth 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.

Parameters:

n - an integer, the index at which the given node is inserted

node - an XMLNode to be inserted as nth child.

Returns:

a reference to the newly-inserted child node

removeChild

public XMLNode removeChild(int n)

Removes the nth 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).

Parameters:

n - an integer, the index of the node to be removed

Returns:

the removed child, or null if n is greater than the number of children in this node

removeChildren

public int removeChildren()

Removes all children from this node.

Returns:

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

• JSBML#OPERATION_SUCCESS

toString

public java.lang.String toString()

Overrides:

toString in class AbstractTreeNode

toXMLString

public java.lang.String toXMLString()
                             throws javax.xml.stream.XMLStreamException

Returns a string representation of this XMLNode.

Returns:

a string derived from this XMLNode.

Throws:

javax.xml.stream.XMLStreamException - if an error occurs while writing the XMLNode to String.

removeChild

public boolean removeChild(XMLNode xmlNode)

Removes the first occurrence of the specified element from this list.

If this list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o == null ? get(i) == null : o.equals(get(i))) (if such an element exists). Returns true if this list contained the specified element (or equivalently, if this list changed as a result of the call).

Parameters:

xmlNode -

Returns:

true if the XMLNode was found and removed.

getChildElement

public XMLNode getChildElement(java.lang.String elementName,
                               java.lang.String elementURI)

Gets the first direct child element of this XMLNode with the given local name and namespace.

If null or an empty String is given for either the elementName or the elementURI, it is interpreted as any name or namespace. This is the same as passing the special value "*".

Parameters:

elementName - - The local name of the elements to match on. The special value "*" matches all local names.

elementURI - - The namespace URI of the elements to match on. The special value "*" matches all namespaces.

Returns:

the first direct child of this XMLNode with the given local name and namespace or null if no match found.

getChildElements

public java.util.List<XMLNode> getChildElements(java.lang.String elementName,
                                                java.lang.String elementURI)

Gets all the direct children of this XMLNode with the given local name and namespace.

If null or an empty String is given for either the elementName or the elementURI, it is interpreted as any name or namespace. This is the same as passing the special value "*".

Parameters:

elementName - - The local name of the elements to match on. The special value "*" matches all local names.

elementURI - - The namespace URI of the elements to match on. The special value "*" matches all namespaces.

Returns:

all the direct children of this XMLNode with the given local name and namespace or an empty List if not match were found.