| Frames | No Frames |
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: }