EntityReferenceImpl

Class Overview

EntityReference models the XML &entityname; syntax, when used for entities defined by the DOM. Entities hardcoded into XML, such as character entities, should instead have been translated into text by the code which generated the DOM tree.

An XML processor has the alternative of fully expanding Entities into the normal document tree. If it does so, no EntityReference nodes will appear.

Similarly, non-validating XML processors are not required to read or process entity declarations made in the external subset or declared in external parameter entities. Hence, some applications may not make the replacement value available for Parsed Entities of these types.

EntityReference behaves as a read-only node, and the children of the EntityReference (which reflect those of the Entity, and should also be read-only) give its replacement value, if any. They are supposed to automagically stay in synch if the DocumentType is updated with new values for the Entity.

The defined behavior makes efficient storage difficult for the DOM implementor. We can't just look aside to the Entity's definition in the DocumentType since those nodes have the wrong parent (unless we can come up with a clever "imaginary parent" mechanism). We must at least appear to clone those children... which raises the issue of keeping the reference synchronized with its parent. This leads me back to the "cached image of centrally defined data" solution, much as I dislike it.

For now I have decided, since REC-DOM-Level-1-19980818 doesn't cover this in much detail, that synchronization doesn't have to be considered while the user is deep in the tree. That is, if you're looking within one of the EntityReferennce's children and the Entity changes, you won't be informed; instead, you will continue to access the same object -- which may or may not still be part of the tree. This is the same behavior that obtains elsewhere in the DOM if the subtree you're looking at is deleted from its parent, so it's acceptable here. (If it really bothers folks, we could set things up so deleted subtrees are walked and marked invalid, but that's not part of the DOM's defined behavior.)

As a result, only the EntityReference itself has to be aware of changes in the Entity. And it can take advantage of the same structure-change-monitoring code I implemented to support DeepNodeList.@xerces.internal

Summary

[Expand] Inherited Constants
From class org.apache.xerces.dom.NodeImpl short DOCUMENT_POSITION_CONTAINS short DOCUMENT_POSITION_DISCONNECTED short DOCUMENT_POSITION_FOLLOWING short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC short DOCUMENT_POSITION_IS_CONTAINED short DOCUMENT_POSITION_PRECEDING short ELEMENT_DEFINITION_NODE Element definition node type. short FIRSTCHILD short HASSTRING short ID short IGNORABLEWS short NORMALIZED short OWNED short READONLY short SPECIFIED short SYNCCHILDREN short SYNCDATA short TREE_POSITION_ANCESTOR The node is an ancestor of the reference node. short TREE_POSITION_DESCENDANT The node is a descendant of the reference node. short TREE_POSITION_DISCONNECTED The two nodes are disconnected, they do not have any common ancestor. short TREE_POSITION_EQUIVALENT The two nodes have an equivalent position. short TREE_POSITION_FOLLOWING The node follows the reference node. short TREE_POSITION_PRECEDING The node precedes the reference node. short TREE_POSITION_SAME_NODE The two nodes are the same.
From interface org.w3c.dom.Node short ATTRIBUTE_NODE short CDATA_SECTION_NODE short COMMENT_NODE short DOCUMENT_FRAGMENT_NODE short DOCUMENT_NODE short DOCUMENT_POSITION_CONTAINED_BY short DOCUMENT_POSITION_CONTAINS short DOCUMENT_POSITION_DISCONNECTED short DOCUMENT_POSITION_FOLLOWING short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC short DOCUMENT_POSITION_PRECEDING short DOCUMENT_TYPE_NODE short ELEMENT_NODE short ENTITY_NODE short ENTITY_REFERENCE_NODE short NOTATION_NODE short PROCESSING_INSTRUCTION_NODE short TEXT_NODE

[Expand] Inherited Fields
From class org.apache.xerces.dom.ParentNode protected NodeListCache fNodeListCache NodeList cache protected ChildNode firstChild First child. protected CoreDocumentImpl ownerDocument Owner document.
From class org.apache.xerces.dom.ChildNode protected ChildNode nextSibling Next sibling. protected ChildNode previousSibling Previous sibling.
From class org.apache.xerces.dom.NodeImpl protected short flags protected NodeImpl ownerNode

[Expand] Inherited Methods
From class org.apache.xerces.dom.ParentNode Node cloneNode(boolean deep) Returns a duplicate of a given node. NodeList getChildNodes() Obtain a NodeList enumerating all children of this node. final NodeList getChildNodesUnoptimized() Create a NodeList to access children that is use by subclass elements that have methods named getLength() or item(int). Node getFirstChild() The first child of this Node, or null if none. Node getLastChild() The last child of this Node, or null if none. int getLength() NodeList method: Count the immediate children of this node Document getOwnerDocument() Find the Document that this Node belongs to (the document in whose context the Node was created). String getTextContent() This attribute returns the text content of this node and its descendants. boolean hasChildNodes() Test whether this node has any children. Node insertBefore(Node newChild, Node refChild) Move one or more node(s) to our list of children. boolean isEqualNode(Node arg) DOM Level 3 WD- Experimental. Node item(int index) NodeList method: Return the Nth immediate child of this node, or null if the index is out of bounds. void normalize() Override default behavior to call normalize() on this Node's children. Node removeChild(Node oldChild) Remove a child from this Node. Node replaceChild(Node newChild, Node oldChild) Make newChild occupy the location that oldChild used to have. void setOwnerDocument(CoreDocumentImpl doc) NON-DOM set the ownerDocument of this node and its children void setReadOnly(boolean readOnly, boolean deep) Override default behavior so that if deep is true, children are also toggled. void setTextContent(String textContent) This attribute returns the text content of this node and its descendants. void synchronizeChildren() Override this method in subclass to hook in efficient internal data structure.
From class org.apache.xerces.dom.ChildNode Node cloneNode(boolean deep) Returns a duplicate of a given node. Node getNextSibling() The next child of this node's parent, or null if none Node getParentNode() Returns the parent node of this node Node getPreviousSibling() The previous child of this node's parent, or null if none
From class org.apache.xerces.dom.NodeImpl void addEventListener(String type, EventListener listener, boolean useCapture) Node appendChild(Node newChild) Adds a child node to the end of the list of children for this node. void changed() Denotes that this node has changed. int changes() Returns the number of changes to this node. Node cloneNode(boolean deep) Returns a duplicate of a given node. short compareDocumentPosition(Node other) Compares a node with this node with regard to their position in the document. short compareTreePosition(Node other) This method is deprecated. No replacement. boolean dispatchEvent(Event event) NamedNodeMap getAttributes() Return the collection of attributes associated with this node, or null if none. String getBaseURI() The absolute base URI of this node or null if undefined. NodeList getChildNodes() Obtain a NodeList enumerating all children of this node. Node getContainer() For non-child nodes, the node which "points" to this node. Object getFeature(String feature, String version) Node getFirstChild() The first child of this Node, or null if none. Node getLastChild() The first child of this Node, or null if none. int getLength() NodeList method: Count the immediate children of this node By default we do not have any children, ParentNode overrides this. String getLocalName() Introduced in DOM Level 2. String getNamespaceURI() Introduced in DOM Level 2. Node getNextSibling() The next child of this node's parent, or null if none abstract String getNodeName() the name of this node. int getNodeNumber() Returns the node number abstract short getNodeType() A short integer indicating what type of node this is. String getNodeValue() Returns the node value. Document getOwnerDocument() Find the Document that this Node belongs to (the document in whose context the Node was created). Node getParentNode() 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). String getPrefix() Introduced in DOM Level 2. Node getPreviousSibling() The previous child of this node's parent, or null if none boolean getReadOnly() NON-DOM: Returns true if this node is read-only. String getTextContent() This attribute returns the text content of this node and its descendants. Object getUserData() NON-DOM: Returns the user data associated to this node. Object getUserData(String key) Retrieves the object associated to a key on a this node. Hashtable getUserDataRecord() boolean hasAttributes() Returns whether this node (if it is an element) has any attributes. boolean hasChildNodes() Test whether this node has any children. Node insertBefore(Node newChild, Node refChild) Move one or more node(s) to our list of children. boolean isDefaultNamespace(String namespaceURI) DOM Level 3: Experimental This method checks if the specified namespaceURI is the default namespace or not. boolean isEqualNode(Node arg) Tests whether two nodes are equal. boolean isSameNode(Node other) Returns whether this node is the same node as the given one. boolean isSupported(String feature, String version) Introduced in DOM Level 2. Node item(int index) NodeList method: Return the Nth immediate child of this node, or null if the index is out of bounds. String lookupNamespaceURI(String specifiedPrefix) DOM Level 3 - Experimental: Look up the namespace URI associated to the given prefix, starting from this node. String lookupPrefix(String namespaceURI) DOM Level 3 - Experimental: Look up the prefix associated to the given namespace URI, starting from this node. final void needsSyncChildren(boolean value) void normalize() Puts all 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. Node removeChild(Node oldChild) Remove a child from this Node. void removeEventListener(String type, EventListener listener, boolean useCapture) Node replaceChild(Node newChild, Node oldChild) Make newChild occupy the location that oldChild used to have. void setNodeValue(String x) Sets the node value. void setOwnerDocument(CoreDocumentImpl doc) NON-DOM set the ownerDocument of this node void setPrefix(String prefix) Introduced in DOM Level 2. void setReadOnly(boolean readOnly, boolean deep) NON-DOM: PR-DOM-Level-1-19980818 mentions readonly nodes in conjunction with Entities, but provides no API to support this. void setTextContent(String textContent) This attribute returns the text content of this node and its descendants. Object setUserData(String key, Object data, UserDataHandler handler) Associate an object to a key on this node. void setUserData(Object data) NON-DOM: As an alternative to subclassing the DOM, this implementation has been extended with the ability to attach an object to each node. void synchronizeData() Override this method in subclass to hook in efficient internal data structure. String toString() NON-DOM method for debugging convenience.
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait() final void wait(long arg0, int arg1) final void wait(long arg0)
From interface org.w3c.dom.Node abstract Node appendChild(Node arg0) abstract Node cloneNode(boolean arg0) abstract short compareDocumentPosition(Node arg0) abstract NamedNodeMap getAttributes() abstract String getBaseURI() abstract NodeList getChildNodes() abstract Object getFeature(String arg0, String arg1) abstract Node getFirstChild() abstract Node getLastChild() abstract String getLocalName() abstract String getNamespaceURI() abstract Node getNextSibling() abstract String getNodeName() abstract short getNodeType() abstract String getNodeValue() abstract Document getOwnerDocument() abstract Node getParentNode() abstract String getPrefix() abstract Node getPreviousSibling() abstract String getTextContent() abstract Object getUserData(String arg0) abstract boolean hasAttributes() abstract boolean hasChildNodes() abstract Node insertBefore(Node arg0, Node arg1) abstract boolean isDefaultNamespace(String arg0) abstract boolean isEqualNode(Node arg0) abstract boolean isSameNode(Node arg0) abstract boolean isSupported(String arg0, String arg1) abstract String lookupNamespaceURI(String arg0) abstract String lookupPrefix(String arg0) abstract void normalize() abstract Node removeChild(Node arg0) abstract Node replaceChild(Node arg0, Node arg1) abstract void setNodeValue(String arg0) abstract void setPrefix(String arg0) abstract void setTextContent(String arg0) abstract Object setUserData(String arg0, Object arg1, UserDataHandler arg2)
From interface org.w3c.dom.NodeList abstract int getLength() abstract Node item(int arg0)
From interface org.w3c.dom.events.EventTarget abstract void addEventListener(String arg0, EventListener arg1, boolean arg2) abstract boolean dispatchEvent(Event arg0) abstract void removeEventListener(String arg0, EventListener arg1, boolean arg2)