|
1 /* |
|
2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 #ifndef DOMNodeIterator_HEADER_GUARD_ |
|
18 #define DOMNodeIterator_HEADER_GUARD_ |
|
19 |
|
20 /* |
|
21 * Licensed to the Apache Software Foundation (ASF) under one or more |
|
22 * contributor license agreements. See the NOTICE file distributed with |
|
23 * this work for additional information regarding copyright ownership. |
|
24 * The ASF licenses this file to You under the Apache License, Version 2.0 |
|
25 * (the "License"); you may not use this file except in compliance with |
|
26 * the License. You may obtain a copy of the License at |
|
27 * |
|
28 * http://www.apache.org/licenses/LICENSE-2.0 |
|
29 * |
|
30 * Unless required by applicable law or agreed to in writing, software |
|
31 * distributed under the License is distributed on an "AS IS" BASIS, |
|
32 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
33 * See the License for the specific language governing permissions and |
|
34 * limitations under the License. |
|
35 */ |
|
36 |
|
37 /* |
|
38 * $Id: DOMNodeIterator.hpp 568078 2007-08-21 11:43:25Z amassari $ |
|
39 */ |
|
40 |
|
41 #include <xercesc/dom/DOMNodeFilter.hpp> |
|
42 #include <xercesc/dom/DOMNode.hpp> |
|
43 |
|
44 XERCES_CPP_NAMESPACE_BEGIN |
|
45 |
|
46 |
|
47 /** |
|
48 * <code>DOMNodeIterators</code> are used to step through a set of nodes, e.g. |
|
49 * the set of nodes in a <code>DOMNodeList</code>, the document subtree |
|
50 * governed by a particular <code>DOMNode</code>, the results of a query, or |
|
51 * any other set of nodes. The set of nodes to be iterated is determined by |
|
52 * the implementation of the <code>DOMNodeIterator</code>. DOM Level 2 |
|
53 * specifies a single <code>DOMNodeIterator</code> implementation for |
|
54 * document-order traversal of a document subtree. Instances of these |
|
55 * <code>DOMNodeIterators</code> are created by calling |
|
56 * <code>DOMDocumentTraversal</code><code>.createNodeIterator()</code>. |
|
57 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>. |
|
58 * @since DOM Level 2 |
|
59 */ |
|
60 class CDOM_EXPORT DOMNodeIterator |
|
61 { |
|
62 protected: |
|
63 // ----------------------------------------------------------------------- |
|
64 // Hidden constructors |
|
65 // ----------------------------------------------------------------------- |
|
66 /** @name Hidden constructors */ |
|
67 //@{ |
|
68 DOMNodeIterator() {} |
|
69 DOMNodeIterator(const DOMNodeIterator &) {} |
|
70 //@} |
|
71 |
|
72 private: |
|
73 // ----------------------------------------------------------------------- |
|
74 // Unimplemented constructors and operators |
|
75 // ----------------------------------------------------------------------- |
|
76 /** @name Unimplemented operators */ |
|
77 //@{ |
|
78 DOMNodeIterator & operator = (const DOMNodeIterator &); |
|
79 //@} |
|
80 |
|
81 public: |
|
82 // ----------------------------------------------------------------------- |
|
83 // All constructors are hidden, just the destructor is available |
|
84 // ----------------------------------------------------------------------- |
|
85 /** @name Destructor */ |
|
86 //@{ |
|
87 /** |
|
88 * Destructor |
|
89 * |
|
90 */ |
|
91 virtual ~DOMNodeIterator() {}; |
|
92 //@} |
|
93 |
|
94 // ----------------------------------------------------------------------- |
|
95 // Virtual DOMNodeFilter interface |
|
96 // ----------------------------------------------------------------------- |
|
97 /** @name Functions introduced in DOM Level 2 */ |
|
98 //@{ |
|
99 // ----------------------------------------------------------------------- |
|
100 // Getter methods |
|
101 // ----------------------------------------------------------------------- |
|
102 /** |
|
103 * The <code>root</code> node of the <code>DOMNodeIterator</code>, as specified |
|
104 * when it was created. |
|
105 * @since DOM Level 2 |
|
106 */ |
|
107 virtual DOMNode* getRoot() = 0; |
|
108 /** |
|
109 * Return which node types are presented via the iterator. |
|
110 * This attribute determines which node types are presented via the |
|
111 * <code>DOMNodeIterator</code>. The available set of constants is defined |
|
112 * in the <code>DOMNodeFilter</code> interface. Nodes not accepted by |
|
113 * <code>whatToShow</code> will be skipped, but their children may still |
|
114 * be considered. Note that this skip takes precedence over the filter, |
|
115 * if any. |
|
116 * @since DOM Level 2 |
|
117 * |
|
118 */ |
|
119 virtual unsigned long getWhatToShow() = 0; |
|
120 |
|
121 /** |
|
122 * The <code>DOMNodeFilter</code> used to screen nodes. |
|
123 * |
|
124 * @since DOM Level 2 |
|
125 */ |
|
126 virtual DOMNodeFilter* getFilter() = 0; |
|
127 |
|
128 /** |
|
129 * Return the expandEntityReferences flag. |
|
130 * The value of this flag determines whether the children of entity |
|
131 * reference nodes are visible to the <code>DOMNodeIterator</code>. If |
|
132 * false, these children and their descendants will be rejected. Note |
|
133 * that this rejection takes precedence over <code>whatToShow</code> and |
|
134 * the filter. Also note that this is currently the only situation where |
|
135 * <code>DOMNodeIterators</code> may reject a complete subtree rather than |
|
136 * skipping individual nodes. |
|
137 * <br> |
|
138 * <br> To produce a view of the document that has entity references |
|
139 * expanded and does not expose the entity reference node itself, use |
|
140 * the <code>whatToShow</code> flags to hide the entity reference node |
|
141 * and set <code>expandEntityReferences</code> to true when creating the |
|
142 * <code>DOMNodeIterator</code>. To produce a view of the document that has |
|
143 * entity reference nodes but no entity expansion, use the |
|
144 * <code>whatToShow</code> flags to show the entity reference node and |
|
145 * set <code>expandEntityReferences</code> to false. |
|
146 * |
|
147 * @since DOM Level 2 |
|
148 */ |
|
149 virtual bool getExpandEntityReferences() = 0; |
|
150 |
|
151 // ----------------------------------------------------------------------- |
|
152 // Query methods |
|
153 // ----------------------------------------------------------------------- |
|
154 /** |
|
155 * Returns the next node in the set and advances the position of the |
|
156 * <code>DOMNodeIterator</code> in the set. After a |
|
157 * <code>DOMNodeIterator</code> is created, the first call to |
|
158 * <code>nextNode()</code> returns the first node in the set. |
|
159 * @return The next <code>DOMNode</code> in the set being iterated over, or |
|
160 * <code>null</code> if there are no more members in that set. |
|
161 * @exception DOMException |
|
162 * INVALID_STATE_ERR: Raised if this method is called after the |
|
163 * <code>detach</code> method was invoked. |
|
164 * @since DOM Level 2 |
|
165 */ |
|
166 virtual DOMNode* nextNode() = 0; |
|
167 |
|
168 /** |
|
169 * Returns the previous node in the set and moves the position of the |
|
170 * <code>DOMNodeIterator</code> backwards in the set. |
|
171 * @return The previous <code>DOMNode</code> in the set being iterated over, |
|
172 * or <code>null</code> if there are no more members in that set. |
|
173 * @exception DOMException |
|
174 * INVALID_STATE_ERR: Raised if this method is called after the |
|
175 * <code>detach</code> method was invoked. |
|
176 * @since DOM Level 2 |
|
177 */ |
|
178 virtual DOMNode* previousNode() = 0; |
|
179 |
|
180 /** |
|
181 * Detaches the <code>DOMNodeIterator</code> from the set which it iterated |
|
182 * over, releasing any computational resources and placing the |
|
183 * <code>DOMNodeIterator</code> in the INVALID state. After |
|
184 * <code>detach</code> has been invoked, calls to <code>nextNode</code> |
|
185 * or <code>previousNode</code> will raise the exception |
|
186 * INVALID_STATE_ERR. |
|
187 * @since DOM Level 2 |
|
188 */ |
|
189 virtual void detach() = 0; |
|
190 //@} |
|
191 |
|
192 // ----------------------------------------------------------------------- |
|
193 // Non-standard Extension |
|
194 // ----------------------------------------------------------------------- |
|
195 /** @name Non-standard Extension */ |
|
196 //@{ |
|
197 /** |
|
198 * Called to indicate that this NodeIterator is no longer in use |
|
199 * and that the implementation may relinquish any resources associated with it. |
|
200 * (release() will call detach() where appropriate) |
|
201 * |
|
202 * Access to a released object will lead to unexpected result. |
|
203 */ |
|
204 virtual void release() = 0; |
|
205 //@} |
|
206 }; |
|
207 |
|
208 #define GetDOMNodeIteratorMemoryManager GET_DIRECT_MM(fDocument) |
|
209 |
|
210 XERCES_CPP_NAMESPACE_END |
|
211 |
|
212 #endif |