KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xml > serializer > ElemContext


1 /*
2  * Copyright 2003-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  * $Id: ElemContext.java,v 1.2 2004/02/17 04:18:19 minchau Exp $
18  */
19 package org.apache.xml.serializer;
20
21 /**
22  * This class is a stack frame that consists of
23  * information about the element currently being processed
24  * by a serializer. Consider this example:
25  * <pre>
26  * <A>
27  * <B1>
28  * </B1>
29  * <B2>
30  * </B2>
31  * <A>
32  * </pre>
33  *
34  * A stack frame will be pushed for "A" at depth 1,
35  * then another one for "B1" at depth 2.
36  * Then "B1" stackframe is popped. When the stack frame for "B2" is
37  * pushed, this implementation re-uses the old stack fram object used
38  * by "B1" to be efficient at not creating too many of these object.
39  *
40  * This is by no means a public class, and neither are its fields or methods,
41  * they are all helper fields for a serializer.
42  *
43  * The purpose of this class is to be more consistent with pushing information
44  * when a new element is being serialized and more quickly restoring the old
45  * information about the parent element with a simple pop() when the
46  * child element is done. Previously there was some redundant and error-prone
47  * calculations going on to retore information.
48  *
49  */
50 class ElemContext
51 {
52     // Fields that form the context of the element
53
54     /**
55      * The nesting depth of the element inside other elements.
56      */
57     final int m_currentElemDepth;
58
59     /** HTML field, the element description of the HTML element */
60     ElemDesc m_elementDesc = null;
61
62     /**
63      * The local name of the element.
64      */
65     String JavaDoc m_elementLocalName = null;
66
67     /**
68      * The fully qualified name of the element (with prefix, if any).
69      */
70     String JavaDoc m_elementName = null;
71
72     /**
73      * The URI of the element.
74      */
75     String JavaDoc m_elementURI = null;
76
77     /** If the element is in the cdata-section-names list
78      * then the value is true. If it is true the text children of the element
79      * should be output in CDATA section blocks.
80      */
81     boolean m_isCdataSection;
82
83     /** True if the current element has output escaping disabled.
84      * This is true for SCRIPT and STYLE elements.
85      */
86     boolean m_isRaw = false;
87
88     /** The next element "stack frame". This value will only be
89      * set once as deeper stack frames are not deleted when popped off,
90      * but are rather re-used when a push is required.
91      *
92      * This makes for very fast pushing and popping of stack frames
93      * because very few stack frame objects are ever created, they are
94      * mostly re-used. This re-use saves object creation but it also means
95      * that connections between the frames via m_next and m_prev
96      * never changes either. Just the contents of the frames change
97      * as they are re-used. Only the reference to the current stack frame, which
98      * is held by the serializer is changed via a quick pop() or push().
99      */
100     private ElemContext m_next;
101
102     /** The previous element "stack frame". */
103     final ElemContext m_prev;
104
105     /**
106      * Set to true when a start tag is started, or open, but not all the
107      * attributes or namespace information is yet collected.
108      */
109     boolean m_startTagOpen = false;
110
111     /**
112      * Constructor to create the root of the element contexts.
113      *
114      */
115     ElemContext()
116     {
117         // this assignment means can never pop this context off
118 m_prev = this;
119         // depth 0 because it doesn't correspond to any element
120 m_currentElemDepth = 0;
121     }
122
123     /**
124      * Constructor to create the "stack frame" for a given element depth.
125      *
126      * This implementation will re-use the context at each depth. If
127      * a documents deepest element depth is N then there will be (N+1)
128      * such objects created, no more than that.
129      *
130      * @param previous The "stack frame" corresponding to the new
131      * elements parent element.
132      */
133     private ElemContext(final ElemContext previous)
134     {
135         m_prev = previous;
136         m_currentElemDepth = previous.m_currentElemDepth + 1;
137     }
138
139     /**
140      * Pop the current "stack frame".
141      * @return Returns the parent "stack frame" of the one popped.
142      */
143     final ElemContext pop()
144     {
145         /* a very simple pop. No clean up is done of the deeper
146          * stack frame. All deeper stack frames are still attached
147          * but dormant, just waiting to be re-used.
148          */
149         return this.m_prev;
150     }
151
152     /**
153      * This method pushes an element "stack frame"
154      * but with no initialization of values in that frame.
155      * This method is used for optimization purposes, like when pushing
156      * a stack frame for an HTML "IMG" tag which has no children and
157      * the stack frame will almost immediately be popped.
158      */
159     final ElemContext push()
160     {
161         ElemContext frame = this.m_next;
162         if (frame == null)
163         {
164             /* We have never been at this depth yet, and there is no
165              * stack frame to re-use, so we now make a new one.
166              */
167             frame = new ElemContext(this);
168             this.m_next = frame;
169         }
170         /*
171          * We shouldn't need to set this true because we should just
172          * be pushing a dummy stack frame that will be instantly popped.
173          * Yet we need to be ready in case this element does have
174          * unexpected children.
175          */
176         frame.m_startTagOpen = true;
177         return frame;
178     }
179     
180     /**
181      * Push an element context on the stack. This context keeps track of
182      * information gathered about the element.
183      * @param uri The URI for the namespace for the element name,
184      * can be null if it is not yet known.
185      * @param localName The local name of the element (no prefix),
186      * can be null.
187      * @param qName The qualified name (with prefix, if any)
188      * of the element, this parameter is required.
189      */
190     final ElemContext push(
191         final String JavaDoc uri,
192         final String JavaDoc localName,
193         final String JavaDoc qName)
194     {
195         ElemContext frame = this.m_next;
196         if (frame == null)
197         {
198             /* We have never been at this depth yet, and there is no
199              * stack frame to re-use, so we now make a new one.
200              */
201             frame = new ElemContext(this);
202             this.m_next = frame;
203         }
204
205         // Initialize, or reset values in the new or re-used stack frame.
206 frame.m_elementName = qName;
207         frame.m_elementLocalName = localName;
208         frame.m_elementURI = uri;
209         frame.m_isCdataSection = false;
210         frame.m_startTagOpen = true;
211
212         // is_Raw is already set in the HTML startElement() method
213 // frame.m_isRaw = false;
214 return frame;
215     }
216 }
217
Popular Tags