org.apache.xerces.dom
Class EntityReferenceImpl

java.lang.Object
  extended by org.apache.xerces.dom.NodeImpl
      extended by org.apache.xerces.dom.ChildNode
          extended by org.apache.xerces.dom.ParentNode
              extended by org.apache.xerces.dom.EntityReferenceImpl
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, org.w3c.dom.EntityReference, org.w3c.dom.events.EventTarget, org.w3c.dom.Node, org.w3c.dom.NodeList
Direct Known Subclasses:
DeferredEntityReferenceImpl

public class EntityReferenceImpl
extends ParentNode
implements org.w3c.dom.EntityReference

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.

Since:
PR-DOM-Level-1-19980818.
Version:
$Id: EntityReferenceImpl.java 447266 2006-09-18 05:57:49Z mrglavas $
Author:
Arnaud Le Hors, IBM, Joe Kesselman, IBM, Andy Clark, IBM, Ralf Pfeiffer, IBM
See Also:
Serialized Form

INTERNAL:

Usage of this class is not supported. It may be altered or removed at any time.

Field Summary
protected  java.lang.String baseURI
          Base URI
protected  java.lang.String name
          Name of Entity referenced
 
Fields inherited from class org.apache.xerces.dom.ParentNode
firstChild, fNodeListCache, ownerDocument
 
Fields inherited from class org.apache.xerces.dom.ChildNode
nextSibling, previousSibling
 
Fields inherited from class org.apache.xerces.dom.NodeImpl
DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_IS_CONTAINED, DOCUMENT_POSITION_PRECEDING, ELEMENT_DEFINITION_NODE, FIRSTCHILD, flags, HASSTRING, ID, IGNORABLEWS, NORMALIZED, OWNED, ownerNode, READONLY, SPECIFIED, SYNCCHILDREN, SYNCDATA, TREE_POSITION_ANCESTOR, TREE_POSITION_DESCENDANT, TREE_POSITION_DISCONNECTED, TREE_POSITION_EQUIVALENT, TREE_POSITION_FOLLOWING, TREE_POSITION_PRECEDING, TREE_POSITION_SAME_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
EntityReferenceImpl(CoreDocumentImpl ownerDoc, java.lang.String name)
          Factory constructor.
 
Method Summary
 org.w3c.dom.Node cloneNode(boolean deep)
          Clone node.
 java.lang.String getBaseURI()
          Returns the absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI.
protected  java.lang.String getEntityRefValue()
          NON-DOM: compute string representation of the entity reference.
 java.lang.String getNodeName()
          Returns the name of the entity referenced
 short getNodeType()
          A short integer indicating what type of node this is.
 void setBaseURI(java.lang.String uri)
          NON-DOM: set base uri
 void setReadOnly(boolean readOnly, boolean deep)
          NON-DOM: sets the node and its children value.
protected  void synchronizeChildren()
          EntityReference's children are a reflection of those defined in the named Entity.
 
Methods inherited from class org.apache.xerces.dom.ParentNode
getChildNodes, getChildNodesUnoptimized, getFirstChild, getLastChild, getLength, getOwnerDocument, getTextContent, hasChildNodes, insertBefore, isEqualNode, item, normalize, removeChild, replaceChild, setOwnerDocument, setTextContent
 
Methods inherited from class org.apache.xerces.dom.ChildNode
getNextSibling, getParentNode, getPreviousSibling
 
Methods inherited from class org.apache.xerces.dom.NodeImpl
addEventListener, appendChild, changed, changes, compareDocumentPosition, compareTreePosition, dispatchEvent, getAttributes, getContainer, getFeature, getLocalName, getNamespaceURI, getNodeNumber, getNodeValue, getPrefix, getReadOnly, getUserData, getUserData, getUserDataRecord, hasAttributes, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, needsSyncChildren, removeEventListener, setNodeValue, setPrefix, setUserData, setUserData, synchronizeData, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.w3c.dom.Node
appendChild, compareDocumentPosition, getAttributes, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData
 

Field Detail

name

protected java.lang.String name
Name of Entity referenced


baseURI

protected java.lang.String baseURI
Base URI

Constructor Detail

EntityReferenceImpl

public EntityReferenceImpl(CoreDocumentImpl ownerDoc,
                           java.lang.String name)
Factory constructor.

Method Detail

getNodeType

public short getNodeType()
A short integer indicating what type of node this is. The named constants for this value are defined in the org.w3c.dom.Node interface.

Specified by:
getNodeType in interface org.w3c.dom.Node
Specified by:
getNodeType in class NodeImpl

getNodeName

public java.lang.String getNodeName()
Returns the name of the entity referenced

Specified by:
getNodeName in interface org.w3c.dom.Node
Specified by:
getNodeName in class NodeImpl

cloneNode

public org.w3c.dom.Node cloneNode(boolean deep)
Clone node.

Specified by:
cloneNode in interface org.w3c.dom.Node
Overrides:
cloneNode in class ParentNode
See Also:

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.


getBaseURI

public java.lang.String getBaseURI()
Returns the absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI. Note: If the URI is malformed, a null is returned.

Specified by:
getBaseURI in interface org.w3c.dom.Node
Overrides:
getBaseURI in class NodeImpl
Returns:
The absolute base URI of this node or null.
Since:
DOM Level 3

setBaseURI

public void setBaseURI(java.lang.String uri)
NON-DOM: set base uri


getEntityRefValue

protected java.lang.String getEntityRefValue()
NON-DOM: compute string representation of the entity reference. This method is used to retrieve a string value for an attribute node that has child nodes.

Returns:
String representing a value of this entity ref. or null if any node other than EntityReference, Text is encountered during computation

synchronizeChildren

protected void synchronizeChildren()
EntityReference's children are a reflection of those defined in the named Entity. This method creates them if they haven't been created yet. This doesn't support editing the Entity though, since this only called once for all.

Overrides:
synchronizeChildren in class ParentNode

setReadOnly

public void setReadOnly(boolean readOnly,
                        boolean deep)
NON-DOM: sets the node and its children value.

Note: make sure that entity reference and its kids could be set readonly.

Overrides:
setReadOnly in class ParentNode
Parameters:
readOnly - True or false as desired.
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.
See Also:

Note: this will not change the state of an EntityReference or its children, which are always read-only.



Copyright 1999-2010 The Apache Software Foundation. All Rights Reserved.