org.openxml.dom

Class NodeImpl

java.lang.Object

org.openxml.dom.NodeImpl

All Implemented Interfaces:

Cloneable, Node

Direct Known Subclasses:

CommentImpl, DocumentTypeImpl, ElementDeclImpl, EntityImpl, NotationImpl, ParamEntity, ParentNodeImpl, ProcessingInstructionImpl

public abstract class NodeImpl
extends Object
implements Node, Cloneable

Node is the primary class in the DOM, representing a single node in the document tree. All other classes derived and extend their major functionality from this class.

This class is abstract. All derived classes must extend getNodeType(). This class does not support child nodes, all classes supporting child nodes must extend ParentNodeImpl. In addition, derived classes might wish to extend Node.cloneNode(boolean), equals(java.lang.Object) and Object.toString() and other methods as necessary. Many methods cannot be extended.

For speed and consistency, this is a "kitchen sink" class. It implements most of the functionality for all derived class types.

NodeImpl does not support child nodes, such support is available in the extended class ParentNodeImpl. Namespace support (for element and attribute) is available in ParentNSNodeImpl.

Author:

Assaf Arkin

See Also:

Node

Field Summary

Fields

Modifier and Type	Field and Description
static short	ATTLIST_DECL_NODE Attributes list declaration node.
static short	ELEMENT_DECL_NODE Element declaration node.
static short	PARAM_ENTITY_NODE Parameter entity declaration node.

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NodeImpl(DocumentImpl owner, String name, String value) Hidden constructor creates a new node.

Method Summary

Modifier and Type	Method and Description
Node	appendChild(Node newChild) Insert newChild as the last child of this parent.
protected void	cloneInto(NodeImpl into, boolean deep) This clone method is called after a new node has been constructed to copy the contents of this node into the new one.
boolean	equals(Object other) Returns true if this node and other are identical by content but not context.
NamedNodeMap	getAttributes() Return attributes of node.
NodeList	getChildNodes() Returns a NodeList object that can be used to traverse this node's children.
Node	getFirstChild() Returns the first child of the node.
Node	getLastChild() Returns the last child of the node.
String	getLocalName()
String	getNamespaceURI()
Node	getNextSibling() Returns the next sibling of this node.
String	getNodeName() Returns the name of the node, set from the constructor.
abstract short	getNodeType() Abstract method must be implemented by each node class.
String	getNodeValue() Returns the value of the node.
Document	getOwnerDocument() Return the document associated with this node.
Node	getParentNode() Returns the parent node of this node.
String	getPrefix()
Node	getPreviousSibling() Returns the previous sibling of this node.
boolean	hasChildNodes() Return true if there are any childern to this node.
Node	insertBefore(Node newChild, Node refChild) Insert newChild in this parent, before the existing child refChild.
boolean	isReadOnly() Returns true if node is read-only and cannot be modified, or if node belongs to a read-only document.
void	makeReadOnly() Renders this node read only, preventing it's contents from being modified.
void	normalize()
Node	removeChild(Node oldChild) Remove oldChild from this parent.
Node	replaceChild(Node newChild, Node oldChild) Replace oldChild with newChild, adding the new child and removing the old one.
void	setNodeValue(String value) Changes the value of the node.
protected void	setOwnerDocument(Document owner) Sets the owner document of this node and all its children.
void	setPrefix(String newPrefix)
boolean	supports(String feature, String version) Returns true if the node defines a subtree within which the specified feature is supported, false otherwise.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.w3c.dom.Node

cloneNode, compareDocumentPosition, getBaseURI, getFeature, getTextContent, getUserData, hasAttributes, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, setTextContent, setUserData

Field Detail

ELEMENT_DECL_NODE

public static final short ELEMENT_DECL_NODE

Element declaration node. Not part of the DOM, identifies an element declaration node appearing in the DTD.

See Also:

Constant Field Values

ATTLIST_DECL_NODE

public static final short ATTLIST_DECL_NODE

Attributes list declaration node. Not part of the DOM, identifies an attributes list declaration node appearing in the DTD..

See Also:

Constant Field Values

PARAM_ENTITY_NODE

public static final short PARAM_ENTITY_NODE

Parameter entity declaration node. Not part of the DOM, identifies an internal or external parameter entity declaration node appearing in the DTD (see ParamEntity).

See Also:

Constant Field Values

Constructor Detail

NodeImpl

protected NodeImpl(DocumentImpl owner,
                   String name,
                   String value)
            throws DOMException

Hidden constructor creates a new node. Only one constructor is supported, although cloning is also supported. Owner document must be supplied except for DocumentImpl and DocumentTypeImpl. Name must be supplied, either dynamic or static (e.g. "#document#").

If checkName is true, the supplied named is assumed to be a valid XML name token, one that can contain any Unicode letters and digits, must start with a letter, and may also contain hyphen, underscore, digit or colon.

Parameters:

owner - Document owner of this node, or null

name - Name of node

value - Initial value of node or null

Throws:

DOMException - INVALID_CHARACTER_ERR Node name cannot contain whitespaces or non-printable characters

Method Detail

getNodeType

public abstract short getNodeType()

Abstract method must be implemented by each node class.

Specified by:

getNodeType in interface Node

See Also:

Node.getNodeType()

getNodeName

public String getNodeName()

Returns the name of the node, set from the constructor. Some derived classes do not have the notion of a name, and will return the same name each time. They should do so by setting the default name (e.g. "#comment") in the constructor. This value is never null.

Specified by:

getNodeName in interface Node

See Also:

Node.getNodeName()

getNamespaceURI

public String getNamespaceURI()

Specified by:

getNamespaceURI in interface Node

getPrefix

public String getPrefix()

Specified by:

getPrefix in interface Node

setPrefix

public void setPrefix(String newPrefix)

Specified by:

setPrefix in interface Node

getLocalName

public String getLocalName()

Specified by:

getLocalName in interface Node

getNodeValue

public final String getNodeValue()

Returns the value of the node. Depending on the node type, this value is either the node value (e.g. the text in Text), or always null is node has no notion of a value (e.g. Element). For complete list of which node types will return what, see setNodeValue(java.lang.String).

Specified by:

getNodeValue in interface Node

Returns:

Value of node, null if node has no value

setNodeValue

public void setNodeValue(String value)

Changes the value of the node. Not all node types support the notion of a value. If the value is not supported by a particular node type, it will throw an exception when calling this method. The following table specifies which node types support values:

 Element                Not supported
 Attr                   Supported
 Text                   Supported
 CDATASection           Supported
 EntityReference        Not supported
 Entity                 Not supported
 ProcessingInstruction  Supported
 Comment                Supported
 Document               Not supported
 DocumentType           Not supported
 DocumentFragment       Not supported
 Notation               Not supported
 

For most node types, if the value is set to null, getNodeValue() will return an empty string instead.

Specified by:

setNodeValue in interface Node

Parameters:

value - New value of node

getParentNode

public Node getParentNode()

Returns the parent node of this node. Node may not necessarily have a parent node. If node has been created but not added to any other node, it will be parentless. The Document node is always parentless.

Specified by:

getParentNode in interface Node

Returns:

Parent node of this node

getChildNodes

public NodeList getChildNodes()

Returns a NodeList object that can be used to traverse this node's children. The node list is live, so every change to this node is reflected in it. If the node does not support children, returns an empty node list.

Specified by:

getChildNodes in interface Node

Returns:

NodeList on this node

See Also:

NodeList

getFirstChild

public Node getFirstChild()

Returns the first child of the node. If node has no children, returns null.

Specified by:

getFirstChild in interface Node

Returns:

First child or null

getLastChild

public Node getLastChild()

Returns the last child of the node. If node has no children, returns null.

Specified by:

getLastChild in interface Node

Returns:

Last child or null

getPreviousSibling

public Node getPreviousSibling()

Returns the previous sibling of this node. If node has no previous siblings, returns null.

Specified by:

getPreviousSibling in interface Node

Returns:

Previous sibling or null

getNextSibling

public Node getNextSibling()

Returns the next sibling of this node. If node has no next siblings, returns null.

Specified by:

getNextSibling in interface Node

Returns:

Next sibling or null

getAttributes

public NamedNodeMap getAttributes()

Return attributes of node. Returns null unless node is of type Element, in which case the returned NamedNodeMap will provide access to all the element's attributes.

Specified by:

getAttributes in interface Node

Returns:

Attributes of node or null

getOwnerDocument

public final Document getOwnerDocument()

Return the document associated with this node. The document is used to create new nodes. If this is a Document, or a DocumentType which is not used with any document, will return null.

Specified by:

getOwnerDocument in interface Node

Returns:

The document associated with this node

hasChildNodes

public boolean hasChildNodes()

Return true if there are any childern to this node. Less intensive than calling getChildNodes().

Specified by:

hasChildNodes in interface Node

Returns:

True if node has any children

appendChild

public Node appendChild(Node newChild)

Insert newChild as the last child of this parent.

If newChild is null, newChild is not a compatible type, or childern are not supported by this node type, an exception is thrown.

newChild is removed from its original parent before adding to this parent. If newChild is a DocumentFragment, all its children are inserted one by one into this parent.

Specified by:

appendChild in interface Node

Parameters:

newChild - The new child to add

Returns:

The newly inserted child

Throws:

DOMException - NO_MODIFICATION_ALLOWED_ERR Node is read-only and cannot be modified

DOMException - HIERARCHY_REQUEST_ERR Children are not supported by this node type, or newChild is not a compatible type for this node

insertBefore

public Node insertBefore(Node newChild,
                         Node refChild)
                  throws DOMException

Insert newChild in this parent, before the existing child refChild. If refChild is null, insert newChild as the last child of this parent, akin to calling appendChild(org.w3c.dom.Node).

If newChild is null, newChild does not belong to this DOM, refChild is not a direct child of this node, or childern are not supported by this node type, an exception is thrown.

newChild is removed from its original parent before adding to this parent. If newChild is a DocumentFragment, all its children are inserted one by one into this parent.

Specified by:

insertBefore in interface Node

Parameters:

newChild - The new child to add

refChild - Insert new child before this child, or insert at the end if this child is null

Returns:

The newly inserted child

Throws:

DOMException - NO_MODIFICATION_ALLOWED_ERR Node is read-only and cannot be modified

DOMException - HIERARCHY_REQUEST_ERR Children are not supported by this node type, or newChild is not a compatible type for this node

DOMException - NOT_FOUND_ERR oldChild is not null and not a direct child of this node

removeChild

public Node removeChild(Node oldChild)
                 throws DOMException

Remove oldChild from this parent. If oldChild is not a direct child of this parent, or childern are not supported by this node type, an exception is thrown.

Specified by:

removeChild in interface Node

Parameters:

oldChild - The child to remove

Returns:

The removed child

Throws:

DOMException - NO_MODIFICATION_ALLOWED_ERR Node is read-only and cannot be modified

DOMException - HIERARCHY_REQUEST_ERR Children are not supported by this node type

DOMException - NOT_FOUND_ERR oldChild is not a direct child of this node

replaceChild

public Node replaceChild(Node newChild,
                         Node oldChild)
                  throws DOMException

Replace oldChild with newChild, adding the new child and removing the old one.

If newChild does not belong to this DOM, oldChild is not a direct child of this parent, or childern are not supported by this node type, an exception is thrown.

newChild is removed from its original parent before adding to this parent. If newChild is a DocumentFragment, all its children are inserted one by one into this parent.

Specified by:

replaceChild in interface Node

Parameters:

newChild - The new child to add

oldChild - The old child to take away

Returns:

The old child

Throws:

DOMException - NO_MODIFICATION_ALLOWED_ERR Node is read-only and cannot be modified

DOMException - HIERARCHY_REQUEST_ERR Children are not supported by this node type, or newChild is not a compatible type for this node

DOMException - NOT_FOUND_ERR oldChild is not a direct child of this node

normalize

public void normalize()

Specified by:

normalize in interface Node

makeReadOnly

public final void makeReadOnly()

Renders this node read only, preventing it's contents from being modified. Attempts to modify the node's contents will throw an exception. The node's children are also made read-only.

isReadOnly

public final boolean isReadOnly()

Returns true if node is read-only and cannot be modified, or if node belongs to a read-only document.

Returns:

True if node is read-only and cannot be modified

See Also:

makeReadOnly()

supports

public final boolean supports(String feature,
                              String version)

Returns true if the node defines a subtree within which the specified feature is supported, false otherwise.

Parameters:

feature - The package name of the feature set

version - The version number of the feature set (e.g. "2.0" for Level 2), or any version if null

Returns:

True if feature is supported

setOwnerDocument

protected final void setOwnerDocument(Document owner)
                               throws DOMException

Sets the owner document of this node and all its children. When adding a node previously with one document to a new document, it makes sense to switch the owner document. If the new owner is not part of this DOM implementation, an exception will be thrown.

Parameters:

owner - The new owner

Throws:

DOMException - The owner is not of this DOM implementation

cloneInto

protected void cloneInto(NodeImpl into,
                         boolean deep)

This clone method is called after a new node has been constructed to copy the contents of this node into the new one. It clones in contents but not in context, and guarantees that the cloned node will pass the equality test (see equals(java.lang.Object)).

into must be a valid node of the exact same class as this one. deep is true if deep cloning (includes all children nodes) is to be performed. If deep is false, the clone might not pass the equality test.

Derived classes override and call this method to add per-class variable copying. This method is called by Node.cloneNode(boolean) and the default Object.clone() method.

Contents cloning duplicates the node's name and value, and its children. It does not duplicate it's context, that is, the node's parent or sibling. Initially a clone node has no parents or siblings. However, the node does belong to the same document, since all nodes must belong to some document. The cloned node is never read-only.

Parameters:

into - A node into which to duplicate this one

deep - True if deep cloning is required

equals

public boolean equals(Object other)

Returns true if this node and other are identical by content but not context. Test by content but not context adheres to the following:

• Both nodes must be of the same type, must have the same name and value (case sensitive) and for elements, the same tag name
• For elements, both must have identical attribute list, although attributes may be specified/unspecified and in different orders
• Both nodes must have no children, or must have the exact same sequence of children; children are tested for equality by calling equals(java.lang.Object) on each pair
• However, both nodes may reside in different documents, belong to different parents, have different siblings, different read-only flags, etc.

It is guaranteed that the act of cloning a node will return a second node that will pass the test of equality.

Note that for large document roots, the equality operation can be very expensive.

Overrides:

equals in class Object

Parameters:

other - The other node to test for equality

Returns:

True if both nodes are equal based on their content but not their context