XPathEvaluatorImpl


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