source: icXML/icXML-devel/src/xercesc/dom/DOMNodeIterator.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

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