xercesc/dom/DOMXPathEvaluator.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_DOMXPATHEVALUATOR_HPP)
0023 #define XERCESC_INCLUDE_GUARD_DOMXPATHEVALUATOR_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026 #include <xercesc/dom/DOMXPathResult.hpp>
0027
0028 XERCES_CPP_NAMESPACE_BEGIN
0029
0030 class DOMXPathNSResolver;
0031 class DOMXPathExpression;
0032 class DOMNode;
0033
0034 /**
0035  * The evaluation of XPath expressions is provided by <code>DOMXPathEvaluator</code>.
0036  * In a DOM implementation which supports the XPath feature, the <code>DOMXPathEvaluator</code>
0037  * interface will be implemented on the same object which implements the Document interface permitting
0038  * it to be obtained by casting or by using the DOM Level 3 getFeature method. In this case the
0039  * implementation obtained from the Document supports the XPath DOM module and is compatible
0040  * with the XPath 1.0 specification.
0041  * Evaluation of expressions with specialized extension functions or variables may not
0042  * work in all implementations and is, therefore, not portable. XPathEvaluator implementations
0043  * may be available from other sources that could provide specific support for specialized extension
0044  * functions or variables as would be defined by other specifications.
0045  * @since DOM Level 3
0046  */
0047 class CDOM_EXPORT DOMXPathEvaluator
0048 {
0049
0050 protected:
0051     // -----------------------------------------------------------------------
0052     //  Hidden constructors
0053     // -----------------------------------------------------------------------
0054     /** @name Hidden constructors */
0055     //@{
0056     DOMXPathEvaluator() {};
0057     //@}
0058
0059 private:
0060     // -----------------------------------------------------------------------
0061     // Unimplemented constructors and operators
0062     // -----------------------------------------------------------------------
0063     /** @name Unimplemented constructors and operators */
0064     //@{
0065     DOMXPathEvaluator(const DOMXPathEvaluator &);
0066     DOMXPathEvaluator& operator = (const  DOMXPathEvaluator&);
0067     //@}
0068
0069 public:
0070     // -----------------------------------------------------------------------
0071     //  All constructors are hidden, just the destructor is available
0072     // -----------------------------------------------------------------------
0073     /** @name Destructor */
0074     //@{
0075     /**
0076      * Destructor
0077      *
0078      */
0079     virtual ~DOMXPathEvaluator() {};
0080     //@}
0081
0082     // -----------------------------------------------------------------------
0083     // Virtual DOMXPathEvaluator interface
0084     // -----------------------------------------------------------------------
0085     /** @name Functions introduced in DOM Level 3 */
0086     //@{
0087
0088     /**
0089      * Creates a parsed XPath expression with resolved namespaces. This is useful
0090      * when an expression will be reused in an application since it makes it
0091      * possible to compile the expression string into a more efficient internal
0092      * form and preresolve all namespace prefixes which occur within the expression.
0093      * @param expression of type XMLCh - The XPath expression string to be parsed.
0094      * @param resolver of type <code>XPathNSResolver</code> - The resolver permits
0095      * translation of all prefixes, including the xml namespace prefix, within the XPath expression
0096      * into appropriate namespace URIs. If this is specified as null, any namespace
0097      * prefix within the expression will result in <code>DOMException</code> being thrown with the
0098      * code NAMESPACE_ERR.
0099      * @return <code>DOMXPathExpression</code> The compiled form of the XPath expression.
0100      * @exception <code>DOMXPathException</code>
0101      * INVALID_EXPRESSION_ERR: Raised if the expression is not legal according to the
0102      * rules of the <code>DOMXPathEvaluator</code>.
0103      * @exception DOMException
0104      * NAMESPACE_ERR: Raised if the expression contains namespace prefixes which cannot
0105      * be resolved by the specified <code>XPathNSResolver</code>.
0106      * @since DOM Level 3
0107      */
0108     virtual DOMXPathExpression* createExpression(const XMLCh *expression,
0109                                                  const DOMXPathNSResolver *resolver) = 0;
0110
0111
0112     /** Adapts any DOM node to resolve namespaces so that an XPath expression can be
0113      * easily evaluated relative to the context of the node where it appeared within
0114      * the document. This adapter works like the DOM Level 3 method lookupNamespaceURI
0115      * on nodes in resolving the namespaceURI from a given prefix using the current
0116      * information available in the node's hierarchy at the time lookupNamespaceURI
0117      * is called. also correctly resolving the implicit xml prefix.
0118      * @param nodeResolver of type <code>DOMNode</code> The node to be used as a context
0119      * for namespace resolution. If this parameter is null, an unpopulated
0120      * <code>DOMXPathNSResolver</code> is returned, which can be populated using the
0121      * Xerces-C extension <code>DOMXPathNSResolver::addNamespaceBinding()</code>.
0122      * @return <code>DOMXPathNSResolver</code> The object which resolves namespaces
0123      * with respect to the definitions in scope for the specified node.
0124      */
0125     virtual DOMXPathNSResolver* createNSResolver(const DOMNode *nodeResolver) = 0;
0126
0127
0128     /**
0129      * Evaluates an XPath expression string and returns a result of the specified
0130      * type if possible.
0131      * @param expression of type XMLCh The XPath expression string to be parsed
0132      * and evaluated.
0133      * @param contextNode of type <code>DOMNode</code> The context is context node
0134      * for the evaluation
0135      * of this XPath expression. If the <code>DOMXPathEvaluator</code> was obtained by
0136      * casting the <code>DOMDocument</code> then this must be owned by the same
0137      * document and must be a <code>DOMDocument</code>, <code>DOMElement</code>,
0138      * <code>DOMAttribute</code>, <code>DOMText</code>, <code>DOMCDATASection</code>,
0139      * <code>DOMComment</code>, <code>DOMProcessingInstruction</code>, or
0140      * <code>XPathNamespace</code> node. If the context node is a <code>DOMText</code> or
0141      * a <code>DOMCDATASection</code>, then the context is interpreted as the whole
0142      * logical text node as seen by XPath, unless the node is empty in which case it
0143      * may not serve as the XPath context.
0144      * @param resolver of type <code>XPathNSResolver</code> The resolver permits
0145      * translation of all prefixes, including the xml namespace prefix, within
0146      * the XPath expression into appropriate namespace URIs. If this is specified
0147      * as null, any namespace prefix within the expression will result in
0148      * <code>DOMException</code> being thrown with the code NAMESPACE_ERR.
0149      * @param type - If a specific type is specified, then
0150      * the result will be returned as the corresponding type. This must be one
0151      * of the codes of the <code>DOMXPathResult</code> interface.
0152      * @param result of type DOMXPathResult* - The result specifies a specific result object
0153      * which may be reused and returned by this method. If this is specified as
0154      * null or the implementation does not reuse the specified result, a new result
0155      * object will be constructed and returned.
0156      * @return DOMXPathResult* The result of the evaluation of the XPath expression.
0157      * @exception <code>DOMXPathException</code>
0158      * INVALID_EXPRESSION_ERR: Raised if the expression is not legal
0159      * according to the rules of the <code>DOMXPathEvaluator</code>
0160      * TYPE_ERR: Raised if the result cannot be converted to return the specified type.
0161      * @exception <code>DOMException</code>
0162      * NAMESPACE_ERR: Raised if the expression contains namespace prefixes
0163      * which cannot be resolved by the specified <code>XPathNSResolver</code>.
0164      * WRONG_DOCUMENT_ERR: The DOMNode is from a document that is not supported
0165      * by this <code>DOMXPathEvaluator</code>.
0166      * NOT_SUPPORTED_ERR: The DOMNode is not a type permitted as an XPath context
0167      * node or the request type is not permitted by this <code>DOMXPathEvaluator</code>.
0168      */
0169     virtual DOMXPathResult* evaluate(const XMLCh *expression,
0170                                      const DOMNode *contextNode,
0171                                      const DOMXPathNSResolver *resolver,
0172                                      DOMXPathResult::ResultType type,
0173                                      DOMXPathResult* result) = 0;
0174
0175     //@}
0176 };
0177
0178 XERCES_CPP_NAMESPACE_END
0179
0180 #endif