KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xml > dtm > ref > DTMNodeIterator


1 /*
2  * Copyright 1999-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: DTMNodeIterator.java,v 1.9 2004/02/16 23:06:11 minchau Exp $
18  */
19 package org.apache.xml.dtm.ref;
20
21 import org.apache.xml.dtm.DTM;
22 import org.apache.xml.dtm.DTMDOMException;
23 import org.apache.xml.dtm.DTMIterator;
24
25 import org.w3c.dom.DOMException JavaDoc;
26 import org.w3c.dom.Node JavaDoc;
27 import org.w3c.dom.traversal.NodeFilter;
28
29 /**
30  * <code>DTMNodeIterator</code> gives us an implementation of the
31  * DTMNodeIterator which returns DOM nodes.
32  *
33  * Please note that this is not necessarily equivlaent to a DOM
34  * NodeIterator operating over the same document. In particular:
35  * <ul>
36  *
37  * <li>If there are several Text nodes in logical succession (ie,
38  * across CDATASection and EntityReference boundaries), we will return
39  * only the first; the caller is responsible for stepping through
40  * them.
41  * (%REVIEW% Provide a convenience routine here to assist, pending
42  * proposed DOM Level 3 getAdjacentText() operation?) </li>
43  *
44  * <li>Since the whole XPath/XSLT architecture assumes that the source
45  * document is not altered while we're working with it, we do not
46  * promise to implement the DOM NodeIterator's "maintain current
47  * position" response to document mutation. </li>
48  *
49  * <li>Since our design for XPath NodeIterators builds a stateful
50  * filter directly into the traversal object, getNodeFilter() is not
51  * supported.</li>
52  *
53  * </ul>
54  *
55  * <p>State: In progress!!</p>
56  * */
57 public class DTMNodeIterator implements org.w3c.dom.traversal.NodeIterator
58 {
59   private DTMIterator dtm_iter;
60   private boolean valid=true;
61
62   //================================================================
63 // Methods unique to this class
64
65   /** Public constructor: Wrap a DTMNodeIterator around an existing
66    * and preconfigured DTMIterator
67    * */
68   public DTMNodeIterator(DTMIterator dtmIterator)
69     {
70       try
71       {
72         dtm_iter=(DTMIterator)dtmIterator.clone();
73       }
74       catch(CloneNotSupportedException JavaDoc cnse)
75       {
76         throw new org.apache.xml.utils.WrappedRuntimeException(cnse);
77       }
78     }
79
80   /** Access the wrapped DTMIterator. I'm not sure whether anyone will
81    * need this or not, but let's write it and think about it.
82    * */
83   public DTMIterator getDTMIterator()
84     {
85       return dtm_iter;
86     }
87   
88
89   //================================================================
90 // org.w3c.dom.traversal.NodeFilter API follows
91
92   /** Detaches the NodeIterator from the set which it iterated over,
93    * releasing any computational resources and placing the iterator in
94    * the INVALID state.
95    * */
96   public void detach()
97     {
98       // Theoretically, we could release dtm_iter at this point. But
99 // some of the operations may still want to consult it even though
100 // navigation is now invalid.
101 valid=false;
102     }
103
104   /** The value of this flag determines whether the children
105    * of entity reference nodes are visible to the iterator.
106    *
107    * @return false, always (the DTM model flattens entity references)
108    * */
109   public boolean getExpandEntityReferences()
110     {
111       return false;
112     }
113   
114   /** Return a handle to the filter used to screen nodes.
115    *
116    * This is ill-defined in Xalan's usage of Nodeiterator, where we have
117    * built stateful XPath-based filtering directly into the traversal
118    * object. We could return something which supports the NodeFilter interface
119    * and allows querying whether a given node would be permitted if it appeared
120    * as our next node, but in the current implementation that would be very
121    * complex -- and just isn't all that useful.
122    *
123    * @throws DOMException -- NOT_SUPPORTED_ERROR because I can't think
124    * of anything more useful to do in this case
125    * */
126   public NodeFilter getFilter()
127     {
128       throw new DTMDOMException(DOMException.NOT_SUPPORTED_ERR);
129     }
130   
131
132   /** @return The root node of the NodeIterator, as specified
133    * when it was created.
134    * */
135   public Node JavaDoc getRoot()
136     {
137       int handle=dtm_iter.getRoot();
138       return dtm_iter.getDTM(handle).getNode(handle);
139     }
140   
141
142   /** Return a mask describing which node types are presented via the
143    * iterator.
144    **/
145   public int getWhatToShow()
146     {
147       return dtm_iter.getWhatToShow();
148     }
149
150   /** @return the next node in the set and advance the position of the
151    * iterator in the set.
152    *
153    * @throws DOMException - INVALID_STATE_ERR Raised if this method is
154    * called after the detach method was invoked.
155    * */
156   public Node JavaDoc nextNode() throws DOMException
157     {
158       if(!valid)
159         throw new DTMDOMException(DOMException.INVALID_STATE_ERR);
160       
161       int handle=dtm_iter.nextNode();
162       if (handle==DTM.NULL)
163         return null;
164       return dtm_iter.getDTM(handle).getNode(handle);
165     }
166   
167
168   /** @return the next previous in the set and advance the position of the
169    * iterator in the set.
170    *
171    * @throws DOMException - INVALID_STATE_ERR Raised if this method is
172    * called after the detach method was invoked.
173    * */
174   public Node JavaDoc previousNode()
175     {
176       if(!valid)
177         throw new DTMDOMException(DOMException.INVALID_STATE_ERR);
178       
179       int handle=dtm_iter.previousNode();
180       if (handle==DTM.NULL)
181         return null;
182       return dtm_iter.getDTM(handle).getNode(handle);
183     }
184 }
185
Popular Tags