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