gomp-20050608-branch/libjava/classpath/external/w3c_dom/org/w3c/dom/xpath/XPathEvaluator.java

   1 /*
   2  * Copyright (c) 2004 World Wide Web Consortium,
   3  *
   4  * (Massachusetts Institute of Technology, European Research Consortium for
   5  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6  * work is distributed under the W3C(r) Software License [1] in the hope that
   7  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11  */
  12
  13 package org.w3c.dom.xpath;
  14
  15 import org.w3c.dom.Node;
  16 import org.w3c.dom.DOMException;
  17
  18 /**
  19  *  The evaluation of XPath expressions is provided by
  20  * <code>XPathEvaluator</code>. In a DOM implementation which supports the
  21  * XPath 3.0 feature, as described above, the <code>XPathEvaluator</code>
  22  * interface will be implemented on the same object which implements the
  23  * <code>Document</code> interface permitting it to be obtained by the usual
  24  * binding-specific method such as casting or by using the DOM Level 3
  25  * getInterface method. In this case the implementation obtained from the
  26  * Document supports the XPath DOM module and is compatible with the XPath
  27  * 1.0 specification.
  28  * <p>Evaluation of expressions with specialized extension functions or
  29  * variables may not work in all implementations and is, therefore, not
  30  * portable. <code>XPathEvaluator</code> implementations may be available
  31  * from other sources that could provide specific support for specialized
  32  * extension functions or variables as would be defined by other
  33  * specifications.
  34  * <p>See also the <a href='http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226'>Document Object Model (DOM) Level 3 XPath Specification</a>.
  35  */
  36 public interface XPathEvaluator {
  37     /**
  38      * Creates a parsed XPath expression with resolved namespaces. This is
  39      * useful when an expression will be reused in an application since it
  40      * makes it possible to compile the expression string into a more
  41      * efficient internal form and preresolve all namespace prefixes which
  42      * occur within the expression.
  43      * @param expression The XPath expression string to be parsed.
  44      * @param resolver The <code>resolver</code> permits translation of all
  45      *   prefixes, including the <code>xml</code> namespace prefix, within
  46      *   the XPath expression into appropriate namespace URIs. If this is
  47      *   specified as <code>null</code>, any namespace prefix within the
  48      *   expression will result in <code>DOMException</code> being thrown
  49      *   with the code <code>NAMESPACE_ERR</code>.
  50      * @return The compiled form of the XPath expression.
  51      * @exception XPathException
  52      *   INVALID_EXPRESSION_ERR: Raised if the expression is not legal
  53      *   according to the rules of the <code>XPathEvaluator</code>.
  54      * @exception DOMException
  55      *   NAMESPACE_ERR: Raised if the expression contains namespace prefixes
  56      *   which cannot be resolved by the specified
  57      *   <code>XPathNSResolver</code>.
  58      */
  59     public XPathExpression createExpression(String expression,
  60                                             XPathNSResolver resolver)
  61                                             throws XPathException, DOMException;
  62
  63     /**
  64      * Adapts any DOM node to resolve namespaces so that an XPath expression
  65      * can be easily evaluated relative to the context of the node where it
  66      * appeared within the document. This adapter works like the DOM Level 3
  67      * method <code>lookupNamespaceURI</code> on nodes in resolving the
  68      * namespaceURI from a given prefix using the current information
  69      * available in the node's hierarchy at the time lookupNamespaceURI is
  70      * called. also correctly resolving the implicit xml prefix.
  71      * @param nodeResolver The node to be used as a context for namespace
  72      *   resolution.
  73      * @return <code>XPathNSResolver</code> which resolves namespaces with
  74      *   respect to the definitions in scope for a specified node.
  75      */
  76     public XPathNSResolver createNSResolver(Node nodeResolver);
  77
  78     /**
  79      * Evaluates an XPath expression string and returns a result of the
  80      * specified type if possible.
  81      * @param expression The XPath expression string to be parsed and
  82      *   evaluated.
  83      * @param contextNode The <code>context</code> is context node for the
  84      *   evaluation of this XPath expression. If the XPathEvaluator was
  85      *   obtained by casting the <code>Document</code> then this must be
  86      *   owned by the same document and must be a <code>Document</code>,
  87      *   <code>Element</code>, <code>Attribute</code>, <code>Text</code>,
  88      *   <code>CDATASection</code>, <code>Comment</code>,
  89      *   <code>ProcessingInstruction</code>, or <code>XPathNamespace</code>
  90      *   node. If the context node is a <code>Text</code> or a
  91      *   <code>CDATASection</code>, then the context is interpreted as the
  92      *   whole logical text node as seen by XPath, unless the node is empty
  93      *   in which case it may not serve as the XPath context.
  94      * @param resolver The <code>resolver</code> permits translation of all
  95      *   prefixes, including the <code>xml</code> namespace prefix, within
  96      *   the XPath expression into appropriate namespace URIs. If this is
  97      *   specified as <code>null</code>, any namespace prefix within the
  98      *   expression will result in <code>DOMException</code> being thrown
  99      *   with the code <code>NAMESPACE_ERR</code>.
 100      * @param type If a specific <code>type</code> is specified, then the
 101      *   result will be returned as the corresponding type.For XPath 1.0
 102      *   results, this must be one of the codes of the
 103      *   <code>XPathResult</code> interface.
 104      * @param result The <code>result</code> specifies a specific result
 105      *   object which may be reused and returned by this method. If this is
 106      *   specified as <code>null</code>or the implementation does not reuse
 107      *   the specified result, a new result object will be constructed and
 108      *   returned.For XPath 1.0 results, this object will be of type
 109      *   <code>XPathResult</code>.
 110      * @return The result of the evaluation of the XPath expression.For XPath
 111      *   1.0 results, this object will be of type <code>XPathResult</code>.
 112      * @exception XPathException
 113      *   INVALID_EXPRESSION_ERR: Raised if the expression is not legal
 114      *   according to the rules of the <code>XPathEvaluator</code>i
 115      *   <br>TYPE_ERR: Raised if the result cannot be converted to return the
 116      *   specified type.
 117      * @exception DOMException
 118      *   NAMESPACE_ERR: Raised if the expression contains namespace prefixes
 119      *   which cannot be resolved by the specified
 120      *   <code>XPathNSResolver</code>.
 121      *   <br>WRONG_DOCUMENT_ERR: The Node is from a document that is not
 122      *   supported by this <code>XPathEvaluator</code>.
 123      *   <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath
 124      *   context node or the request type is not permitted by this
 125      *   <code>XPathEvaluator</code>.
 126      */
 127     public Object evaluate(String expression,
 128                            Node contextNode,
 129                            XPathNSResolver resolver,
 130                            short type,
 131                            Object result)
 132                            throws XPathException, DOMException;
 133
 134 }