java.lang.Object
|
+--gnu.xml.dom.DomNode
All Implemented Interfaces:
java.lang.Cloneable, DocumentEvent, EventTarget, Node, NodeListKnown Direct Subclasses:
DomCharacterData, DomDocument, DomEntityReference, DomExtern, DomFragment, DomNsNode, DomPI
"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.
- David Brownell
DomNode
protected DomNode(Document 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.
- owner
addEventListener
public final void addEventListener(java.lang.String type, EventListener listener, boolean useCapture)
DOM L2 (Events)
Registers an event listener's interest in a class of events.
- type
- listener
- useCapture
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.
- newChild
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.
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.
- deep
compact
public void compact()
Reduces space utilization for this node.
createEvent
public Event createEvent(java.lang.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().
- eventType - Identifies the particular DOM feature module
defining the type of event, such as "MutationEvents".
dispatchEvent
public final boolean dispatchEvent(Event event)
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.
- event
java.lang.NullPointerException
- When a null event is passed.java.lang.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
createEvent
getAttributes
public NamedNodeMap getAttributes()
DOM L1
Returns null; Element subclasses must override this method.
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.
getElementsByTagName
public NodeList getElementsByTagName(java.lang.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.
- tag
getElementsByTagNameNS
public NodeList getElementsByTagNameNS(java.lang.String namespace, java.lang.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.
- namespace
- local
getFirstChild
public final Node getFirstChild()
DOM L1
Returns the first child of this node, or null if there are none.
getLastChild
public final Node getLastChild()
DOM L1
Returns the last child of this node, or null if there are none.
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.)
getLocalName
public String getLocalName()
DOM L2
Returns the node name; this must be overridden for element and
attribute nodes.
getNamespaceURI
public String getNamespaceURI()
DOM L2
Returns null; this must be overridden for element and
attribute nodes.
getNextSibling
public final Node getNextSibling()
DOM L1
Returns the previous sibling, if one is known.
getNodeName
public String getNodeName()
This forces GCJ compatibility.
Without this method GCJ seems unable to natively compile GNUJAXP.
getNodeType
public short getNodeType()
This forces GCJ compatibility.
Without this method GCJ is unable to compile to byte code.
getNodeValue
public String getNodeValue()
DOM L1
Returns null; this must be overridden for nodes types with
a defined value, along with the setNodeValue method.
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.
getParentNode
public final Node getParentNode()
DOM L1
Returns the parent node, if one is known.
getPrefix
public String getPrefix()
DOM L2
Returns null; this must be overridden for element and
attribute nodes.
getPreviousSibling
public final Node getPreviousSibling()
DOM L1
Returns the previous sibling, if one is known.
hasAttributes
public boolean hasAttributes()
DOM L2>
Returns true iff this is an element node with attributes.
hasChildNodes
public final boolean hasChildNodes()
DOM L1
Returns true if this node has children.
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.
- newChild
- refChild
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.
isSupported
public boolean isSupported(java.lang.String feature, java.lang.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.)
- feature
- version
item
public final Node item(int index)
DOM L1 (NodeList)
Returns the item with the specified index in this NodeList,
else null.
- index
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.
- other
normalize
public 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).
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.
- refChild
removeEventListener
public final void removeEventListener(java.lang.String type, EventListener listener, boolean useCapture)
DOM L2 (Events)
Unregisters an event listener.
- type
- listener
- useCapture
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.
- newChild
- refChild
setNodeValue
public void setNodeValue(java.lang.String value)
DOM L1
Does nothing; this must be overridden (along with the
getNodeValue method) for nodes with a non-null defined value.
- value
setPrefix
public void setPrefix(java.lang.String prefix)
DOM L2
Does nothing; this must be overridden (along with the
getPrefix method) for element and attribute nodes.
- prefix
trimToSize
public void trimToSize()
Minimize extra space consumed by this node to hold children and event
listeners.