* The Node interface provides shared behaviors such as siblings and * children, both for consistancy and so that the most common tree * operations may be performed without constantly having to downcast * to specific node types. When there is no obvious mapping for one of * these queries, it will respond with null. * Note that the default behavior is that children are forbidden. To * permit them, the subclass ParentNode overrides several methods. *
* NodeImpl also implements NodeList, so it can return itself in * response to the getChildNodes() query. This eliminiates the need * for a separate ChildNodeList object. Note that this is an * IMPLEMENTATION DETAIL; applications should _never_ assume that * this identity exists. *
* All nodes in a single document must originate * in that document. (Note that this is much tighter than "must be * same implementation") Nodes are all aware of their ownerDocument, * and attempts to mismatch will throw WRONG_DOCUMENT_ERR. *
* However, to save memory not all nodes always have a direct reference * to their ownerDocument. When a node is owned by another node it relies * on its owner to store its ownerDocument. Parent nodes always store it * though, so there is never more than one level of indirection. * And when a node doesn't have an owner, ownerNode refers to its * ownerDocument. *
* This class doesn't directly support mutation events, however, it still * implements the EventTarget interface and forward all related calls to the * document so that the document class do so. * * @author Arnaud Le Hors, IBM * @author Joe Kesselman, IBM * @version * @since PR-DOM-Level-1-19980818. */ public abstract class NodeImpl implements Node, NodeList, EventTarget, Cloneable, Serializable { // // Constants // /** Serialization version. */ static final long serialVersionUID = -6316591992167219696L; // public /** Element definition node type. */ public static final short ELEMENT_DEFINITION_NODE = -1; // // Data // // links protected NodeImpl ownerNode; // typically the parent but not always! // data protected short flags; protected final static short READONLY = 0x1<<0; protected final static short SYNCDATA = 0x1<<1; protected final static short SYNCCHILDREN = 0x1<<2; protected final static short OWNED = 0x1<<3; protected final static short FIRSTCHILD = 0x1<<4; protected final static short SPECIFIED = 0x1<<5; protected final static short IGNORABLEWS = 0x1<<6; protected final static short HASSTRING = 0x1<<7; protected final static short UNNORMALIZED = 0x1<<8; // // Constructors // /** * No public constructor; only subclasses of Node should be * instantiated, and those normally via a Document's factory methods *
* Every Node knows what Document it belongs to.
*/
protected NodeImpl(CoreDocumentImpl ownerDocument) {
// as long as we do not have any owner, ownerNode is our ownerDocument
ownerNode = ownerDocument;
} //
* By default we do not accept any children, ParentNode overrides this.
* @see ParentNode
*
* @returns newChild, in its new state (relocated, or emptied in the
* case of DocumentNode.)
*
* @throws DOMException(HIERARCHY_REQUEST_ERR) if newChild is of a
* type that shouldn't be a child of this node.
*
* @throws DOMException(WRONG_DOCUMENT_ERR) if newChild has a
* different owner document than we do.
*
* @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is
* read-only.
*/
public Node appendChild(Node newChild) throws DOMException {
return insertBefore(newChild, null);
}
/**
* Returns a duplicate of a given node. You can consider this a
* generic "copy constructor" for nodes. The newly returned object should
* be completely independent of the source object's subtree, so changes
* in one after the clone has been made will not affect the other.
*
* Note: since we never have any children deep is meaningless here,
* ParentNode overrides this behavior.
* @see ParentNode
*
*
* Example: Cloning a Text node will copy both the node and the text it
* contains.
*
* Example: Cloning something that has children -- Element or Attr, for
* example -- will _not_ clone those children unless a "deep clone"
* has been requested. A shallow clone of an Attr node will yield an
* empty Attr of the same name.
*
* NOTE: Clones will always be read/write, even if the node being cloned
* is read-only, to permit applications using only the DOM API to obtain
* editable copies of locked portions of the tree.
*/
public Node cloneNode(boolean deep) {
if (needsSyncData()) {
synchronizeData();
}
NodeImpl newnode;
try {
newnode = (NodeImpl)clone();
}
catch (CloneNotSupportedException e) {
// Revisit : don't fail silently - but don't want to tie to parser guts
// System.out.println("UNEXPECTED "+e);
return null;
}
// Need to break the association w/ original kids
newnode.ownerNode = ownerDocument();
newnode.isOwned(false);
// REVISIT: What to do when readOnly? -Ac
newnode.isReadOnly(false);
return newnode;
} // cloneNode(boolean):Node
/**
* Find the Document that this Node belongs to (the document in
* whose context the Node was created). The Node may or may not
* currently be part of that Document's actual contents.
*/
public Document getOwnerDocument() {
// if we have an owner simply forward the request
// otherwise ownerNode is our ownerDocument
if (isOwned()) {
return ownerNode.ownerDocument();
} else {
return (Document) ownerNode;
}
}
/**
* same as above but returns internal type and this one is not overridden
* by CoreDocumentImpl to return null
*/
CoreDocumentImpl ownerDocument() {
// if we have an owner simply forward the request
// otherwise ownerNode is our ownerDocument
if (isOwned()) {
return ownerNode.ownerDocument();
} else {
return (CoreDocumentImpl) ownerNode;
}
}
/**
* NON-DOM
* set the ownerDocument of this node
*/
void setOwnerDocument(CoreDocumentImpl doc) {
if (needsSyncData()) {
synchronizeData();
}
// if we have an owner we rely on it to have it right
// otherwise ownerNode is our ownerDocument
if (!isOwned()) {
ownerNode = doc;
}
}
/**
* Obtain the DOM-tree parent of this node, or null if it is not
* currently active in the DOM tree (perhaps because it has just been
* created or removed). Note that Document, DocumentFragment, and
* Attribute will never have parents.
*/
public Node getParentNode() {
return null; // overriden by ChildNode
}
/*
* same as above but returns internal type
*/
NodeImpl parentNode() {
return null;
}
/** The next child of this node's parent, or null if none */
public Node getNextSibling() {
return null; // default behavior, overriden in ChildNode
}
/** The previous child of this node's parent, or null if none */
public Node getPreviousSibling() {
return null; // default behavior, overriden in ChildNode
}
ChildNode previousSibling() {
return null; // default behavior, overriden in ChildNode
}
/**
* Return the collection of attributes associated with this node,
* or null if none. At this writing, Element is the only type of node
* which will ever have attributes.
*
* @see ElementImpl
*/
public NamedNodeMap getAttributes() {
return null; // overridden in ElementImpl
}
/**
* Returns whether this node (if it is an element) has any attributes.
* @return
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*/
public boolean hasChildNodes() {
return false;
}
/**
* Obtain a NodeList enumerating all children of this node. If there
* are none, an (initially) empty NodeList is returned.
*
* NodeLists are "live"; as children are added/removed the NodeList
* will immediately reflect those changes. Also, the NodeList refers
* to the actual nodes, so changes to those nodes made via the DOM tree
* will be reflected in the NodeList and vice versa.
*
* In this implementation, Nodes implement the NodeList interface and
* provide their own getChildNodes() support. Other DOMs may solve this
* differently.
*/
public NodeList getChildNodes() {
return this;
}
/** The first child of this Node, or null if none.
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*/
public Node getFirstChild() {
return null;
}
/** The first child of this Node, or null if none.
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*/
public Node getLastChild() {
return null;
}
/**
* Move one or more node(s) to our list of children. Note that this
* implicitly removes them from their previous parent.
*
* By default we do not accept any children, ParentNode overrides this.
* @see ParentNode
*
* @param newChild The Node to be moved to our subtree. As a
* convenience feature, inserting a DocumentNode will instead insert
* all its children.
*
* @param refChild Current child which newChild should be placed
* immediately before. If refChild is null, the insertion occurs
* after all existing Nodes, like appendChild().
*
* @returns newChild, in its new state (relocated, or emptied in the
* case of DocumentNode.)
*
* @throws DOMException(HIERARCHY_REQUEST_ERR) if newChild is of a
* type that shouldn't be a child of this node, or if newChild is an
* ancestor of this node.
*
* @throws DOMException(WRONG_DOCUMENT_ERR) if newChild has a
* different owner document than we do.
*
* @throws DOMException(NOT_FOUND_ERR) if refChild is not a child of
* this node.
*
* @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is
* read-only.
*/
public Node insertBefore(Node newChild, Node refChild)
throws DOMException {
throw new DOMException(DOMException.HIERARCHY_REQUEST_ERR,
"DOM006 Hierarchy request error");
}
/**
* Remove a child from this Node. The removed child's subtree
* remains intact so it may be re-inserted elsewhere.
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*
* @return oldChild, in its new state (removed).
*
* @throws DOMException(NOT_FOUND_ERR) if oldChild is not a child of
* this node.
*
* @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is
* read-only.
*/
public Node removeChild(Node oldChild)
throws DOMException {
throw new DOMException(DOMException.NOT_FOUND_ERR,
"DOM008 Not found");
}
/**
* Make newChild occupy the location that oldChild used to
* have. Note that newChild will first be removed from its previous
* parent, if any. Equivalent to inserting newChild before oldChild,
* then removing oldChild.
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*
* @returns oldChild, in its new state (removed).
*
* @throws DOMException(HIERARCHY_REQUEST_ERR) if newChild is of a
* type that shouldn't be a child of this node, or if newChild is
* one of our ancestors.
*
* @throws DOMException(WRONG_DOCUMENT_ERR) if newChild has a
* different owner document than we do.
*
* @throws DOMException(NOT_FOUND_ERR) if oldChild is not a child of
* this node.
*
* @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is
* read-only.
*/
public Node replaceChild(Node newChild, Node oldChild)
throws DOMException {
throw new DOMException(DOMException.HIERARCHY_REQUEST_ERR,
"DOM006 Hierarchy request error");
}
//
// NodeList methods
//
/**
* NodeList method: Count the immediate children of this node
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*
* @return int
*/
public int getLength() {
return 0;
}
/**
* NodeList method: Return the Nth immediate child of this node, or
* null if the index is out of bounds.
*
* By default we do not have any children, ParentNode overrides this.
* @see ParentNode
*
* @return org.w3c.dom.Node
* @param Index int
*/
public Node item(int index) {
return null;
}
//
// DOM2: methods, getters, setters
//
/**
* Puts all
* Note that this implementation simply calls normalize() on this Node's
* children. It is up to implementors or Node to override normalize()
* to take action.
*/
public void normalize() {
/* by default we do not have any children,
ParentNode overrides this behavior */
}
/**
* Introduced in DOM Level 2.
* Tests whether the DOM implementation implements a specific feature and
* that feature is supported by this node.
* @param feature The package name of the feature to test. This is the same
* name as what can be passed to the method hasFeature on
* DOMImplementation.
* @param version This is the version number of the package name to
* test. In Level 2, version 1, this is the string "2.0". If the version is
* not specified, supporting any version of the feature will cause the
* method to return true.
* @return boolean Returns true if this node defines a subtree within which
* the specified feature is supported, false otherwise.
* @since WD-DOM-Level-2-19990923
*/
public boolean isSupported(String feature, String version)
{
return ownerDocument().getImplementation().hasFeature(feature,
version);
}
/**
* Introduced in DOM Level 2.
*
* The namespace URI of this node, or null if it is unspecified. When this
* node is of any type other than ELEMENT_NODE and ATTRIBUTE_NODE, this is
* always null and setting it has no effect.
*
* This is not a computed value that is the result of a namespace lookup
* based on an examination of the namespace declarations in scope. It is
* merely the namespace URI given at creation time.
*
* For nodes created with a DOM Level 1 method, such as createElement
* from the Document interface, this is null.
* @since WD-DOM-Level-2-19990923
* @see AttrNSImpl
* @see ElementNSImpl
*/
public String getNamespaceURI()
{
return null;
}
/**
* Introduced in DOM Level 2.
*
* The namespace prefix of this node, or null if it is unspecified. When
* this node is of any type other than ELEMENT_NODE and ATTRIBUTE_NODE this
* is always null and setting it has no effect.
*
* For nodes created with a DOM Level 1 method, such as createElement
* from the Document interface, this is null.
*
* @since WD-DOM-Level-2-19990923
* @see AttrNSImpl
* @see ElementNSImpl
*/
public String getPrefix()
{
return null;
}
/**
* Introduced in DOM Level 2.
*
* The namespace prefix of this node, or null if it is unspecified. When
* this node is of any type other than ELEMENT_NODE and ATTRIBUTE_NODE
* this is always null and setting it has no effect.
*
* For nodes created with a DOM Level 1 method, such as createElement from
* the Document interface, this is null.
*
* Note that setting this attribute changes the nodeName attribute, which
* holds the qualified name, as well as the tagName and name attributes of
* the Element and Attr interfaces, when applicable.
*
* @throws INVALID_CHARACTER_ERR Raised if the specified
* prefix contains an invalid character.
*
* @since WD-DOM-Level-2-19990923
* @see AttrNSImpl
* @see ElementNSImpl
*/
public void setPrefix(String prefix)
throws DOMException
{
throw new DOMException(DOMException.NAMESPACE_ERR,
"DOM003 Namespace error");
}
/**
* Introduced in DOM Level 2.
*
* Returns the local part of the qualified name of this node.
* For nodes created with a DOM Level 1 method, such as createElement
* from the Document interface, and for nodes of any type other than
* ELEMENT_NODE and ATTRIBUTE_NODE this is the same as the nodeName
* attribute.
* @since WD-DOM-Level-2-19990923
* @see AttrNSImpl
* @see ElementNSImpl
*/
public String getLocalName()
{
return null;
}
//
// EventTarget support
//
public void addEventListener(String type, EventListener listener,
boolean useCapture) {
// simply forward to Document
ownerDocument().addEventListener(this, type, listener, useCapture);
}
public void removeEventListener(String type, EventListener listener,
boolean useCapture) {
// simply forward to Document
ownerDocument().removeEventListener(this, type, listener, useCapture);
}
public boolean dispatchEvent(Event event) {
// simply forward to Document
return ownerDocument().dispatchEvent(this, event);
}
//
// Public methods
//
/**
* NON-DOM: PR-DOM-Level-1-19980818 mentions readonly nodes in conjunction
* with Entities, but provides no API to support this.
*
* Most DOM users should not touch this method. Its anticpated use
* is during construction of EntityRefernces, where it will be used to
* lock the contents replicated from Entity so they can't be casually
* altered. It _could_ be published as a DOM extension, if desired.
*
* Note: since we never have any children deep is meaningless here,
* ParentNode overrides this behavior.
* @see ParentNode
*
* @param readOnly True or false as desired.
* @param deep If true, children are also toggled. Note that this will
* not change the state of an EntityReference or its children,
* which are always read-only.
*/
public void setReadOnly(boolean readOnly, boolean deep) {
if (needsSyncData()) {
synchronizeData();
}
isReadOnly(readOnly);
} // setReadOnly(boolean,boolean)
/**
* NON-DOM: Returns true if this node is read-only. This is a
* shallow check.
*/
public boolean getReadOnly() {
if (needsSyncData()) {
synchronizeData();
}
return isReadOnly();
} // getReadOnly():boolean
/**
* NON-DOM: As an alternative to subclassing the DOM, this implementation
* has been extended with the ability to attach an object to each node.
* (If you need multiple objects, you can attach a collection such as a
* vector or hashtable, then attach your application information to that.)
* Important Note: You are responsible for removing references
* to your data on nodes that are no longer used. Failure to do so will
* prevent the nodes, your data is attached to, to be garbage collected
* until the whole document is.
*
* @param data the object to store or null to remove any existing reference
*/
public void setUserData(Object data) {
ownerDocument().setUserData(this, data);
}
/**
* NON-DOM:
* Returns the user data associated to this node.
*/
public Object getUserData() {
return ownerDocument().getUserData(this);
}
//
// Protected methods
//
/**
* Denotes that this node has changed.
*/
protected void changed() {
// we do not actually store this information on every node, we only
// have a global indicator on the Document. Doing otherwise cost us too
// much for little gain.
ownerDocument().changed();
}
/**
* Returns the number of changes to this node.
*/
protected int changes() {
// we do not actually store this information on every node, we only
// have a global indicator on the Document. Doing otherwise cost us too
// much for little gain.
return ownerDocument().changes();
}
/**
* Override this method in subclass to hook in efficient
* internal data structure.
*/
protected void synchronizeData() {
// By default just change the flag to avoid calling this method again
needsSyncData(false);
}
/*
* Flags setters and getters
*/
final boolean isReadOnly() {
return (flags & READONLY) != 0;
}
final void isReadOnly(boolean value) {
flags = (short) (value ? flags | READONLY : flags & ~READONLY);
}
final boolean needsSyncData() {
return (flags & SYNCDATA) != 0;
}
final void needsSyncData(boolean value) {
flags = (short) (value ? flags | SYNCDATA : flags & ~SYNCDATA);
}
final boolean needsSyncChildren() {
return (flags & SYNCCHILDREN) != 0;
}
final void needsSyncChildren(boolean value) {
flags = (short) (value ? flags | SYNCCHILDREN : flags & ~SYNCCHILDREN);
}
final boolean isOwned() {
return (flags & OWNED) != 0;
}
final void isOwned(boolean value) {
flags = (short) (value ? flags | OWNED : flags & ~OWNED);
}
final boolean isFirstChild() {
return (flags & FIRSTCHILD) != 0;
}
final void isFirstChild(boolean value) {
flags = (short) (value ? flags | FIRSTCHILD : flags & ~FIRSTCHILD);
}
final boolean isSpecified() {
return (flags & SPECIFIED) != 0;
}
final void isSpecified(boolean value) {
flags = (short) (value ? flags | SPECIFIED : flags & ~SPECIFIED);
}
// inconsistent name to avoid clash with public method on TextImpl
final boolean internalIsIgnorableWhitespace() {
return (flags & IGNORABLEWS) != 0;
}
final void isIgnorableWhitespace(boolean value) {
flags = (short) (value ? flags | IGNORABLEWS : flags & ~IGNORABLEWS);
}
final boolean hasStringValue() {
return (flags & HASSTRING) != 0;
}
final void hasStringValue(boolean value) {
flags = (short) (value ? flags | HASSTRING : flags & ~HASSTRING);
}
final boolean isNormalized() {
return (flags & UNNORMALIZED) == 0;
}
final void isNormalized(boolean value) {
// See if flag should propagate to parent.
if (!value && isNormalized() && ownerNode != null) {
ownerNode.isNormalized(false);
}
flags = (short) (value ? flags & ~UNNORMALIZED : flags | UNNORMALIZED);
}
//
// Object methods
//
/** NON-DOM method for debugging convenience. */
public String toString() {
return "["+getNodeName()+": "+getNodeValue()+"]";
}
//
// Serialization methods
//
/** Serialize object. */
private void writeObject(ObjectOutputStream out) throws IOException {
// synchronize data
if (needsSyncData()) {
synchronizeData();
}
// write object
out.defaultWriteObject();
} // writeObject(ObjectOutputStream)
} // class NodeImpl
true if this node has any attributes,
* false otherwise.
* @since DOM Level 2
* @see ElementImpl
*/
public boolean hasAttributes() {
return false; // overridden in ElementImpl
}
/**
* Test whether this node has any children. Convenience shorthand
* for (Node.getFirstChild()!=null)
* Text nodes in the full depth of the sub-tree
* underneath this Node, including attribute nodes, into a
* "normal" form where only markup (e.g., tags, comments, processing
* instructions, CDATA sections, and entity references) separates
* Text nodes, i.e., there are no adjacent Text
* nodes. This can be used to ensure that the DOM view of a document is
* the same as if it were saved and re-loaded, and is useful when
* operations (such as XPointer lookups) that depend on a particular
* document tree structure are to be used.In cases where the document
* contains CDATASections, the normalize operation alone may
* not be sufficient, since XPointers do not differentiate between
* Text nodes and CDATASection nodes.
*