XPathEvaluator


1   /*
2    * Copyright (c) 2002 World Wide Web Consortium,
3    * (Massachusetts Institute of Technology, Institut National de
4    * Recherche en Informatique et en Automatique, Keio University). All
5    * Rights Reserved. This program is distributed under the W3C's Software
6    * Intellectual Property License. This program is distributed in the
7    * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
8    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
9    * PURPOSE.
10   * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
11   */
12  
13  package org.w3c.dom.xpath;
14  
15  
16  import org.w3c.dom.Node  ;
17  import org.w3c.dom.DOMException  ;
18  
19  /**
20   *  The evaluation of XPath expressions is provided by 
21   * <code>XPathEvaluator</code>. In a DOM implementation which supports the 
22   * XPath 3.0 feature, as described above, the <code>XPathEvaluator</code> 
23   * interface will be implemented on the same object which implements the 
24   * <code>Document</code> interface permitting it to be obtained by the usual 
25   * binding-specific method such as casting or by using the DOM Level 3 
26   * getInterface method. In this case the implementation obtained from the 
27   * Document supports the XPath DOM module and is compatible with the XPath 
28   * 1.0 specification. 
29   * <p>Evaluation of expressions with specialized extension functions or 
30   * variables may not work in all implementations and is, therefore, not 
31   * portable. <code>XPathEvaluator</code> implementations may be available 
32   * from other sources that could provide specific support for specialized 
33   * extension functions or variables as would be defined by other 
34   * specifications. 
35   * <p>See also the <a HREF='http://www.w3.org/2002/08/WD-DOM-Level-3-XPath-20020820'>Document Object Model (DOM) Level 3 XPath Specification</a>.
36   */
37  public interface XPathEvaluator {
38      /**
39       * Creates a parsed XPath expression with resolved namespaces. This is 
40       * useful when an expression will be reused in an application since it 
41       * makes it possible to compile the expression string into a more 
42       * efficient internal form and preresolve all namespace prefixes which 
43       * occur within the expression.
44       * @param expression The XPath expression string to be parsed.
45       * @param resolver The <code>resolver</code> permits translation of 
46       *   prefixes within the XPath expression into appropriate namespace URIs
47       *   . If this is specified as <code>null</code>, any namespace prefix 
48       *   within the expression will result in <code>DOMException</code> 
49       *   being thrown 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>i
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 
95       *   prefixes within the XPath expression into appropriate namespace URIs
96       *   . If this is specified as <code>null</code>, any namespace prefix 
97       *   within the expression will result in <code>DOMException</code> 
98       *   being thrown with the code <code>NAMESPACE_ERR</code>.
99       * @param type If a specific <code>type</code> is specified, then the 
100      *   result will be returned as the corresponding type.For XPath 1.0 
101      *   results, this must be one of the codes of the 
102      *   <code>XPathResult</code> interface.
103      * @param result The <code>result</code> specifies a specific result 
104      *   object which may be reused and returned by this method. If this is 
105      *   specified as <code>null</code>or the implementation does not reuse 
106      *   the specified result, a new result object will be constructed and 
107      *   returned.For XPath 1.0 results, this object will be of type 
108      *   <code>XPathResult</code>.
109      * @return The result of the evaluation of the XPath expression.For XPath 
110      *   1.0 results, this object will be of type <code>XPathResult</code>.
111      * @exception XPathException
112      *   INVALID_EXPRESSION_ERR: Raised if the expression is not legal 
113      *   according to the rules of the <code>XPathEvaluator</code>i
114      *   <br>TYPE_ERR: Raised if the result cannot be converted to return the 
115      *   specified type.
116      * @exception DOMException
117      *   NAMESPACE_ERR: Raised if the expression contains namespace prefixes 
118      *   which cannot be resolved by the specified 
119      *   <code>XPathNSResolver</code>.
120      *   <br>WRONG_DOCUMENT_ERR: The Node is from a document that is not 
121      *   supported by this <code>XPathEvaluator</code>.
122      *   <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath 
123      *   context node or the request type is not permitted by this 
124      *   <code>XPathEvaluator</code>.
125      */
126     public Object   evaluate(String   expression, 
127                            Node   contextNode, 
128                            XPathNSResolver resolver, 
129                            short type, 
130                            Object   result)
131                            throws XPathException, DOMException  ;
132 
133 }
134
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags