XPathEvaluatorImpl


1   /*
2    * Copyright 2002-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * $Id$
18   */
19  
20  package org.apache.xpath.domapi;
21  
22  import javax.xml.transform.TransformerException  ;
23  
24  import org.apache.xalan.res.XSLMessages;
25  import org.apache.xml.utils.PrefixResolver;
26  import org.apache.xpath.XPath;
27  import org.apache.xpath.res.XPATHErrorResources;
28  
29  import org.w3c.dom.DOMException  ;
30  import org.w3c.dom.Document  ;
31  import org.w3c.dom.Node  ;
32  import org.w3c.dom.xpath.XPathEvaluator;
33  import org.w3c.dom.xpath.XPathException;
34  import org.w3c.dom.xpath.XPathExpression;
35  import org.w3c.dom.xpath.XPathNSResolver;
36  
37  /**
38   *
39   * The class provides an implementation of XPathEvaluator according 
40   * to the DOM L3 XPath Specification, Working Draft 28, March 2002.
41   *
42   * <p>See also the <a HREF='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.</p>
43   * 
44   * </p>The evaluation of XPath expressions is provided by 
45   * <code>XPathEvaluator</code>, which will provide evaluation of XPath 1.0 
46   * expressions with no specialized extension functions or variables. It is 
47   * expected that the <code>XPathEvaluator</code> interface will be 
48   * implemented on the same object which implements the <code>Document</code> 
49   * interface in an implementation which supports the XPath DOM module. 
50   * <code>XPathEvaluator</code> implementations may be available from other 
51   * sources that may provide support for special extension functions or 
52   * variables which are not defined in this specification.</p>
53   * 
54   * @see org.w3c.dom.xpath.XPathEvaluator
55   * 
56   * @xsl.usage experimental
57   */
58  public class XPathEvaluatorImpl implements XPathEvaluator {
59  
60      /**
61       * This prefix resolver is created whenever null is passed to the 
62       * evaluate method.  Its purpose is to satisfy the DOM L3 XPath API
63       * requirement that if a null prefix resolver is used, an exception 
64       * should only be thrown when an attempt is made to resolve a prefix.
65       */
66      class DummyPrefixResolver implements PrefixResolver {
67  
68          /**
69           * Constructor for DummyPrefixResolver.
70           */
71          public DummyPrefixResolver() {}
72              
73          /**
74           * @exception DOMException
75           *   NAMESPACE_ERR: Always throws this exceptionn
76           *
77           * @see org.apache.xml.utils.PrefixResolver#getNamespaceForPrefix(String, Node)
78           */
79          public String   getNamespaceForPrefix(String   prefix, Node   context) {
80              String   fmsg = XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NULL_RESOLVER, null);       
81              throw new DOMException  (DOMException.NAMESPACE_ERR, fmsg);   // Unable to resolve prefix with null prefix resolver.         
82          }
83  
84          /**
85           * @exception DOMException
86           *   NAMESPACE_ERR: Always throws this exceptionn
87           * 
88           * @see org.apache.xml.utils.PrefixResolver#getNamespaceForPrefix(String)
89           */
90          public String   getNamespaceForPrefix(String   prefix) {
91              return getNamespaceForPrefix(prefix,null);
92          }
93  
94          /**
95           * @see org.apache.xml.utils.PrefixResolver#handlesNullPrefixes()
96           */
97          public boolean handlesNullPrefixes() {
98              return false;
99          }
100 
101         /**
102          * @see org.apache.xml.utils.PrefixResolver#getBaseIdentifier()
103          */
104         public String   getBaseIdentifier() {
105             return null;
106         }
107 
108     }
109 
110     /**
111      * The document to be searched to parallel the case where the XPathEvaluator
112      * is obtained by casting a Document.
113      */  
114     private Document   m_doc = null;
115     
116     /**
117      * Constructor for XPathEvaluatorImpl.
118      */
119     public XPathEvaluatorImpl() {
120         super();
121     }
122     
123      /**
124      * Constructor for XPathEvaluatorImpl.
125      * 
126      * @param doc The document to be searched, to parallel the case where''
127      *            the XPathEvaluator is obtained by casting the document.
128      */
129     public XPathEvaluatorImpl(Document   doc) {
130         m_doc = doc;
131     }
132 
133     /**
134      * Creates a parsed XPath expression with resolved namespaces. This is 
135      * useful when an expression will be reused in an application since it 
136      * makes it possible to compile the expression string into a more 
137      * efficient internal form and preresolve all namespace prefixes which 
138      * occur within the expression.
139      * 
140      * @param expression The XPath expression string to be parsed.
141      * @param resolver The <code>resolver</code> permits translation of 
142      *   prefixes within the XPath expression into appropriate namespace URIs
143      *   . If this is specified as <code>null</code>, any namespace prefix 
144      *   within the expression will result in <code>DOMException</code> 
145      *   being thrown with the code <code>NAMESPACE_ERR</code>.
146      * @return The compiled form of the XPath expression.
147      * @exception XPathException
148      *   INVALID_EXPRESSION_ERR: Raised if the expression is not legal 
149      *   according to the rules of the <code>XPathEvaluator</code>i
150      * @exception DOMException
151      *   NAMESPACE_ERR: Raised if the expression contains namespace prefixes 
152      *   which cannot be resolved by the specified 
153      *   <code>XPathNSResolver</code>.  
154      *  
155      * @see org.w3c.dom.xpath.XPathEvaluator#createExpression(String, XPathNSResolver)
156      */
157     public XPathExpression createExpression(
158         String   expression,
159         XPathNSResolver resolver)
160         throws XPathException, DOMException   {
161         
162         try {
163             
164             // If the resolver is null, create a dummy prefix resolver
165             XPath xpath =  new XPath(expression,null,
166                  ((null == resolver) ? new DummyPrefixResolver() : ((PrefixResolver)resolver)), 
167                   XPath.SELECT);
168                   
169             return new XPathExpressionImpl(xpath, m_doc);
170                   
171         } catch (TransformerException   e) {
172             throw new DOMException  (XPathException.INVALID_EXPRESSION_ERR,e.getMessageAndLocation());
173         }
174     }
175 
176     /**
177      * Adapts any DOM node to resolve namespaces so that an XPath expression 
178      * can be easily evaluated relative to the context of the node where it 
179      * appeared within the document. This adapter works like the DOM Level 3 
180      * method <code>lookupNamespaceURI</code> on nodes in resolving the 
181      * namespaceURI from a given prefix using the current information available 
182      * in the node's hierarchy at the time lookupNamespaceURI is called, also 
183      * correctly resolving the implicit xml prefix.
184      *
185      * @param nodeResolver The node to be used as a context for namespace 
186      *   resolution.
187      * @return <code>XPathNSResolver</code> which resolves namespaces with 
188      *   respect to the definitions in scope for a specified node.
189      *  
190      * @see org.w3c.dom.xpath.XPathEvaluator#createNSResolver(Node)
191      */
192     public XPathNSResolver createNSResolver(Node   nodeResolver) {
193     
194         return new XPathNSResolverImpl((nodeResolver.getNodeType() == Node.DOCUMENT_NODE)
195                ? ((Document  ) nodeResolver).getDocumentElement() : nodeResolver);
196     }
197 
198     /**
199      * Evaluates an XPath expression string and returns a result of the 
200      * specified type if possible.
201      * 
202      * @param expression The XPath expression string to be parsed and 
203      *   evaluated.
204      * @param contextNode The <code>context</code> is context node for the 
205      *   evaluation of this XPath expression. If the XPathEvaluator was 
206      *   obtained by casting the <code>Document</code> then this must be 
207      *   owned by the same document and must be a <code>Document</code>, 
208      *   <code>Element</code>, <code>Attribute</code>, <code>Text</code>, 
209      *   <code>CDATASection</code>, <code>Comment</code>, 
210      *   <code>ProcessingInstruction</code>, or <code>XPathNamespace</code> 
211      *   node. If the context node is a <code>Text</code> or a 
212      *   <code>CDATASection</code>, then the context is interpreted as the 
213      *   whole logical text node as seen by XPath, unless the node is empty 
214      *   in which case it may not serve as the XPath context.
215      * @param resolver The <code>resolver</code> permits translation of 
216      *   prefixes within the XPath expression into appropriate namespace URIs
217      *   . If this is specified as <code>null</code>, any namespace prefix 
218      *   within the expression will result in <code>DOMException</code> 
219      *   being thrown with the code <code>NAMESPACE_ERR</code>.
220      * @param type If a specific <code>type</code> is specified, then the 
221      *   result will be coerced to return the specified type relying on 
222      *   XPath type conversions and fail if the desired coercion is not 
223      *   possible. This must be one of the type codes of 
224      *   <code>XPathResult</code>.
225      * @param result The <code>result</code> specifies a specific result 
226      *   object which may be reused and returned by this method. If this is 
227      *   specified as <code>null</code>or the implementation does not reuse 
228      *   the specified result, a new result object will be constructed and 
229      *   returned.For XPath 1.0 results, this object will be of type 
230      *   <code>XPathResult</code>.
231      * @return The result of the evaluation of the XPath expression.For XPath 
232      *   1.0 results, this object will be of type <code>XPathResult</code>.
233      * @exception XPathException
234      *   INVALID_EXPRESSION_ERR: Raised if the expression is not legal 
235      *   according to the rules of the <code>XPathEvaluator</code>i
236      *   <br>TYPE_ERR: Raised if the result cannot be converted to return the 
237      *   specified type.
238      * @exception DOMException
239      *   NAMESPACE_ERR: Raised if the expression contains namespace prefixes 
240      *   which cannot be resolved by the specified 
241      *   <code>XPathNSResolver</code>.
242      *   <br>WRONG_DOCUMENT_ERR: The Node is from a document that is not 
243      *   supported by this XPathEvaluator.
244      *   <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath 
245      *   context node.
246      * 
247      * @see org.w3c.dom.xpath.XPathEvaluator#evaluate(String, Node, XPathNSResolver, short, XPathResult)
248      */
249     public Object   evaluate(
250         String   expression,
251         Node   contextNode,
252         XPathNSResolver resolver,
253         short type,
254         Object   result)
255         throws XPathException, DOMException   {
256             
257         XPathExpression xpathExpression = createExpression(expression, resolver);
258         
259         return  xpathExpression.evaluate(contextNode, type, result);
260     }
261 
262 }
263
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags