/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xerces" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, International
* Business Machines, Inc., http://www.apache.org. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xerces.dom;
import org.w3c.dom.DocumentType;
import org.w3c.dom.Entity;
import org.w3c.dom.NamedNodeMap;
import org.w3c.dom.Node;
/**
* 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.
* <P>
* An XML processor has the alternative of fully expanding Entities
* into the normal document tree. If it does so, no EntityReference nodes
* will appear.
* <P>
* 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.
* <P>
* 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.
* <P>
* 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.
* <P>
* 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.)
* <P>
* 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.
*
* @version
* @since PR-DOM-Level-1-19980818.
*/
public class DeferredEntityReferenceImpl
extends EntityReferenceImpl
implements DeferredNode {
//
// Constants
//
/** Serialization version. */
static final long serialVersionUID = 390319091370032223L;
//
// Data
//
/** Node index. */
protected transient int fNodeIndex;
//
// Constructors
//
/**
* This is the deferred constructor. Only the fNodeIndex is given here.
* All other data, can be requested from the ownerDocument via the index.
*/
DeferredEntityReferenceImpl(DeferredDocumentImpl ownerDocument, int nodeIndex) {
super(ownerDocument, null);
fNodeIndex = nodeIndex;
needsSyncData(true);
needsSyncChildren(true);
} // <init>(DeferredDocumentImpl,int)
//
// DeferredNode methods
//
/** Returns the node index. */
public int getNodeIndex() {
return fNodeIndex;
}
//
// Protected methods
//
/**
* Synchronize the entity data. This is special because of the way
* that the "fast" version stores the information.
*/
protected void synchronizeData() {
// no need to sychronize again
needsSyncData(false);
// get the node data
DeferredDocumentImpl ownerDocument = (DeferredDocumentImpl)this.ownerDocument;
name = ownerDocument.getNodeNameString(fNodeIndex);
} // synchronizeData()
/** Synchronize the children. */
protected void synchronizeChildren() {
// no need to synchronize again
needsSyncChildren(false);
// get children
DocumentType doctype = ownerDocument.getDoctype();
boolean found = false;
if (doctype != null) {
// we don't want to generate any event for this so turn them off
boolean orig = ownerDocument.getMutationEvents();
ownerDocument.setMutationEvents(false);
NamedNodeMap entities = doctype.getEntities();
if (entities != null) {
Entity entity = (Entity)entities.getNamedItem(getNodeName());
if (entity != null) {
// we found the entity
found = true;
// clone entity at this reference
boolean ro = isReadOnly();
isReadOnly(false);
Node child = entity.getFirstChild();
while (child != null) {
appendChild(child.cloneNode(true));
child = child.getNextSibling();
}
// set it back to readonly if what it was
if (ro) {
setReadOnly(true, true);
}
}
}
// set mutation events flag back to its original value
ownerDocument.setMutationEvents(orig);
}
// if not found, create entity at this reference
if (!found) {
isReadOnly(false);
DeferredDocumentImpl ownerDocument =
(DeferredDocumentImpl) ownerDocument();
ownerDocument.synchronizeChildren(this, fNodeIndex);
setReadOnly(true, true);
}
} // synchronizeChildren()
// inhibit the synchronize inherited from EntityReferenceImpl
protected void synchronize() {
}
} // class DeferredEntityReferenceImpl