|
1 /* |
|
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
3 * |
|
4 * This code is free software; you can redistribute it and/or modify it |
|
5 * under the terms of the GNU General Public License version 2 only, as |
|
6 * published by the Free Software Foundation. Oracle designates this |
|
7 * particular file as subject to the "Classpath" exception as provided |
|
8 * by Oracle in the LICENSE file that accompanied this code. |
|
9 * |
|
10 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
13 * version 2 for more details (a copy is included in the LICENSE file that |
|
14 * accompanied this code). |
|
15 * |
|
16 * You should have received a copy of the GNU General Public License version |
|
17 * 2 along with this work; if not, write to the Free Software Foundation, |
|
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
19 * |
|
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
21 * or visit www.oracle.com if you need additional information or have any |
|
22 * questions. |
|
23 */ |
|
24 |
|
25 /* |
|
26 * This file is available under and governed by the GNU General Public |
|
27 * License version 2 only, as published by the Free Software Foundation. |
|
28 * However, the following notice accompanied the original version of this |
|
29 * file and, per its terms, should not be removed: |
|
30 * |
|
31 * Copyright (c) 2002 World Wide Web Consortium, |
|
32 * (Massachusetts Institute of Technology, Institut National de |
|
33 * Recherche en Informatique et en Automatique, Keio University). All |
|
34 * Rights Reserved. This program is distributed under the W3C's Software |
|
35 * Intellectual Property License. This program is distributed in the |
|
36 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even |
|
37 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
|
38 * PURPOSE. |
|
39 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. |
|
40 */ |
|
41 |
|
42 package org.w3c.dom.xpath; |
|
43 |
|
44 |
|
45 import org.w3c.dom.Node; |
|
46 import org.w3c.dom.DOMException; |
|
47 |
|
48 /** |
|
49 * The evaluation of XPath expressions is provided by |
|
50 * <code>XPathEvaluator</code>. In a DOM implementation which supports the |
|
51 * XPath 3.0 feature, as described above, the <code>XPathEvaluator</code> |
|
52 * interface will be implemented on the same object which implements the |
|
53 * <code>Document</code> interface permitting it to be obtained by the usual |
|
54 * binding-specific method such as casting or by using the DOM Level 3 |
|
55 * getInterface method. In this case the implementation obtained from the |
|
56 * Document supports the XPath DOM module and is compatible with the XPath |
|
57 * 1.0 specification. |
|
58 * <p>Evaluation of expressions with specialized extension functions or |
|
59 * variables may not work in all implementations and is, therefore, not |
|
60 * portable. <code>XPathEvaluator</code> implementations may be available |
|
61 * from other sources that could provide specific support for specialized |
|
62 * extension functions or variables as would be defined by other |
|
63 * specifications. |
|
64 * <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>. |
|
65 */ |
|
66 public interface XPathEvaluator { |
|
67 /** |
|
68 * Creates a parsed XPath expression with resolved namespaces. This is |
|
69 * useful when an expression will be reused in an application since it |
|
70 * makes it possible to compile the expression string into a more |
|
71 * efficient internal form and preresolve all namespace prefixes which |
|
72 * occur within the expression. |
|
73 * @param expression The XPath expression string to be parsed. |
|
74 * @param resolver The <code>resolver</code> permits translation of |
|
75 * prefixes within the XPath expression into appropriate namespace URIs |
|
76 * . If this is specified as <code>null</code>, any namespace prefix |
|
77 * within the expression will result in <code>DOMException</code> |
|
78 * being thrown with the code <code>NAMESPACE_ERR</code>. |
|
79 * @return The compiled form of the XPath expression. |
|
80 * @exception XPathException |
|
81 * INVALID_EXPRESSION_ERR: Raised if the expression is not legal |
|
82 * according to the rules of the <code>XPathEvaluator</code>i |
|
83 * @exception DOMException |
|
84 * NAMESPACE_ERR: Raised if the expression contains namespace prefixes |
|
85 * which cannot be resolved by the specified |
|
86 * <code>XPathNSResolver</code>. |
|
87 */ |
|
88 public XPathExpression createExpression(String expression, |
|
89 XPathNSResolver resolver) |
|
90 throws XPathException, DOMException; |
|
91 |
|
92 /** |
|
93 * Adapts any DOM node to resolve namespaces so that an XPath expression |
|
94 * can be easily evaluated relative to the context of the node where it |
|
95 * appeared within the document. This adapter works like the DOM Level 3 |
|
96 * method <code>lookupNamespaceURI</code> on nodes in resolving the |
|
97 * namespaceURI from a given prefix using the current information |
|
98 * available in the node's hierarchy at the time lookupNamespaceURI is |
|
99 * called. also correctly resolving the implicit xml prefix. |
|
100 * @param nodeResolver The node to be used as a context for namespace |
|
101 * resolution. |
|
102 * @return <code>XPathNSResolver</code> which resolves namespaces with |
|
103 * respect to the definitions in scope for a specified node. |
|
104 */ |
|
105 public XPathNSResolver createNSResolver(Node nodeResolver); |
|
106 |
|
107 /** |
|
108 * Evaluates an XPath expression string and returns a result of the |
|
109 * specified type if possible. |
|
110 * @param expression The XPath expression string to be parsed and |
|
111 * evaluated. |
|
112 * @param contextNode The <code>context</code> is context node for the |
|
113 * evaluation of this XPath expression. If the XPathEvaluator was |
|
114 * obtained by casting the <code>Document</code> then this must be |
|
115 * owned by the same document and must be a <code>Document</code>, |
|
116 * <code>Element</code>, <code>Attribute</code>, <code>Text</code>, |
|
117 * <code>CDATASection</code>, <code>Comment</code>, |
|
118 * <code>ProcessingInstruction</code>, or <code>XPathNamespace</code> |
|
119 * node. If the context node is a <code>Text</code> or a |
|
120 * <code>CDATASection</code>, then the context is interpreted as the |
|
121 * whole logical text node as seen by XPath, unless the node is empty |
|
122 * in which case it may not serve as the XPath context. |
|
123 * @param resolver The <code>resolver</code> permits translation of |
|
124 * prefixes within the XPath expression into appropriate namespace URIs |
|
125 * . If this is specified as <code>null</code>, any namespace prefix |
|
126 * within the expression will result in <code>DOMException</code> |
|
127 * being thrown with the code <code>NAMESPACE_ERR</code>. |
|
128 * @param type If a specific <code>type</code> is specified, then the |
|
129 * result will be returned as the corresponding type.For XPath 1.0 |
|
130 * results, this must be one of the codes of the |
|
131 * <code>XPathResult</code> interface. |
|
132 * @param result The <code>result</code> specifies a specific result |
|
133 * object which may be reused and returned by this method. If this is |
|
134 * specified as <code>null</code>or the implementation does not reuse |
|
135 * the specified result, a new result object will be constructed and |
|
136 * returned.For XPath 1.0 results, this object will be of type |
|
137 * <code>XPathResult</code>. |
|
138 * @return The result of the evaluation of the XPath expression.For XPath |
|
139 * 1.0 results, this object will be of type <code>XPathResult</code>. |
|
140 * @exception XPathException |
|
141 * INVALID_EXPRESSION_ERR: Raised if the expression is not legal |
|
142 * according to the rules of the <code>XPathEvaluator</code>i |
|
143 * <br>TYPE_ERR: Raised if the result cannot be converted to return the |
|
144 * specified type. |
|
145 * @exception DOMException |
|
146 * NAMESPACE_ERR: Raised if the expression contains namespace prefixes |
|
147 * which cannot be resolved by the specified |
|
148 * <code>XPathNSResolver</code>. |
|
149 * <br>WRONG_DOCUMENT_ERR: The Node is from a document that is not |
|
150 * supported by this <code>XPathEvaluator</code>. |
|
151 * <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath |
|
152 * context node or the request type is not permitted by this |
|
153 * <code>XPathEvaluator</code>. |
|
154 */ |
|
155 public Object evaluate(String expression, |
|
156 Node contextNode, |
|
157 XPathNSResolver resolver, |
|
158 short type, |
|
159 Object result) |
|
160 throws XPathException, DOMException; |
|
161 |
|
162 } |