fr.gael.drb.impl.xml
Class XmlNode

java.lang.Object
  fr.gael.drb.DrbDefaultNodesChangeProducer
      fr.gael.drb.DrbAbstractNode
          fr.gael.drb.impl.DrbNodeImpl
              fr.gael.drb.impl.xml.XmlNode

All Implemented Interfaces:

DrbMutableNode, DrbNode, DrbNodesChangeListener, DrbNodesChangeProducer, EventListener

public class XmlNode
extends DrbNodeImpl

XML node implementation. This implementation uses the DOM API provided by W3C to comply the DrbNode interface. It allows to browse the XML documents with the Data Request Broker API.

Note: the main difference between DRB API and the DOM provided by the W3C is that the children of a node cannot be notations, PI, ENTITY, attributes, etc. All the nodes corresponds to the XML markups and their content the text embedded between the markups. Attributes are supported but processing instructions, ENTITY, notation, etc. are discarded by the DRB.

Field Summary

static String	XML_NAMESPACE XML Namespace
static String	XML_PREFIX XML Prefix
static String	XMLNS_NAMESPACE XMLNS Namespace
static String	XMLNS_PREFIX XMLNS Prefix

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Constructor Summary

XmlNode(InputStream input_stream, DrbNode base_node)
Deprecated. As of DRB 2.2, added the XmlDocument class.

XmlNode(Node node)
Deprecated. As of DRB 2.2, added the XmlDocument class.

XmlNode(Node node, DrbNode base_node)
Deprecated. As of DRB 2.2, added the XmlDocument class.

XmlNode(Reader reader, DrbNode base_node)
Deprecated. As of DRB 2.2, added the XmlDocument class.

XmlNode(String xml_string)
Deprecated. As of DRB 2.2, added the XmlDocument class.

Method Summary

boolean	allowsMultiOccurrence() Check if this node may have multiple occurrence
DrbNode	appendChild(DrbNode nodes) Appends a child at the end of the children list.
boolean	equals(Object obj) Indicates whether this node is "equal to" to another node.
void	flush() Performs any pending changes.
DrbAttributeList	getAttributes() The attributes of the current node.
DrbNode	getChildAt(int index) The child located at a specific position.
DrbNodeList	getChildren() The children of the current node.
int	getChildrenCount() Number of children.
DrbSequence	getContent() The content of the current node.
DrbNode	getFirstChild() The first child of the current node.
int	getIndex() The index of the node in the parent children list.
DrbNode	getLastChild() The last child of the curren node.
String	getName() The name of the node.
DrbNode	getNamedChild(String name, int occurence) Returns an occurence of child matching a specific name.
Namespace	getNamespaceBindings() Get the namespace bindings.
String	getNamespaceURI() The namespace URI of the XML node.
DrbNode	getNextSibling() The next sibling of the current node.
int	getOccurrence() Occurrence of the node.
DrbNode	getParent() The parent of the current node.
DrbNode	getPreviousSibling() The previous sibling of the current node.
DrbNode	getRoot() The root node of the XML node.
Value	getValue() The contents of the current node.
int	getValueType() The content type of the node.
boolean	hasChild() Tests if the current node has any child.
DrbNode	insertChild(DrbNode new_node, int index) Inserts a child at a given position.
void	removeChild(int index) Removes an existing child.
void	rename(String name) Changes the name of the node.
DrbNode	replaceChild(int index, DrbNode new_node) Replaces a child of the current node.
void	setAttributes(DrbAttributeList attributes) Set the attribute list of a node.
void	setNamespaceURI(String namespace_uri) Sets a namespace resource identifier.
Value	setValue(Value value) Changes the value of the node.
String	toString() String representqtion of the object.
static String	toXML(String str) Format an XML string.

Methods inherited from class fr.gael.drb.impl.DrbNodeImpl

close, createAttribute, createNode, getImpl, getProvider, hasImpl

Methods inherited from class fr.gael.drb.DrbAbstractNode

appendReference, getAttribute, getItemType, getPath, getXPathName, getXPathName, setNamespaceBindings

Methods inherited from class fr.gael.drb.DrbDefaultNodesChangeProducer

addNodesChangeListener, getListenerList, nodesChanged, nodesInserted, nodesRemoved, removeNodesChangeListener, setListenerList, structureChanged

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

XML_NAMESPACE

public static final String XML_NAMESPACE

XML Namespace

See Also:

Constant Field Values

XML_PREFIX

public static final String XML_PREFIX

XML Prefix

See Also:

Constant Field Values

XMLNS_NAMESPACE

public static final String XMLNS_NAMESPACE

XMLNS Namespace

See Also:

Constant Field Values

XMLNS_PREFIX

public static final String XMLNS_PREFIX

XMLNS Prefix

See Also:

Constant Field Values

Constructor Detail

XmlNode

public XmlNode(Node node)

Deprecated. As of DRB 2.2, added the XmlDocument class.

Builds a new XmlNode from a DOM element. This constructor set the attribute reference to the passed DOM node. TODO : this operation shall raise an exception in case of null parameter.

Parameters:

node - The DOM element to be wrapped. This parameter shall never be null.

See Also:

XmlDocument

XmlNode

public XmlNode(InputStream input_stream,
               DrbNode base_node)

Deprecated. As of DRB 2.2, added the XmlDocument class.

Builds a new XmlNode from an InputStream. This constructor initialises a node based on the XML document encoded in the passed InputStream. TODO : this operation shall raise an exception in case of null parameter.

Parameters:

input_stream - The InputStream to build the DOM node.

base_node - A reference to a the base node of an external implementation.

See Also:

XmlDocument.XmlDocument(java.io.InputStream)

XmlNode

public XmlNode(Reader reader,
               DrbNode base_node)

Deprecated. As of DRB 2.2, added the XmlDocument class.

Builds a new XmlNode from an reader. This constructor initialises a node based on the XML document encoded in the passed InputStream. TODO : this operation shall raise an exception in case of null parameter.

Parameters:

reader - The reader to build the DOM node.

base_node - A reference to a the base node of an external implementation.

See Also:

XmlDocument.XmlDocument(java.io.Reader)

XmlNode

public XmlNode(String xml_string)

Deprecated. As of DRB 2.2, added the XmlDocument class.

Builds a new XmlNode from a String. This constructor initialises a node based on the XML document encoded in the passed string.

Parameters:

xml_string - The XML string. This parameter shall never be null.

See Also:

XmlDocument.XmlDocument(java.lang.String)

XmlNode

public XmlNode(Node node,
               DrbNode base_node)

Deprecated. As of DRB 2.2, added the XmlDocument class.

Builds a new XmlNode from a DOM node with a base node. This constructor set the attribute reference to the passed DOM node.

Parameters:

node - The DOM node to be wrapped. This parameter shall never be null.

base_node - A reference to a the base node of an external implementation.

See Also:

XmlDocument

Method Detail

equals

public boolean equals(Object obj)

Indicates whether this node is "equal to" to another node. See Object.equals() for the general contract of this method.

Overrides:

equals in class DrbAbstractNode

Parameters:

obj - another value.

Returns:

true if this object is the same as the obj argument

getName

public String getName()

The name of the node. This name is never null and correspond to the markup identifier in the XML document. For instance the markup will provide a name equal to "example".This operation extracts the name of the markup from the getLocalName() operation defined node class of DOM.

Overrides:

getName in class DrbAbstractNode

Returns:

The name of the markup node.

getIndex

public int getIndex()

The index of the node in the parent children list. This operation counts the previous sibling to retreive the index of the current node.

Overrides:

getIndex in class DrbAbstractNode

Returns:

The index of the current node.

getRoot

public DrbNode getRoot()

The root node of the XML node. The root node is the one of the underlying implementation.If the node does not belongs to a parent node, the root may not exists.

Overrides:

getRoot in class DrbAbstractNode

Returns:

A reference to the root node or null if none.

getOccurrence

public int getOccurrence()

Occurrence of the node. Returns the occurrence of the node in its parent children list. If the node has not parent the occurrence may not be available: the operation returns therefore a negative value.

Overrides:

getOccurrence in class DrbAbstractNode

Returns:

The index of the node or negative value.

allowsMultiOccurrence

public boolean allowsMultiOccurrence()

Check if this node may have multiple occurrence

Overrides:

allowsMultiOccurrence in class DrbAbstractNode

Returns:

true if the children may have a multiple occurrence and false otherwise.

getNamespaceURI

public String getNamespaceURI()

The namespace URI of the XML node. The namespace is extracted from the wrapped XML node through the DOM API

Overrides:

getNamespaceURI in class DrbAbstractNode

Returns:

The namespace URI or null if unspecified.

getValueType

public int getValueType()

The content type of the node. The type of an XML element is yet a string. See the getValue() operation for additional information about typing and values.

Overrides:

getValueType in class DrbAbstractNode

Returns:

fr.gael.drb.value.Value.STRING_ID.

getValue

public Value getValue()

The contents of the current node. The value of the node is the concatenation of the TEXT and CDATA nodes children of the current one. Actually the wrapped nodes are only element and their contents corresponds to their textual children. This operation catches all the DOM exceptions and continue its processing with only few messages printed out the standard error. Returned value are always identified by fr.gael.drb.value.Value.STRING_ID.

Overrides:

getValue in class DrbAbstractNode

Returns:

The value of the current node or null if none.

getNamespaceBindings

public Namespace getNamespaceBindings()

Get the namespace bindings.

Overrides:

getNamespaceBindings in class DrbAbstractNode

Returns:

The namespace bindings.

getAttributes

public final DrbAttributeList getAttributes()

The attributes of the current node. Scope of this function is to extract the attributes provided by the wrapped node (i.e. supported by DOM) and transform them in some item and list compliant with DRB API. Because le DOM nodes (i.e. the current is considered as an ELEMENT_NODE) have not always attributes, or because of processing errors,the list may contain less than the effective document node or this list may not exist. The operation never returns empty list but null reference. All the exceptions raised during the processing are catched but not propagated. The naming convention wihtin this source code considers the dom_attr_xxx and the attr_xxx variables. The dom_attr_xxx are the variables related to the wrapped DOM node (i.e. the one handled by DOM) and the attr_xxx deal with the DRB variable expected in output of this operation.

Overrides:

getAttributes in class DrbAbstractNode

Returns:

The list of attribute owned by the current node.

getParent

public DrbNode getParent()

The parent of the current node. This operation uses the getParentNode() provided by the DOM node. The parent may not exist for several reasons. For instance root nodes as well as just created onces have no parent node.If the current node is the root node of the XML document,the base node (the one of the underlying implementation) is returned.

Specified by:

getParent in class DrbAbstractNode

Returns:

A reference to the parent node if any or null otherwise.

getChildren

public DrbNodeList getChildren()

The children of the current node. This operation filters all the DOM children and selects only the XML ELEMENT ones. All other node types are discarded.

Specified by:

getChildren in class DrbAbstractNode

Returns:

The list of children if any or null otherwise.

getContent

public DrbSequence getContent()

The content of the current node. Returns a sequence of nodes and atomic values.

Overrides:

getContent in class DrbAbstractNode

Returns:

The content of this node.

hasChild

public boolean hasChild()

Tests if the current node has any child. This operation cannot use directly the hasChildNodes() specified by DOM because it has to count the XML ELEMENT nodes and discard all others in is accounting. The operation delegates the selection to the getChildren().

Overrides:

hasChild in class DrbAbstractNode

Returns:

true if the node has at least one ELEMENT node and false otherwise.

getNamedChild

public DrbNode getNamedChild(String name,
                             int occurence)

Returns an occurence of child matching a specific name. The occurence number starts from 1.

Overrides:

getNamedChild in class DrbAbstractNode

Parameters:

name - The name to match.

occurence - The occurence number of the desired child.

Returns:

A reference to the child or null is not found.

getFirstChild

public DrbNode getFirstChild()

The first child of the current node. This operation looks for the first occurence of ELEMENT node in the node and return it. It was not possible to use directly the getFirstChild() operation specified by DOM because it is necessary to filter the ELEMENT nodes and discard al other types.

Overrides:

getFirstChild in class DrbAbstractNode

Returns:

A reference to the first child or null if none.

getLastChild

public DrbNode getLastChild()

The last child of the curren node. This operation looks for the last occurence of ELEMENT node in the node and return it. It was not possible to use directly the getLastChild() operation specified by DOM because it is necessary to filter the ELEMENT nodes and discard al other types.

Overrides:

getLastChild in class DrbAbstractNode

Returns:

A reference to the last child or null is none.

getChildAt

public DrbNode getChildAt(int index)

The child located at a specific position. The provided position starts from 0.It is important to consider the index as a counter among ELEMENT nodes and not among the overall DOM nodes. All other types are not accounted in the index.

Overrides:

getChildAt in class DrbAbstractNode

Parameters:

index - the index of the child node to find

Returns:

A reference to the node at the given index if any and null oterwise.

getChildrenCount

public int getChildrenCount()

Number of children. This operation counts the number of ELEMENT nodes children of the current one. All other types are discarted in the accounting.

Overrides:

getChildrenCount in class DrbAbstractNode

Returns:

The number of children.

getPreviousSibling

public DrbNode getPreviousSibling()

The previous sibling of the current node. The previous sibling is the first one of type ELEMENT.

Overrides:

getPreviousSibling in class DrbAbstractNode

Returns:

A reference to the previous sibling if any or null otherwise.

getNextSibling

public DrbNode getNextSibling()

The next sibling of the current node. This sibling is the next one of type ELEMENT. All other types are discarded during the search.

Overrides:

getNextSibling in class DrbAbstractNode

Returns:

A reference to the next sibling if any and null otherwise.

flush

public void flush()

Performs any pending changes. This methods forces the underlying implementation to perform all changes. The current node may use a buffer for caching input/output operations. In that case, this method will write the node to the system ressource.

Overrides:

flush in class DrbNodeImpl

toString

public String toString()

String representqtion of the object. This operation overrides the default one to set the string representation to the name of the node.

Overrides:

toString in class DrbAbstractNode

Returns:

The name of the node.

setValue

public Value setValue(Value value)
               throws NullPointerException,
                      ClassCastException,
                      UnsupportedOperationException

Changes the value of the node. This operation sets a new value of the current node. This value is converted to text through the toString() method. If the cast is not possible the operation raises an UnsupportedOperationException. If the document has write permission the value is updated in the underlying file in order to persist among sessions. It is therefore possible that this operation consumes a variable amount of time.

Important note: The implementation will rewrite the entire file with the default XmlWritter. Some formatting may be lost depending on the capabilties of the encoder. It will support at least: Element, Attribute, Text and Namespace information. The whitespace and data not exposed in DrbNode will be definitly lost.

Events: This operation fires a node changed event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node. The called operation is the nodesChanged() of the listeners.

Specified by:

setValue in interface DrbNode

Overrides:

setValue in class DrbAbstractNode

Parameters:

value - The new value of the node.

Returns:

The effectivelly assigned value.The type of this value may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed reference to the value is null. This exception may be overriden by an UnsupportedOperationException.

ClassCastException - This exception is raised when the implementation has not succeeded to cast the input value in a type compatible with the current node.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested assignment for any reason.

setAttributes

public void setAttributes(DrbAttributeList attributes)
                   throws NullPointerException,
                          UnsupportedOperationException

Set the attribute list of a node. If some attributes are already attached to the current node they are first removed and then replaced by the new ones. However the operation checks the compatibility of the passed attribute according to the current implementation. The operation does nothing if the compatibility check fails.

Warning: The input attributes may be duplicated or re-instanciated according to the targetted implementation. References to the effectively inserted attributes can be reteived from the getAttributes() operation of the DrbNode. It is highly recommended to discard the references to the input attribuets if not mandatory.

Important note: The implementation of the node is not supposed to accept attribute changes. For instance it may not be possible to change the size attribute of a file through this operation with would meant a effective file resize that is not really relevant without additional data.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node.The called operation is the nodesChanged() of the listeners.

Specified by:

setAttributes in interface DrbNode

Overrides:

setAttributes in class DrbAbstractNode

Parameters:

attributes - A reference to the new attribute list.

Throws:

NullPointerException - This exception is raised when the passed reference to the attribute list is null. This exception may be overriden by an UnsupportedOperationException.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested attribute changes for any reason.

rename

public void rename(String name)
            throws NullPointerException,
                   UnsupportedOperationException

Changes the name of the node. The passed name may be an empty string but never a null reference. The change is persistant such as further instance of a same node (even in different sessions) will have this new name. If the implementation does not suppot the rename operation it is supposerd to throw a UnsupportedOperationException.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the current standing also as the source of the event. The called opetation is the nodesChanged() of the listeners.

Overrides:

rename in class DrbAbstractNode

Parameters:

name - Reference to the new name.

Throws:

UnsupportedOperationException - This exception is raised when the implementation does not support the requested rename for any reason (e.g. specific case or general incapability).

NullPointerException - This exception is raised when the passed name is a null reference.This exception may be overriden by an UnsupportedOperationException.

setNamespaceURI

public void setNamespaceURI(String namespace_uri)
                     throws NullPointerException,
                            UnsupportedOperationException

Sets a namespace resource identifier. The new namespace identifier shall not be null.

Important note: The implementation of the node is not supposed to accept namespace changes. For instance it may not be possible to change the namespace of a file that is basically fixed.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node.The called operation is the nodesChanged() of the listeners.

Specified by:

setNamespaceURI in interface DrbNode

Overrides:

setNamespaceURI in class DrbAbstractNode

Parameters:

namespace_uri - A reference to the new namespace identifier.

Throws:

NullPointerException - This exception is raised when the passed reference to the new namespace identifier is null.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested namespace change for any reason (e.g. by definition or in the specific case).

replaceChild

public DrbNode replaceChild(int index,
                            DrbNode new_node)
                     throws NullPointerException,
                            IndexOutOfBoundsException,
                            UnsupportedOperationException

Replaces a child of the current node. This operation replaces a child in the current children list by a new one The operation aborts when the index is out of bound (index < 0 || index > size). In case of error, the implementation has to restore the initial situation. It is therefore recommended for any implementation to check the consistency prior to perform the replacement.

Warning: The replacing node may be duplicated or re-instanciated according to the targetted implementation.A reference to the effectively replacing node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned one.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to insert a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the new node and the source is the current node. The called operation is the structureChanged() of the listeners.

Specified by:

replaceChild in interface DrbNode

Overrides:

replaceChild in class DrbAbstractNode

Parameters:

index - Index of the node to be replaced. This index starts at 0 and shall be less than the number of children.

new_node - A reference to the node that replaces the old one.

Returns:

A reference to the effectivelly replacing node.This reference may differ from the new_node parameter.

Throws:

NullPointerException - This exception is raised when the reference to the new node is null. This exception may be overriden by a UnsupportedOperationException.

IndexOutOfBoundsException - This exception is raised when the passed index is less than zero or greater or equal to the current number of children.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested replace for any reason. In addition if the old_node is not retreived in the current children list, this exception is also raised.

toXML

public static String toXML(String str)

Format an XML string. All specific characters will be despecialized by adding the specified notation.

Parameters:

str - the string to format

Returns:

a string suitable for XML queries.

removeChild

public void removeChild(int index)
                 throws IndexOutOfBoundsException,
                        UnsupportedOperationException

Removes an existing child. The child at the given index is removed from the children list of the current node. The child is not modified by this operation. At the child point of view it keeps the same parent or any common association depending on the implementation. However at the parent (i.e. the current node) point of view the removed node is completely dismissed and will never be re-instaciated from constructor operations (e.g. getFirstChild(), etc. ). The index of the child to be removed has to correspond to an existing children index. If the index is less than zero or greater or equal to the current number of children, an exception is thrown.

This operation takes into account the removal by updating the sibling associations of the children nodes prior and next to the removed one. The indicies of the nodes next to the removed one are decresed of one. Their parents as well as their contents are left unchanged.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the removed node and the source is the current node.The called operation is the nodesRemoved() of the listeners.

Specified by:

removeChild in interface DrbNode

Overrides:

removeChild in class DrbAbstractNode

Parameters:

index - Index of the child to be removed.

Throws:

IndexOutOfBoundsException - This exception is raised when the passed index is less than zero or greater or equal to the current number of children.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested removal for any reason.

insertChild

public DrbNode insertChild(DrbNode new_node,
                           int index)
                    throws NullPointerException,
                           UnsupportedOperationException,
                           IndexOutOfBoundsException

Inserts a child at a given position. The passed node is inserted in the list of children at the given position The position is the expected index of the node after insertion. All the previous children from the aimed position to the end of the list are shift to the end of the new children list (i.e. their indices are shifted up of 1). If the given index is out of the children bounds and therefore less than zero and greater or equal to the current number of children,the operation raises an exception. An index equal to the current number of children is allowed and the operation is therefore equivalent to appendChild().

If the node has been inserted within the children list, the next sibling indicies are increased of one. In addition the assiociations between the inserted node and it previous and next siblings are updated (if any).

Warning: The inserted node may be duplicated or re-instanciated according to the targetted implementation. A reference to the effectively inserted node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned node.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to insert a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Case of unordered or specifically ordered implementations: If the implementation does not support ordered children or has specific ordering rules, the node is inserted without taking into account the requested index passed in parameter. For instance it may not be possible to impose the file order in a directory: it generally depends on the lexicographical order of the node names or their creation date.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the inserted node and the source is the current node. The called operation is the nodesInserted() of the listeners.

Specified by:

insertChild in interface DrbNode

Overrides:

insertChild in class DrbAbstractNode

Parameters:

new_node - A reference to the node to be inserted.

index - The expected index of the node after the insertion.

Returns:

A reference to the effectively inserted node. This reference may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed node a null reference. This exception may be overriden by an UnsupportedOperationException.

IndexOutOfBoundsException - This exception is raised when the passe index is less than zero or if it is greater or equal to the number of children in the number of children prior the call

UnsupportedOperationException - This exception is raised when the implementation does not support the requested insertion for any reason (e.g. impossible in this current specific case or in general).

appendChild

public DrbNode appendChild(DrbNode nodes)
                    throws NullPointerException,
                           UnsupportedOperationException

Appends a child at the end of the children list. The passed node is inserted in the list of children at the end of the current list.

Warning: The appended node may be duplicated or re-instanciated according to the targetted implementation. A reference to the effectively appended node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned node.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to append a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Case of unordered or specifically ordered implementations: If the implementation does not support ordered children or has specific ordering rules, the node may not be appended but only inserted according to these rules. For instance it may not be possible to impose the file order in a directory: it generally depends on the lexicographical order of the node names or their creation date.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the appended node and the source is the current node. The called operation is the nodesInserted() of the listeners.

Specified by:

appendChild in interface DrbNode

Overrides:

appendChild in class DrbAbstractNode

Parameters:

nodes - A reference to the node to be appended.

Returns:

A reference to the effectivelly appended node. This reference may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed node a null reference.This exception may be overriden by an UnsupportedOperationException.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested append for any reason (e.g. impossible in this current specific case or in general).