source: icXML/icXML-devel/src/xercesc/dom/DOMXPathResult.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: 15.3 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: DOMXPathResult.hpp 932887 2010-04-11 13:04:59Z borisk $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_DOMXPATHRESULT_HPP)
23#define XERCESC_INCLUDE_GUARD_DOMXPATHRESULT_HPP
24
25#include <xercesc/util/XercesDefs.hpp>
26
27XERCES_CPP_NAMESPACE_BEGIN
28
29class DOMXPathNSResolver;
30class DOMXPathExpression;
31class DOMTypeInfo;
32class DOMNode;
33
34/**
35 * The <code>DOMXPathResult</code> interface represents the result of the
36 * evaluation of an XPath 1.0 or XPath 2.0 expression within the context
37 * of a particular node. Since evaluation of an XPath expression can result
38 * in various result types, this object makes it possible to discover and
39 * manipulate the type and value of the result.
40 *
41 * Note that some function signatures were changed compared to the
42 * DOM Level 3 in order to accommodate XPath 2.0.
43 *
44 * @since DOM Level 3
45 */
46class CDOM_EXPORT DOMXPathResult
47{
48
49protected:
50    // -----------------------------------------------------------------------
51    //  Hidden constructors
52    // -----------------------------------------------------------------------
53    /** @name Hidden constructors */
54    //@{
55    DOMXPathResult() {};
56    //@}
57
58private:
59    // -----------------------------------------------------------------------
60    // Unimplemented constructors and operators
61    // -----------------------------------------------------------------------
62    /** @name Unimplemented constructors and operators */
63    //@{
64    DOMXPathResult(const DOMXPathResult &);
65    DOMXPathResult& operator = (const  DOMXPathResult&);
66    //@}
67
68public:
69    // -----------------------------------------------------------------------
70    //  All constructors are hidden, just the destructor is available
71    // -----------------------------------------------------------------------
72    /** @name Destructor */
73    //@{
74    /**
75     * Destructor
76     *
77     */
78    virtual ~DOMXPathResult() {};
79    //@}
80
81    // -----------------------------------------------------------------------
82    //  Class Types
83    // -----------------------------------------------------------------------
84    /** @name Public Constants */
85    //@{
86    /**
87     * <p>ANY_TYPE
88     * <br>[XPath 1.0] This code does not represent a specific type. An evaluation of an XPath
89     * expression will never produce this type. If this type is requested, then
90     * the evaluation returns whatever type naturally results from evaluation
91     * of the expression.
92     * If the natural result is a node set when ANY_TYPE was requested, then
93     * UNORDERED_NODE_ITERATOR_TYPE is always the resulting type. Any other
94     * representation of a node set must be explicitly requested.
95     * <p>ANY_UNORDERED_NODE_TYPE
96     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 and will be accessed
97     * as a single node, which may be null if the node set is empty. Document
98     * modification does not invalidate the node, but may mean that the result
99     * node no longer corresponds to the current document. This is a convenience
100     * that permits optimization since the implementation can stop once any node
101     * in the resulting set has been found.
102     * If there is more than one node in the actual result, the single node
103     * returned might not be the first in document order.
104     * <p>BOOLEAN_TYPE
105     * <br>[XPath 1.0] The result is a boolean as defined by XPath 1.0. Document modification
106     * does not invalidate the boolean, but may mean that reevaluation would not
107     * yield the same boolean.
108     * <p>FIRST_ORDERED_NODE_TYPE
109     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 and will be accessed
110     * as a single node, which may be null if the node set is empty. Document
111     * modification does not invalidate the node, but may mean that the result
112     * node no longer corresponds to the current document. This is a convenience
113     * that permits optimization since the implementation can stop once the first
114     * node in document order of the resulting set has been found.
115     * If there are more than one node in the actual result, the single node
116     * returned will be the first in document order.
117     * <p>NUMBER_TYPE
118     * <br>[XPath 1.0] The result is a number as defined by XPath 1.0. Document modification does
119     * not invalidate the number, but may mean that reevaluation would not yield the
120     * same number.
121     * <p>ORDERED_NODE_ITERATOR_TYPE
122     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed
123     * iteratively, which will produce document-ordered nodes. Document modification
124     * invalidates the iteration.
125     * <p>ORDERED_NODE_SNAPSHOT_TYPE
126     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed as a
127     * snapshot list of nodes that will be in original document order. Document
128     * modification does not invalidate the snapshot but may mean that reevaluation would
129     * not yield the same snapshot and nodes in the snapshot may have been altered, moved,
130     * or removed from the document.
131     * <p>STRING_TYPE
132     * <br>[XPath 1.0] The result is a string as defined by XPath 1.0. Document modification does not
133     * invalidate the string, but may mean that the string no longer corresponds to the
134     * current document.
135     * <p>UNORDERED_NODE_ITERATOR_TYPE
136     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed iteratively,
137     * which may not produce nodes in a particular order. Document modification invalidates the iteration.
138     * This is the default type returned if the result is a node set and ANY_TYPE is requested.
139     * <p>UNORDERED_NODE_SNAPSHOT_TYPE
140     * <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed as a
141     * snapshot list of nodes that may not be in a particular order. Document modification
142     * does not invalidate the snapshot but may mean that reevaluation would not yield the same
143     * snapshot and nodes in the snapshot may have been altered, moved, or removed from the document.
144     * <p>FIRST_RESULT_TYPE
145     * <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 and will be accessed
146     * as a single current value or there will be no current value if the sequence
147     * is empty. Document modification does not invalidate the value, but may mean
148     * that the result no longer corresponds to the current document. This is a
149     * convenience that permits optimization since the implementation can stop once
150     * the first item in the resulting sequence has been found. If there is more
151     * than one item in the actual result, the single item returned might not be
152     * the first in document order.
153     * <p>ITERATOR_RESULT_TYPE
154     * <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 that will be accessed
155     * iteratively. Document modification invalidates the iteration.
156     * <p>SNAPSHOT_RESULT_TYPE
157     * <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 that will be accessed
158     * as a snapshot list of values. Document modification does not invalidate the
159     * snapshot but may mean that reevaluation would not yield the same snapshot
160     * and any items in the snapshot may have been altered, moved, or removed from
161     * the document.
162     */
163    enum ResultType {
164                /* XPath 1.0 */
165                ANY_TYPE = 0,
166                NUMBER_TYPE = 1,
167                STRING_TYPE = 2,
168                BOOLEAN_TYPE = 3,
169                UNORDERED_NODE_ITERATOR_TYPE = 4,
170                ORDERED_NODE_ITERATOR_TYPE = 5,
171                UNORDERED_NODE_SNAPSHOT_TYPE = 6,
172                ORDERED_NODE_SNAPSHOT_TYPE = 7,
173                ANY_UNORDERED_NODE_TYPE = 8,
174                FIRST_ORDERED_NODE_TYPE = 9,
175                /* XPath 2.0 */
176                FIRST_RESULT_TYPE    = 100,
177                ITERATOR_RESULT_TYPE = 101,
178                SNAPSHOT_RESULT_TYPE = 102
179    };
180    //@}
181
182
183    // -----------------------------------------------------------------------
184    // Virtual DOMXPathResult interface
185    // -----------------------------------------------------------------------
186    /** @name Functions introduced in DOM Level 3 */
187    //@{
188
189    /**
190     * Returns the result type of this result
191     * @return ResultType
192     * A code representing the type of this result, as defined by the type constants.
193     */
194    virtual ResultType getResultType() const = 0;
195
196    /**
197     * Returns the DOM type info of the current result node or value
198     * (XPath 2 only).
199     * @return typeInfo of type TypeInfo, readonly
200     */
201    virtual const DOMTypeInfo *getTypeInfo() const = 0;
202
203    /**
204     * Returns true if the result has a current result and the value is a
205     * node (XPath 2 only). This function is necessary to distinguish
206     * between a string value and a node of type string as returned by
207     * the getTypeInfo() function.
208     * @return isNode of type boolean, readonly
209     */
210    virtual bool isNode() const = 0;
211
212    /**
213     * Returns the boolean value of this result
214     * @return booleanValue of type boolean
215     * The value of this boolean result.
216     * @exception DOMXPathException
217     * TYPE_ERR: raised if ResultType is not BOOLEAN_TYPE (XPath 1.0) or
218     * if current result cannot be properly converted to boolean (XPath 2.0).
219     * <br>
220     * NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
221     */
222    virtual bool getBooleanValue() const = 0;
223
224    /**
225     * Returns the integer value of this result (XPath 2 only).
226     * @return integerValue of type int
227     * The value of this integer result.
228     * @exception DOMXPathException
229     * TYPE_ERR: raised if current result cannot be properly converted to
230     * int (XPath 2.0).
231     * <br>
232     * NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
233     */
234    virtual int getIntegerValue() const = 0;
235
236    /**
237     * Returns the number value of this result
238     * @return numberValue
239     * The value of this number result. If the native double type of the DOM
240     * binding does not directly support the exact IEEE 754 result of the XPath
241     * expression, then it is up to the definition of the binding to specify how
242     * the XPath number is converted to the native binding number.
243     * @exception DOMXPathException
244     * TYPE_ERR: raised if ResultType is not NUMBER_TYPE (XPath 1.0) or
245     * if current result cannot be properly converted to double (XPath 2.0).
246     * <br>
247     * NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
248     */
249    virtual double getNumberValue() const = 0;
250
251   /**
252     * Returns the string value of this result
253     * @return stringValue
254     * The value of this string result.
255     * @exception DOMXPathException
256     * TYPE_ERR: raised if ResultType is not STRING_TYPE (XPath 1.0) or
257     * if current result cannot be properly converted to string (XPath 2.0).
258     * <br>
259     * NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
260     */
261    virtual const XMLCh* getStringValue() const = 0;
262
263    /**
264     * Returns the node value of this result
265     * @return nodeValue
266     * The value of this node result, which may be null.
267     * @exception DOMXPathException
268     * TYPE_ERR: raised if ResultType is not ANY_UNORDERED_NODE_TYPE,
269     * FIRST_ORDERED_NODE_TYPE, UNORDERED_NODE_ITERATOR_TYPE,
270     * ORDERED_NODE_ITERATOR_TYPE, UNORDERED_NODE_SNAPSHOT_TYPE, or
271     * ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if current result is
272     * not a node (XPath 2.0).
273     * <br>
274     * NO_RESULT_ERROR: raised if there is no current result in the result
275     * object.
276     */
277    virtual DOMNode* getNodeValue() const = 0;
278
279    /**
280     * Iterates and returns true if the current result is the next item from the
281     * sequence or false if there are no more items.
282     * @return boolean True if the current result is the next item from the sequence
283     * or false if there are no more items.
284     * @exception XPathException
285     * TYPE_ERR: raised if ResultType is not UNORDERED_NODE_ITERATOR_TYPE or
286     * ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or if ResultType is not
287     * ITERATOR_RESULT_TYPE (XPath 2.0).
288     * @exception DOMException
289     * INVALID_STATE_ERR: The document has been mutated since the result was returned.
290     */
291    virtual bool iterateNext() = 0;
292
293    /**
294     * Signifies that the iterator has become invalid.
295     * @return invalidIteratorState
296     * True if ResultType is UNORDERED_NODE_ITERATOR_TYPE or
297     * ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or ITERATOR_RESULT_TYPE (XPath 2.0)
298     * and the document has been modified since this result was returned.
299     * @exception XPathException
300     * TYPE_ERR: raised if ResultType is not UNORDERED_NODE_ITERATOR_TYPE or
301     * ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or if ResultType is not
302     * ITERATOR_RESULT_TYPE (XPath 2.0).
303     */
304    virtual bool getInvalidIteratorState() const = 0;
305
306    /**
307     * Sets the current result to the indexth item in the snapshot collection. If
308     * index is greater than or equal to the number of items in the list, this method
309     * returns false. Unlike the iterator result, the snapshot does not become
310     * invalid, but may not correspond to the current document if it is mutated.
311     * @param index of type XMLSize_t - Index into the snapshot collection.
312     * @return boolean True if the current result is the next item from the sequence
313     * or false if there are no more items.
314     * @exception XPathException
315     * TYPE_ERR: raised if ResultType is not UNORDERED_NODE_SNAPSHOT_TYPE or
316     * ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if ResultType is not
317     * SNAPSHOT_RESULT_TYPE (XPath 2.0).
318     */
319    virtual bool snapshotItem(XMLSize_t index) = 0;
320
321    /**
322     * The number of items in the result snapshot. Valid values for snapshotItem
323     * indices are 0 to snapshotLength-1 inclusive.
324     * @return snapshotLength of type XMLSize_t
325     * @exception XPathException
326     * TYPE_ERR: raised if ResultType is not UNORDERED_NODE_SNAPSHOT_TYPE or
327     * ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if ResultType is not
328     * SNAPSHOT_RESULT_TYPE (XPath 2.0).
329     */
330    virtual XMLSize_t getSnapshotLength() const = 0;
331
332    //@}
333
334    // -----------------------------------------------------------------------
335    //  Non-standard Extension
336    // -----------------------------------------------------------------------
337    /** @name Non-standard Extension */
338    //@{
339    /**
340     * Called to indicate that this DOMXPathResult is no longer in use
341     * and that the implementation may relinquish any resources associated with it.
342     *
343     * Access to a released object will lead to unexpected result.
344     */
345    virtual void release() = 0;
346    //@}
347};
348
349XERCES_CPP_NAMESPACE_END
350
351#endif
Note: See TracBrowser for help on using the repository browser.