KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xerces > dom > DeferredEntityReferenceImpl


1 /*
2  * Copyright 1999-2002,2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.apache.xerces.dom;
18
19 /**
20  * EntityReference models the XML &entityname; syntax, when used for
21  * entities defined by the DOM. Entities hardcoded into XML, such as
22  * character entities, should instead have been translated into text
23  * by the code which generated the DOM tree.
24  * <P>
25  * An XML processor has the alternative of fully expanding Entities
26  * into the normal document tree. If it does so, no EntityReference nodes
27  * will appear.
28  * <P>
29  * Similarly, non-validating XML processors are not required to read
30  * or process entity declarations made in the external subset or
31  * declared in external parameter entities. Hence, some applications
32  * may not make the replacement value available for Parsed Entities
33  * of these types.
34  * <P>
35  * EntityReference behaves as a read-only node, and the children of
36  * the EntityReference (which reflect those of the Entity, and should
37  * also be read-only) give its replacement value, if any. They are
38  * supposed to automagically stay in synch if the DocumentType is
39  * updated with new values for the Entity.
40  * <P>
41  * The defined behavior makes efficient storage difficult for the DOM
42  * implementor. We can't just look aside to the Entity's definition
43  * in the DocumentType since those nodes have the wrong parent (unless
44  * we can come up with a clever "imaginary parent" mechanism). We
45  * must at least appear to clone those children... which raises the
46  * issue of keeping the reference synchronized with its parent.
47  * This leads me back to the "cached image of centrally defined data"
48  * solution, much as I dislike it.
49  * <P>
50  * For now I have decided, since REC-DOM-Level-1-19980818 doesn't
51  * cover this in much detail, that synchronization doesn't have to be
52  * considered while the user is deep in the tree. That is, if you're
53  * looking within one of the EntityReferennce's children and the Entity
54  * changes, you won't be informed; instead, you will continue to access
55  * the same object -- which may or may not still be part of the tree.
56  * This is the same behavior that obtains elsewhere in the DOM if the
57  * subtree you're looking at is deleted from its parent, so it's
58  * acceptable here. (If it really bothers folks, we could set things
59  * up so deleted subtrees are walked and marked invalid, but that's
60  * not part of the DOM's defined behavior.)
61  * <P>
62  * As a result, only the EntityReference itself has to be aware of
63  * changes in the Entity. And it can take advantage of the same
64  * structure-change-monitoring code I implemented to support
65  * DeepNodeList.
66  *
67  * @xerces.internal
68  *
69  * @version $Id: DeferredEntityReferenceImpl.java,v 1.21 2004/10/05 17:12:50 mrglavas Exp $
70  * @since PR-DOM-Level-1-19980818.
71  */
72 public class DeferredEntityReferenceImpl
73     extends EntityReferenceImpl
74     implements DeferredNode {
75
76     //
77 // Constants
78 //
79
80     /** Serialization version. */
81     static final long serialVersionUID = 390319091370032223L;
82     
83     //
84 // Data
85 //
86
87     /** Node index. */
88     protected transient int fNodeIndex;
89
90     //
91 // Constructors
92 //
93
94     /**
95      * This is the deferred constructor. Only the fNodeIndex is given here.
96      * All other data, can be requested from the ownerDocument via the index.
97      */
98     DeferredEntityReferenceImpl(DeferredDocumentImpl ownerDocument,
99                                 int nodeIndex) {
100         super(ownerDocument, null);
101
102         fNodeIndex = nodeIndex;
103         needsSyncData(true);
104
105     } // <init>(DeferredDocumentImpl,int)
106
107     //
108 // DeferredNode methods
109 //
110
111     /** Returns the node index. */
112     public int getNodeIndex() {
113         return fNodeIndex;
114     }
115
116     //
117 // Protected methods
118 //
119
120     /**
121      * Synchronize the entity data. This is special because of the way
122      * that the "fast" version stores the information.
123      */
124     protected void synchronizeData() {
125
126         // no need to sychronize again
127 needsSyncData(false);
128
129         // get the node data
130 DeferredDocumentImpl ownerDocument =
131             (DeferredDocumentImpl)this.ownerDocument;
132         name = ownerDocument.getNodeName(fNodeIndex);
133         baseURI = ownerDocument.getNodeValue(fNodeIndex);
134         
135     } // synchronizeData()
136
137     /** Synchronize the children. */
138     protected void synchronizeChildren() {
139
140         // no need to synchronize again
141 needsSyncChildren(false);
142
143         // get children
144 isReadOnly(false);
145         DeferredDocumentImpl ownerDocument =
146             (DeferredDocumentImpl) ownerDocument();
147         ownerDocument.synchronizeChildren(this, fNodeIndex);
148         setReadOnly(true, true);
149
150     } // synchronizeChildren()
151
152 } // class DeferredEntityReferenceImpl
153
Popular Tags