352 lines
15 KiB
C++
352 lines
15 KiB
C++
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership.
|
|
* The ASF licenses this file to You under the Apache License, Version 2.0
|
|
* (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
/*
|
|
* $Id: DOMXPathResult.hpp 698579 2008-09-24 14:13:08Z borisk $
|
|
*/
|
|
|
|
#if !defined(XERCESC_INCLUDE_GUARD_DOMXPATHRESULT_HPP)
|
|
#define XERCESC_INCLUDE_GUARD_DOMXPATHRESULT_HPP
|
|
|
|
#include <xercesc/util/XercesDefs.hpp>
|
|
|
|
XERCES_CPP_NAMESPACE_BEGIN
|
|
|
|
class DOMXPathNSResolver;
|
|
class DOMXPathExpression;
|
|
class DOMTypeInfo;
|
|
class DOMNode;
|
|
|
|
/**
|
|
* The <code>DOMXPathResult</code> interface represents the result of the
|
|
* evaluation of an XPath 1.0 or XPath 2.0 expression within the context
|
|
* of a particular node. Since evaluation of an XPath expression can result
|
|
* in various result types, this object makes it possible to discover and
|
|
* manipulate the type and value of the result.
|
|
*
|
|
* Note that some function signatures were changed compared to the
|
|
* DOM Level 3 in order to accommodate XPath 2.0.
|
|
*
|
|
* @since DOM Level 3
|
|
*/
|
|
class CDOM_EXPORT DOMXPathResult
|
|
{
|
|
|
|
protected:
|
|
// -----------------------------------------------------------------------
|
|
// Hidden constructors
|
|
// -----------------------------------------------------------------------
|
|
/** @name Hidden constructors */
|
|
//@{
|
|
DOMXPathResult() {};
|
|
//@}
|
|
|
|
private:
|
|
// -----------------------------------------------------------------------
|
|
// Unimplemented constructors and operators
|
|
// -----------------------------------------------------------------------
|
|
/** @name Unimplemented constructors and operators */
|
|
//@{
|
|
DOMXPathResult(const DOMXPathResult &);
|
|
DOMXPathResult& operator = (const DOMXPathResult&);
|
|
//@}
|
|
|
|
public:
|
|
// -----------------------------------------------------------------------
|
|
// All constructors are hidden, just the destructor is available
|
|
// -----------------------------------------------------------------------
|
|
/** @name Destructor */
|
|
//@{
|
|
/**
|
|
* Destructor
|
|
*
|
|
*/
|
|
virtual ~DOMXPathResult() {};
|
|
//@}
|
|
|
|
// -----------------------------------------------------------------------
|
|
// Class Types
|
|
// -----------------------------------------------------------------------
|
|
/** @name Public Contants */
|
|
//@{
|
|
/**
|
|
* <p>ANY_TYPE
|
|
* <br>[XPath 1.0] This code does not represent a specific type. An evaluation of an XPath
|
|
* expression will never produce this type. If this type is requested, then
|
|
* the evaluation returns whatever type naturally results from evaluation
|
|
* of the expression.
|
|
* If the natural result is a node set when ANY_TYPE was requested, then
|
|
* UNORDERED_NODE_ITERATOR_TYPE is always the resulting type. Any other
|
|
* representation of a node set must be explicitly requested.
|
|
* <p>ANY_UNORDERED_NODE_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 and will be accessed
|
|
* as a single node, which may be null if the node set is empty. Document
|
|
* modification does not invalidate the node, but may mean that the result
|
|
* node no longer corresponds to the current document. This is a convenience
|
|
* that permits optimization since the implementation can stop once any node
|
|
* in the resulting set has been found.
|
|
* If there is more than one node in the actual result, the single node
|
|
* returned might not be the first in document order.
|
|
* <p>BOOLEAN_TYPE
|
|
* <br>[XPath 1.0] The result is a boolean as defined by XPath 1.0. Document modification
|
|
* does not invalidate the boolean, but may mean that reevaluation would not
|
|
* yield the same boolean.
|
|
* <p>FIRST_ORDERED_NODE_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 and will be accessed
|
|
* as a single node, which may be null if the node set is empty. Document
|
|
* modification does not invalidate the node, but may mean that the result
|
|
* node no longer corresponds to the current document. This is a convenience
|
|
* that permits optimization since the implementation can stop once the first
|
|
* node in document order of the resulting set has been found.
|
|
* If there are more than one node in the actual result, the single node
|
|
* returned will be the first in document order.
|
|
* <p>NUMBER_TYPE
|
|
* <br>[XPath 1.0] The result is a number as defined by XPath 1.0. Document modification does
|
|
* not invalidate the number, but may mean that reevaluation would not yield the
|
|
* same number.
|
|
* <p>ORDERED_NODE_ITERATOR_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed
|
|
* iteratively, which will produce document-ordered nodes. Document modification
|
|
* invalidates the iteration.
|
|
* <p>ORDERED_NODE_SNAPSHOT_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed as a
|
|
* snapshot list of nodes that will be in original document order. Document
|
|
* modification does not invalidate the snapshot but may mean that reevaluation would
|
|
* not yield the same snapshot and nodes in the snapshot may have been altered, moved,
|
|
* or removed from the document.
|
|
* <p>STRING_TYPE
|
|
* <br>[XPath 1.0] The result is a string as defined by XPath 1.0. Document modification does not
|
|
* invalidate the string, but may mean that the string no longer corresponds to the
|
|
* current document.
|
|
* <p>UNORDERED_NODE_ITERATOR_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed iteratively,
|
|
* which may not produce nodes in a particular order. Document modification invalidates the iteration.
|
|
* This is the default type returned if the result is a node set and ANY_TYPE is requested.
|
|
* <p>UNORDERED_NODE_SNAPSHOT_TYPE
|
|
* <br>[XPath 1.0] The result is a node set as defined by XPath 1.0 that will be accessed as a
|
|
* snapshot list of nodes that may not be in a particular order. Document modification
|
|
* does not invalidate the snapshot but may mean that reevaluation would not yield the same
|
|
* snapshot and nodes in the snapshot may have been altered, moved, or removed from the document.
|
|
* <p>FIRST_RESULT_TYPE
|
|
* <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 and will be accessed
|
|
* as a single current value or there will be no current value if the sequence
|
|
* is empty. Document modification does not invalidate the value, but may mean
|
|
* that the result no longer corresponds to the current document. This is a
|
|
* convenience that permits optimization since the implementation can stop once
|
|
* the first item in the resulting sequence has been found. If there is more
|
|
* than one item in the actual result, the single item returned might not be
|
|
* the first in document order.
|
|
* <p>ITERATOR_RESULT_TYPE
|
|
* <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 that will be accessed
|
|
* iteratively. Document modification invalidates the iteration.
|
|
* <p>SNAPSHOT_RESULT_TYPE
|
|
* <br>[XPath 2.0] The result is a sequence as defined by XPath 2.0 that will be accessed
|
|
* as a snapshot list of values. Document modification does not invalidate the
|
|
* snapshot but may mean that reevaluation would not yield the same snapshot
|
|
* and any items in the snapshot may have been altered, moved, or removed from
|
|
* the document.
|
|
*/
|
|
enum ResultType {
|
|
/* XPath 1.0 */
|
|
ANY_TYPE = 0,
|
|
NUMBER_TYPE = 1,
|
|
STRING_TYPE = 2,
|
|
BOOLEAN_TYPE = 3,
|
|
UNORDERED_NODE_ITERATOR_TYPE = 4,
|
|
ORDERED_NODE_ITERATOR_TYPE = 5,
|
|
UNORDERED_NODE_SNAPSHOT_TYPE = 6,
|
|
ORDERED_NODE_SNAPSHOT_TYPE = 7,
|
|
ANY_UNORDERED_NODE_TYPE = 8,
|
|
FIRST_ORDERED_NODE_TYPE = 9,
|
|
/* XPath 2.0 */
|
|
FIRST_RESULT_TYPE = 100,
|
|
ITERATOR_RESULT_TYPE = 101,
|
|
SNAPSHOT_RESULT_TYPE = 102
|
|
};
|
|
//@}
|
|
|
|
|
|
// -----------------------------------------------------------------------
|
|
// Virtual DOMXPathResult interface
|
|
// -----------------------------------------------------------------------
|
|
/** @name Functions introduced in DOM Level 3 */
|
|
//@{
|
|
|
|
/**
|
|
* Returns the result type of this result
|
|
* @return ResultType
|
|
* A code representing the type of this result, as defined by the type constants.
|
|
*/
|
|
virtual ResultType getResultType() const = 0;
|
|
|
|
/**
|
|
* Returns the DOM type info of the current result node or value
|
|
* (XPath 2 only).
|
|
* @return typeInfo of type TypeInfo, readonly
|
|
*/
|
|
virtual const DOMTypeInfo *getTypeInfo() const = 0;
|
|
|
|
/**
|
|
* Returns true if the result has a current result and the value is a
|
|
* node (XPath 2 only). This function is necessary to distinguish
|
|
* between a string value and a node of type string as returned by
|
|
* the getTypeInfo() function.
|
|
* @return isNode of type boolean, readonly
|
|
*/
|
|
virtual bool isNode() const = 0;
|
|
|
|
/**
|
|
* Returns the boolean value of this result
|
|
* @return booleanValue of type boolean
|
|
* The value of this boolean result.
|
|
* @exception DOMXPathException
|
|
* TYPE_ERR: raised if ResultType is not BOOLEAN_TYPE (XPath 1.0) or
|
|
* if current result cannot be properly converted to boolean (XPath 2.0).
|
|
* <br>
|
|
* NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
|
|
*/
|
|
virtual bool getBooleanValue() const = 0;
|
|
|
|
/**
|
|
* Returns the integer value of this result (XPath 2 only).
|
|
* @return integerValue of type int
|
|
* The value of this integer result.
|
|
* @exception DOMXPathException
|
|
* TYPE_ERR: raised if current result cannot be properly converted to
|
|
* int (XPath 2.0).
|
|
* <br>
|
|
* NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
|
|
*/
|
|
virtual int getIntegerValue() const = 0;
|
|
|
|
/**
|
|
* Returns the number value of this result
|
|
* @return numberValue
|
|
* The value of this number result. If the native double type of the DOM
|
|
* binding does not directly support the exact IEEE 754 result of the XPath
|
|
* expression, then it is up to the definition of the binding to specify how
|
|
* the XPath number is converted to the native binding number.
|
|
* @exception DOMXPathException
|
|
* TYPE_ERR: raised if ResultType is not NUMBER_TYPE (XPath 1.0) or
|
|
* if current result cannot be properly converted to double (XPath 2.0).
|
|
* <br>
|
|
* NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
|
|
*/
|
|
virtual double getNumberValue() const = 0;
|
|
|
|
/**
|
|
* Returns the string value of this result
|
|
* @return stringValue
|
|
* The value of this string result.
|
|
* @exception DOMXPathException
|
|
* TYPE_ERR: raised if ResultType is not STRING_TYPE (XPath 1.0) or
|
|
* if current result cannot be properly converted to string (XPath 2.0).
|
|
* <br>
|
|
* NO_RESULT_ERROR: raised if there is no current result in the result object (XPath 2.0).
|
|
*/
|
|
virtual const XMLCh* getStringValue() const = 0;
|
|
|
|
/**
|
|
* Returns the node value of this result
|
|
* @return nodeValue
|
|
* The value of this node result, which may be null.
|
|
* @exception DOMXPathException
|
|
* TYPE_ERR: raised if ResultType is not ANY_UNORDERED_NODE_TYPE,
|
|
* FIRST_ORDERED_NODE_TYPE, UNORDERED_NODE_ITERATOR_TYPE,
|
|
* ORDERED_NODE_ITERATOR_TYPE, UNORDERED_NODE_SNAPSHOT_TYPE, or
|
|
* ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if current result is
|
|
* not a node (XPath 2.0).
|
|
* <br>
|
|
* NO_RESULT_ERROR: raised if there is no current result in the result
|
|
* object.
|
|
*/
|
|
virtual DOMNode* getNodeValue() const = 0;
|
|
|
|
/**
|
|
* Iterates and returns true if the current result is the next item from the
|
|
* sequence or false if there are no more items.
|
|
* @return boolean True if the current result is the next item from the sequence
|
|
* or false if there are no more items.
|
|
* @exception XPathException
|
|
* TYPE_ERR: raised if ResultType is not UNORDERED_NODE_ITERATOR_TYPE or
|
|
* ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or if ResultType is not
|
|
* ITERATOR_RESULT_TYPE (XPath 2.0).
|
|
* @exception DOMException
|
|
* INVALID_STATE_ERR: The document has been mutated since the result was returned.
|
|
*/
|
|
virtual bool iterateNext() = 0;
|
|
|
|
/**
|
|
* Signifies that the iterator has become invalid.
|
|
* @return invalidIteratorState
|
|
* True if ResultType is UNORDERED_NODE_ITERATOR_TYPE or
|
|
* ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or ITERATOR_RESULT_TYPE (XPath 2.0)
|
|
* and the document has been modified since this result was returned.
|
|
* @exception XPathException
|
|
* TYPE_ERR: raised if ResultType is not UNORDERED_NODE_ITERATOR_TYPE or
|
|
* ORDERED_NODE_ITERATOR_TYPE (XPath 1.0) or if ResultType is not
|
|
* ITERATOR_RESULT_TYPE (XPath 2.0).
|
|
*/
|
|
virtual bool getInvalidIteratorState() const = 0;
|
|
|
|
/**
|
|
* Sets the current result to the indexth item in the snapshot collection. If
|
|
* index is greater than or equal to the number of items in the list, this method
|
|
* returns false. Unlike the iterator result, the snapshot does not become
|
|
* invalid, but may not correspond to the current document if it is mutated.
|
|
* @param index of type XMLSize_t - Index into the snapshot collection.
|
|
* @return boolean True if the current result is the next item from the sequence
|
|
* or false if there are no more items.
|
|
* @exception XPathException
|
|
* TYPE_ERR: raised if ResultType is not UNORDERED_NODE_SNAPSHOT_TYPE or
|
|
* ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if ResultType is not
|
|
* SNAPSHOT_RESULT_TYPE (XPath 2.0).
|
|
*/
|
|
virtual bool snapshotItem(XMLSize_t index) = 0;
|
|
|
|
/**
|
|
* The number of items in the result snapshot. Valid values for snapshotItem
|
|
* indices are 0 to snapshotLength-1 inclusive.
|
|
* @return snapshotLength of type XMLSize_t
|
|
* @exception XPathException
|
|
* TYPE_ERR: raised if ResultType is not UNORDERED_NODE_SNAPSHOT_TYPE or
|
|
* ORDERED_NODE_SNAPSHOT_TYPE (XPath 1.0) or if ResultType is not
|
|
* SNAPSHOT_RESULT_TYPE (XPath 2.0).
|
|
*/
|
|
virtual XMLSize_t getSnapshotLength() const = 0;
|
|
|
|
//@}
|
|
|
|
// -----------------------------------------------------------------------
|
|
// Non-standard Extension
|
|
// -----------------------------------------------------------------------
|
|
/** @name Non-standard Extension */
|
|
//@{
|
|
/**
|
|
* Called to indicate that this DOMXPathResult is no longer in use
|
|
* and that the implementation may relinquish any resources associated with it.
|
|
*
|
|
* Access to a released object will lead to unexpected result.
|
|
*/
|
|
virtual void release() = 0;
|
|
//@}
|
|
};
|
|
|
|
XERCES_CPP_NAMESPACE_END
|
|
|
|
#endif
|