gnu.xml.dom

Class DomNode

Implemented Interfaces:
Cloneable, Comparable<T>, DocumentEvent, EventTarget, Node, NodeList
Known Direct Subclasses:
DomCharacterData, DomDocument, DomDocumentFragment, DomEntityReference, DomExtern, DomNsNode, DomProcessingInstruction

public abstract class DomNode
extends Object
implements Node, NodeList, EventTarget, DocumentEvent, Cloneable, Comparable<T>

"Node", "EventTarget", and "DocumentEvent" implementation. This provides most of the core DOM functionality; only more specialized features are provided by subclasses. Those subclasses may have some particular constraints they must implement, by overriding methods defined here. Such constraints are noted here in the method documentation.

Note that you can create events with type names prefixed with "USER-", and pass them through this DOM. This lets you use the DOM event scheme for application specific purposes, although you must use a predefined event structure (such as MutationEvent) to pass data along with those events. Test for existence of this feature with the "USER-Events" DOM feature name.

Other kinds of events you can send include the "html" events, like "load", "unload", "abort", "error", and "blur"; and the mutation events. If this DOM has been compiled with mutation event support enabled, it will send mutation events when you change parts of the tree; otherwise you may create and send such events yourself, but they won't be generated by the DOM itself.

Note that there is a namespace-aware name comparison method, nameAndTypeEquals, which compares the names (and types) of two nodes in conformance with the "Namespaces in XML" specification. While mostly intended for use with elements and attributes, this should also be helpful for ProcessingInstruction nodes and some others which do not have namespace URIs.

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

DomNode(short nodeType, DomDocument owner)
Constructs a node and associates it with its owner.

Method Summary

void
addEventListener(String type, EventListener listener, boolean useCapture)
DOM L2 (Events) Registers an event listener's interest in a class of events.
Node
appendChild(Node newChild)
DOM L1 Appends the specified node to this node's list of children.
Object
clone()
Clones this node; roughly equivalent to cloneNode(false).
Node
cloneNode(boolean deep)
DOM L1 Returns a clone of this node which optionally includes cloned versions of child nodes.
void
compact()
Reduces space utilization for this node.
short
compareDocumentPosition(Node other)
int
compareTo(Object other)
DOM nodes have a natural ordering: document order.
Event
createEvent(String eventType)
DOM L2 (Events) Returns an instance of the specified type of event object.
boolean
dispatchEvent(Event event)
DOM L2 (Events) Delivers an event to all relevant listeners, returning true if the caller should perform their default action.
NamedNodeMap
getAttributes()
DOM L1 Returns null; Element subclasses must override this method.
String
getBaseURI()
NodeList
getChildNodes()
DOM L1 Returns a list, possibly empty, of the children of this node.
NodeList
getElementsByTagName(String tag)
DOM L1 Creates a NodeList giving array-style access to elements with the specified name.
NodeList
getElementsByTagNameNS(String namespace, String local)
DOM L2 Creates a NodeList giving array-style access to elements with the specified namespace and local name.
Object
getFeature(String feature, String version)
Node
getFirstChild()
DOM L1 Returns the first child of this node, or null if there are none.
Node
getLastChild()
DOM L1 Returns the last child of this node, or null if there are none.
int
getLength()
DOM L1 (NodeList) Returns the number of elements in this NodeList.
String
getLocalName()
DOM L2 Returns the node name; this must be overridden for element and attribute nodes.
String
getNamespaceURI()
DOM L2 Returns null; this must be overridden for element and attribute nodes.
Node
getNextSibling()
DOM L1 Returns the previous sibling, if one is known.
abstract String
getNodeName()
This forces GCJ compatibility.
short
getNodeType()
This forces GCJ compatibility.
String
getNodeValue()
DOM L1 Returns null; this must be overridden for nodes types with a defined value, along with the setNodeValue method.
Document
getOwnerDocument()
DOM L1 (modified in L2) Returns the owner document.
Node
getParentNode()
DOM L1 Returns the parent node, if one is known.
String
getPrefix()
DOM L2 Returns null; this must be overridden for element and attribute nodes.
Node
getPreviousSibling()
DOM L1 Returns the previous sibling, if one is known.
String
getTextContent()
Object
getUserData(String key)
boolean
hasAttributes()
DOM L2> Returns true iff this is an element node with attributes.
boolean
hasChildNodes()
DOM L1 Returns true if this node has children.
Node
insertBefore(Node newChild, Node refChild)
DOM L1 Inserts the specified node in this node's list of children.
boolean
isDefaultNamespace(String namespaceURI)
boolean
isEqualNode(Node arg)
boolean
isReadonly()
Exposes the internal "readonly" flag.
boolean
isSameNode(Node other)
boolean
isSupported(String feature, String version)
DOM L2 Consults the DOM implementation to determine if the requested feature is supported.
Node
item(int index)
DOM L1 (NodeList) Returns the item with the specified index in this NodeList, else null.
void
list(PrintStream out, int indent)
String
lookupNamespaceURI(String prefix)
String
lookupPrefix(String namespaceURI)
void
makeReadonly()
Sets the internal "readonly" flag so this subtree can't be changed.
boolean
nameAndTypeEquals(Node other)
Returns true iff node types match, and either (a) both nodes have no namespace and their getNodeName() values are the same, or (b) both nodes have the same getNamespaceURI() and same getLocalName() values.
void
normalize()
DOM L1 (relocated in DOM L2) In this node and all contained nodes (including attributes if relevant) merge adjacent text nodes.
Node
removeChild(Node refChild)
DOM L1 Removes the specified child from this node's list of children, or else reports an exception.
void
removeEventListener(String type, EventListener listener, boolean useCapture)
DOM L2 (Events) Unregisters an event listener.
Node
replaceChild(Node newChild, Node refChild)
DOM L1 Replaces the specified node in this node's list of children.
void
setNodeValue(String value)
DOM L1 Does nothing; this must be overridden (along with the getNodeValue method) for nodes with a non-null defined value.
void
setPrefix(String prefix)
DOM L2 Does nothing; this must be overridden (along with the getPrefix method) for element and attribute nodes.
void
setTextContent(String textContent)
Object
setUserData(String key, Object data, UserDataHandler handler)
String
toString()
void
trimToSize()
Minimize extra space consumed by this node to hold children and event listeners.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DomNode

protected DomNode(short nodeType,
                  DomDocument owner)
Constructs a node and associates it with its owner. Only Document and DocumentType nodes may be created with no owner, and DocumentType nodes get an owner as soon as they are associated with a document.

Method Details

addEventListener

public final void addEventListener(String type,
                                   EventListener listener,
                                   boolean useCapture)
DOM L2 (Events) Registers an event listener's interest in a class of events.
Specified by:
addEventListener in interface EventTarget

appendChild

public Node appendChild(Node newChild)
DOM L1 Appends the specified node to this node's list of children. Document subclasses must override this to enforce the restrictions that there be only one element and document type child.

Causes a DOMNodeInserted mutation event to be reported. Will first cause a DOMNodeRemoved event to be reported if the parameter already has a parent. If the new child is a document fragment node, both events will be reported for each child of the fragment; the order in which children are removed and inserted is implementation-specific.

If this DOM has been compiled without mutation event support, these events will not be reported.

Specified by:
appendChild in interface Node

clone

public Object clone()
Clones this node; roughly equivalent to cloneNode(false). Element subclasses must provide a new implementation which invokes this method to handle the basics, and then arranges to clone any element attributes directly. Attribute subclasses must make similar arrangements, ensuring that existing ties to elements are broken by cloning.
Overrides:
clone in interface Object

cloneNode

public Node cloneNode(boolean deep)
DOM L1 Returns a clone of this node which optionally includes cloned versions of child nodes. Clones are always mutable, except for entity reference nodes.
Specified by:
cloneNode in interface Node

compact

public void compact()
Reduces space utilization for this node.

compareDocumentPosition

public short compareDocumentPosition(Node other)
            throws DOMException
Specified by:
compareDocumentPosition in interface Node

compareTo

public final int compareTo(Object other)
DOM nodes have a natural ordering: document order.

createEvent

public Event createEvent(String eventType)
DOM L2 (Events) Returns an instance of the specified type of event object. Understands about DOM Mutation, HTML, and UI events.

If the name of the event type begins with "USER-", then an object implementing the "Event" class will be returned; this provides a limited facility for application-defined events to use the DOM event infrastructure. Alternatively, use one of the standard DOM event classes and initialize it using use such a "USER-" event type name; or defin, instantiate, and initialize an application-specific subclass of DomEvent and pass that to dispatchEvent().

Specified by:
createEvent in interface DocumentEvent
Parameters:
eventType - Identifies the particular DOM feature module defining the type of event, such as "MutationEvents". The event "name" is a different kind of "type".

dispatchEvent

public final boolean dispatchEvent(Event event)
            throws EventException
DOM L2 (Events) Delivers an event to all relevant listeners, returning true if the caller should perform their default action. Note that the event must have been provided by the createEvent() method on this class, else it can't be dispatched.
Specified by:
dispatchEvent in interface EventTarget
Throws:
NullPointerException - When a null event is passed.
ClassCastException - When the event wasn't provided by the createEvent method, or otherwise isn't a DomEvent.
EventException - If the event type wasn't specified

getAttributes

public NamedNodeMap getAttributes()
DOM L1 Returns null; Element subclasses must override this method.
Specified by:
getAttributes in interface Node

getBaseURI

public String getBaseURI()
Specified by:
getBaseURI in interface Node

getChildNodes

public NodeList getChildNodes()
DOM L1 Returns a list, possibly empty, of the children of this node. In this implementation, to conserve memory, nodes are the same as their list of children. This can have ramifications for subclasses, which may need to provide their own getLength method for reasons unrelated to the NodeList method of the same name.
Specified by:
getChildNodes in interface Node

getElementsByTagName

public NodeList getElementsByTagName(String tag)
DOM L1 Creates a NodeList giving array-style access to elements with the specified name. Access is fastest if indices change by small values, and the DOM is not modified.

getElementsByTagNameNS

public NodeList getElementsByTagNameNS(String namespace,
                                       String local)
DOM L2 Creates a NodeList giving array-style access to elements with the specified namespace and local name. Access is fastest if indices change by small values, and the DOM is not modified.

getFeature

public Object getFeature(String feature,
                         String version)
Specified by:
getFeature in interface Node

getFirstChild

public Node getFirstChild()
DOM L1 Returns the first child of this node, or null if there are none.
Specified by:
getFirstChild in interface Node

getLastChild

public Node getLastChild()
DOM L1 Returns the last child of this node, or null if there are none.
Specified by:
getLastChild in interface Node

getLength

public int getLength()
DOM L1 (NodeList) Returns the number of elements in this NodeList. (Note that many interfaces have a "Length" property, not just NodeList, and if a node subtype must implement one of those, it will also need to override getChildNodes.)
Specified by:
getLength in interface NodeList

getLocalName

public String getLocalName()
DOM L2 Returns the node name; this must be overridden for element and attribute nodes.
Specified by:
getLocalName in interface Node

getNamespaceURI

public String getNamespaceURI()
DOM L2 Returns null; this must be overridden for element and attribute nodes.
Specified by:
getNamespaceURI in interface Node

getNextSibling

public Node getNextSibling()
DOM L1 Returns the previous sibling, if one is known.
Specified by:
getNextSibling in interface Node

getNodeName

public abstract String getNodeName()
This forces GCJ compatibility. Without this method GCJ seems unable to natively compile GNUJAXP.
Specified by:
getNodeName in interface Node

getNodeType

public final short getNodeType()
This forces GCJ compatibility. Without this method GCJ is unable to compile to byte code.
Specified by:
getNodeType in interface Node

getNodeValue

public String getNodeValue()
DOM L1 Returns null; this must be overridden for nodes types with a defined value, along with the setNodeValue method.
Specified by:
getNodeValue in interface Node

getOwnerDocument

public final Document getOwnerDocument()
DOM L1 (modified in L2) Returns the owner document. This is only null for Document nodes, and (new in L2) for DocumentType nodes which have not yet been associated with the rest of their document.
Specified by:
getOwnerDocument in interface Node

getParentNode

public Node getParentNode()
DOM L1 Returns the parent node, if one is known.
Specified by:
getParentNode in interface Node

getPrefix

public String getPrefix()
DOM L2 Returns null; this must be overridden for element and attribute nodes.
Specified by:
getPrefix in interface Node

getPreviousSibling

public Node getPreviousSibling()
DOM L1 Returns the previous sibling, if one is known.
Specified by:
getPreviousSibling in interface Node

getTextContent

public final String getTextContent()
            throws DOMException
Specified by:
getTextContent in interface Node

getUserData

public Object getUserData(String key)
Specified by:
getUserData in interface Node

hasAttributes

public boolean hasAttributes()
DOM L2> Returns true iff this is an element node with attributes.
Specified by:
hasAttributes in interface Node

hasChildNodes

public boolean hasChildNodes()
DOM L1 Returns true if this node has children.
Specified by:
hasChildNodes in interface Node

insertBefore

public Node insertBefore(Node newChild,
                         Node refChild)
DOM L1 Inserts the specified node in this node's list of children. Document subclasses must override this to enforce the restrictions that there be only one element and document type child.

Causes a DOMNodeInserted mutation event to be reported. Will first cause a DOMNodeRemoved event to be reported if the newChild parameter already has a parent. If the new child is a document fragment node, both events will be reported for each child of the fragment; the order in which children are removed and inserted is implementation-specific.

If this DOM has been compiled without mutation event support, these events will not be reported.

Specified by:
insertBefore in interface Node

isDefaultNamespace

public boolean isDefaultNamespace(String namespaceURI)
Specified by:
isDefaultNamespace in interface Node

isEqualNode

public boolean isEqualNode(Node arg)
Specified by:
isEqualNode in interface Node

isReadonly

public final boolean isReadonly()
Exposes the internal "readonly" flag. In DOM, children of entities and entity references are readonly, as are the objects associated with DocumentType objets.

isSameNode

public boolean isSameNode(Node other)
Specified by:
isSameNode in interface Node

isSupported

public boolean isSupported(String feature,
                           String version)
DOM L2 Consults the DOM implementation to determine if the requested feature is supported. DocumentType subclasses must override this method, and associate themselves directly with the DOMImplementation node used. (This method relies on being able to access the DOMImplementation from the owner document, but DocumentType nodes can be created without an owner.)
Specified by:
isSupported in interface Node

item

public Node item(int index)
DOM L1 (NodeList) Returns the item with the specified index in this NodeList, else null.
Specified by:
item in interface NodeList

list

public void list(PrintStream out,
                 int indent)

lookupNamespaceURI

public String lookupNamespaceURI(String prefix)
Specified by:
lookupNamespaceURI in interface Node

lookupPrefix

public String lookupPrefix(String namespaceURI)
Specified by:
lookupPrefix in interface Node

makeReadonly

public void makeReadonly()
Sets the internal "readonly" flag so this subtree can't be changed. Subclasses need to override this method for any associated content that's not a child node, such as an element's attributes or the (few) declarations associated with a DocumentType.

nameAndTypeEquals

public boolean nameAndTypeEquals(Node other)
Returns true iff node types match, and either (a) both nodes have no namespace and their getNodeName() values are the same, or (b) both nodes have the same getNamespaceURI() and same getLocalName() values.

Note that notion of a "Per-Element-Type" attribute name scope, as found in a non-normative appendix of the XML Namespaces specification, is not supported here. Your application must implement that notion, typically by not bothering to check nameAndTypeEquals for attributes without namespace URIs unless you already know their elements are nameAndTypeEquals.


normalize

public final void normalize()
DOM L1 (relocated in DOM L2) In this node and all contained nodes (including attributes if relevant) merge adjacent text nodes. This is done while ignoring text which happens to use CDATA delimiters).
Specified by:
normalize in interface Node

removeChild

public Node removeChild(Node refChild)
DOM L1 Removes the specified child from this node's list of children, or else reports an exception.

Causes a DOMNodeRemoved mutation event to be reported.

If this DOM has been compiled without mutation event support, these events will not be reported.

Specified by:
removeChild in interface Node

removeEventListener

public final void removeEventListener(String type,
                                      EventListener listener,
                                      boolean useCapture)
DOM L2 (Events) Unregisters an event listener.
Specified by:
removeEventListener in interface EventTarget

replaceChild

public Node replaceChild(Node newChild,
                         Node refChild)
DOM L1 Replaces the specified node in this node's list of children. Document subclasses must override this to test the restrictions that there be only one element and document type child.

Causes DOMNodeRemoved and DOMNodeInserted mutation event to be reported. Will cause another DOMNodeRemoved event to be reported if the newChild parameter already has a parent. These events may be delivered in any order, except that the event reporting removal from such an existing parent will always be delivered before the event reporting its re-insertion as a child of some other node. The order in which children are removed and inserted is implementation specific.

If your application needs to depend on the in which those removal and insertion events are delivered, don't use this API. Instead, invoke the removeChild and insertBefore methods directly, to guarantee a specific delivery order. Similarly, don't use document fragments, Otherwise your application code may not work on a DOM which implements this method differently.

If this DOM has been compiled without mutation event support, these events will not be reported.

Specified by:
replaceChild in interface Node

setNodeValue

public void setNodeValue(String value)
DOM L1 Does nothing; this must be overridden (along with the getNodeValue method) for nodes with a non-null defined value.
Specified by:
setNodeValue in interface Node

setPrefix

public void setPrefix(String prefix)
DOM L2 Does nothing; this must be overridden (along with the getPrefix method) for element and attribute nodes.
Specified by:
setPrefix in interface Node

setTextContent

public void setTextContent(String textContent)
            throws DOMException
Specified by:
setTextContent in interface Node

setUserData

public Object setUserData(String key,
                          Object data,
                          UserDataHandler handler)
Specified by:
setUserData in interface Node

toString

public String toString()
Overrides:
toString in interface Object

trimToSize

public void trimToSize()
Minimize extra space consumed by this node to hold children and event listeners.

DomNode.java -- Copyright (C) 1999,2000,2001,2004 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.