DeferredEntityReferenceImpl


1   /*
2    * The Apache Software License, Version 1.1
3    *
4    *
5    * Copyright (c) 1999 The Apache Software Foundation.  All rights 
6    * reserved.
7    *
8    * Redistribution and use in source and binary forms, with or without
9    * modification, are permitted provided that the following conditions
10   * are met:
11   *
12   * 1. Redistributions of source code must retain the above copyright
13   *    notice, this list of conditions and the following disclaimer. 
14   *
15   * 2. Redistributions in binary form must reproduce the above copyright
16   *    notice, this list of conditions and the following disclaimer in
17   *    the documentation and/or other materials provided with the
18   *    distribution.
19   *
20   * 3. The end-user documentation included with the redistribution,
21   *    if any, must include the following acknowledgment:  
22   *       "This product includes software developed by the
23   *        Apache Software Foundation (http://www.apache.org/)."
24   *    Alternately, this acknowledgment may appear in the software itself,
25   *    if and wherever such third-party acknowledgments normally appear.
26   *
27   * 4. The names "Xerces" and "Apache Software Foundation" must
28   *    not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written 
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation and was
52   * originally based on software copyright (c) 1999, International
53   * Business Machines, Inc., http://www.apache.org.  For more
54   * information on the Apache Software Foundation, please see
55   * <http://www.apache.org/>.
56   */
57  
58  package org.enhydra.apache.xerces.dom;
59  
60  import org.w3c.dom.DocumentType  ;
61  import org.w3c.dom.Entity  ;
62  import org.w3c.dom.NamedNodeMap  ;
63  import org.w3c.dom.Node  ;
64  
65  /**
66   * EntityReference models the XML &entityname; syntax, when used for
67   * entities defined by the DOM. Entities hardcoded into XML, such as
68   * character entities, should instead have been translated into text
69   * by the code which generated the DOM tree.
70   * <P>
71   * An XML processor has the alternative of fully expanding Entities
72   * into the normal document tree. If it does so, no EntityReference nodes
73   * will appear.
74   * <P>
75   * Similarly, non-validating XML processors are not required to read
76   * or process entity declarations made in the external subset or
77   * declared in external parameter entities. Hence, some applications
78   * may not make the replacement value available for Parsed Entities 
79   * of these types.
80   * <P>
81   * EntityReference behaves as a read-only node, and the children of 
82   * the EntityReference (which reflect those of the Entity, and should
83   * also be read-only) give its replacement value, if any. They are 
84   * supposed to automagically stay in synch if the DocumentType is 
85   * updated with new values for the Entity.
86   * <P>
87   * The defined behavior makes efficient storage difficult for the DOM
88   * implementor. We can't just look aside to the Entity's definition
89   * in the DocumentType since those nodes have the wrong parent (unless
90   * we can come up with a clever "imaginary parent" mechanism). We
91   * must at least appear to clone those children... which raises the
92   * issue of keeping the reference synchronized with its parent.
93   * This leads me back to the "cached image of centrally defined data"
94   * solution, much as I dislike it.
95   * <P>
96   * For now I have decided, since REC-DOM-Level-1-19980818 doesn't
97   * cover this in much detail, that synchronization doesn't have to be
98   * considered while the user is deep in the tree. That is, if you're
99   * looking within one of the EntityReferennce's children and the Entity
100  * changes, you won't be informed; instead, you will continue to access
101  * the same object -- which may or may not still be part of the tree.
102  * This is the same behavior that obtains elsewhere in the DOM if the
103  * subtree you're looking at is deleted from its parent, so it's
104  * acceptable here. (If it really bothers folks, we could set things
105  * up so deleted subtrees are walked and marked invalid, but that's
106  * not part of the DOM's defined behavior.)
107  * <P>
108  * As a result, only the EntityReference itself has to be aware of
109  * changes in the Entity. And it can take advantage of the same
110  * structure-change-monitoring code I implemented to support
111  * DeepNodeList.
112  * 
113  * @version
114  * @since  PR-DOM-Level-1-19980818.
115  */
116 public class DeferredEntityReferenceImpl 
117     extends EntityReferenceImpl 
118     implements DeferredNode {
119 
120     //
121     // Constants
122     //
123 
124     /** Serialization version. */
125     static final long serialVersionUID = 390319091370032223L;
126     
127     //
128     // Data
129     //
130 
131     /** Node index. */
132     protected transient int fNodeIndex;
133 
134     //
135     // Constructors
136     //
137 
138     /**
139      * This is the deferred constructor. Only the fNodeIndex is given here. 
140      * All other data, can be requested from the ownerDocument via the index.
141      */
142     DeferredEntityReferenceImpl(DeferredDocumentImpl ownerDocument, int nodeIndex) {
143         super(ownerDocument, null);
144 
145         fNodeIndex = nodeIndex;
146         needsSyncData(true);
147         needsSyncChildren(true);
148 
149     } // <init>(DeferredDocumentImpl,int)
150 
151     //
152     // DeferredNode methods
153     //
154 
155     /** Returns the node index. */
156     public int getNodeIndex() {
157         return fNodeIndex;
158     }
159 
160     //
161     // Protected methods
162     //
163 
164     /** 
165      * Synchronize the entity data. This is special because of the way
166      * that the "fast" version stores the information.
167      */
168     protected void synchronizeData() {
169 
170         // no need to sychronize again
171         needsSyncData(false);
172 
173         // get the node data
174         DeferredDocumentImpl ownerDocument = (DeferredDocumentImpl)this.ownerDocument;
175         name = ownerDocument.getNodeNameString(fNodeIndex);
176         
177     } // synchronizeData()
178 
179     /** Synchronize the children. */
180     protected void synchronizeChildren() {
181 
182         // no need to synchronize again
183         needsSyncChildren(false);
184 
185         // get children
186         DocumentType   doctype = ownerDocument.getDoctype();
187         boolean found = false;
188         if (doctype != null) {
189 
190             // we don't want to generate any event for this so turn them off
191             boolean orig = ownerDocument.getMutationEvents();
192             ownerDocument.setMutationEvents(false);
193 
194             NamedNodeMap   entities = doctype.getEntities();
195             if (entities != null) {
196                 Entity   entity = (Entity  )entities.getNamedItem(getNodeName());
197                 if (entity != null) {
198 
199                     // we found the entity
200                     found = true;
201 
202                     // clone entity at this reference
203                     boolean ro = isReadOnly();
204                     isReadOnly(false);
205                     Node   child = entity.getFirstChild();
206                     while (child != null) {
207                         appendChild(child.cloneNode(true));
208                         child = child.getNextSibling();
209                     }
210                     // set it back to readonly if what it was
211                     if (ro) {
212                         setReadOnly(true, true);
213                     }
214                 }
215             }
216             // set mutation events flag back to its original value
217             ownerDocument.setMutationEvents(orig);
218         }
219 
220         // if not found, create entity at this reference
221         if (!found) {
222             isReadOnly(false);
223             DeferredDocumentImpl ownerDocument =
224                 (DeferredDocumentImpl) ownerDocument();
225             ownerDocument.synchronizeChildren(this, fNodeIndex);
226             setReadOnly(true, true);
227         }
228 
229     } // synchronizeChildren()
230 
231     // inhibit the synchronize inherited from EntityReferenceImpl
232     protected void synchronize() {
233     }
234 
235 } // class DeferredEntityReferenceImpl
236
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags