KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xpath > XPathAPI


1 /*
2  * Copyright 1999-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: XPathAPI.java,v 1.17 2004/02/17 04:30:02 minchau Exp $
18  */
19 package org.apache.xpath;
20
21 import javax.xml.transform.TransformerException JavaDoc;
22
23 import org.apache.xml.utils.PrefixResolver;
24 import org.apache.xml.utils.PrefixResolverDefault;
25 import org.apache.xpath.objects.XObject;
26
27 import org.w3c.dom.Document JavaDoc;
28 import org.w3c.dom.Node JavaDoc;
29 import org.w3c.dom.NodeList JavaDoc;
30 import org.w3c.dom.traversal.NodeIterator;
31
32 /**
33  * The methods in this class are convenience methods into the
34  * low-level XPath API.
35  * These functions tend to be a little slow, since a number of objects must be
36  * created for each evaluation. A faster way is to precompile the
37  * XPaths using the low-level API, and then just use the XPaths
38  * over and over.
39  *
40  * NOTE: In particular, each call to this method will create a new
41  * XPathContext, a new DTMManager... and thus a new DTM. That's very
42  * safe, since it guarantees that you're always processing against a
43  * fully up-to-date view of your document. But it's also portentially
44  * very expensive, since you're rebuilding the DTM every time. You should
45  * consider using an instance of CachedXPathAPI rather than these static
46  * methods.
47  *
48  * @see <a HREF="http://www.w3.org/TR/xpath">XPath Specification</a>
49  * */
50 public class XPathAPI
51 {
52
53   /**
54    * Use an XPath string to select a single node. XPath namespace
55    * prefixes are resolved from the context node, which may not
56    * be what you want (see the next method).
57    *
58    * @param contextNode The node to start searching from.
59    * @param str A valid XPath string.
60    * @return The first node found that matches the XPath, or null.
61    *
62    * @throws TransformerException
63    */
64   public static Node JavaDoc selectSingleNode(Node JavaDoc contextNode, String JavaDoc str)
65           throws TransformerException JavaDoc
66   {
67     return selectSingleNode(contextNode, str, contextNode);
68   }
69
70   /**
71    * Use an XPath string to select a single node.
72    * XPath namespace prefixes are resolved from the namespaceNode.
73    *
74    * @param contextNode The node to start searching from.
75    * @param str A valid XPath string.
76    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
77    * @return The first node found that matches the XPath, or null.
78    *
79    * @throws TransformerException
80    */
81   public static Node JavaDoc selectSingleNode(
82           Node JavaDoc contextNode, String JavaDoc str, Node JavaDoc namespaceNode)
83             throws TransformerException JavaDoc
84   {
85
86     // Have the XObject return its result as a NodeSetDTM.
87 NodeIterator nl = selectNodeIterator(contextNode, str, namespaceNode);
88
89     // Return the first node, or null
90 return nl.nextNode();
91   }
92
93   /**
94    * Use an XPath string to select a nodelist.
95    * XPath namespace prefixes are resolved from the contextNode.
96    *
97    * @param contextNode The node to start searching from.
98    * @param str A valid XPath string.
99    * @return A NodeIterator, should never be null.
100    *
101    * @throws TransformerException
102    */
103   public static NodeIterator selectNodeIterator(Node JavaDoc contextNode, String JavaDoc str)
104           throws TransformerException JavaDoc
105   {
106     return selectNodeIterator(contextNode, str, contextNode);
107   }
108
109   /**
110    * Use an XPath string to select a nodelist.
111    * XPath namespace prefixes are resolved from the namespaceNode.
112    *
113    * @param contextNode The node to start searching from.
114    * @param str A valid XPath string.
115    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
116    * @return A NodeIterator, should never be null.
117    *
118    * @throws TransformerException
119    */
120   public static NodeIterator selectNodeIterator(
121           Node JavaDoc contextNode, String JavaDoc str, Node JavaDoc namespaceNode)
122             throws TransformerException JavaDoc
123   {
124
125     // Execute the XPath, and have it return the result
126 XObject list = eval(contextNode, str, namespaceNode);
127
128     // Have the XObject return its result as a NodeSetDTM.
129 return list.nodeset();
130   }
131
132   /**
133    * Use an XPath string to select a nodelist.
134    * XPath namespace prefixes are resolved from the contextNode.
135    *
136    * @param contextNode The node to start searching from.
137    * @param str A valid XPath string.
138    * @return A NodeIterator, should never be null.
139    *
140    * @throws TransformerException
141    */
142   public static NodeList JavaDoc selectNodeList(Node JavaDoc contextNode, String JavaDoc str)
143           throws TransformerException JavaDoc
144   {
145     return selectNodeList(contextNode, str, contextNode);
146   }
147
148   /**
149    * Use an XPath string to select a nodelist.
150    * XPath namespace prefixes are resolved from the namespaceNode.
151    *
152    * @param contextNode The node to start searching from.
153    * @param str A valid XPath string.
154    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
155    * @return A NodeIterator, should never be null.
156    *
157    * @throws TransformerException
158    */
159   public static NodeList JavaDoc selectNodeList(
160           Node JavaDoc contextNode, String JavaDoc str, Node JavaDoc namespaceNode)
161             throws TransformerException JavaDoc
162   {
163
164     // Execute the XPath, and have it return the result
165 XObject list = eval(contextNode, str, namespaceNode);
166
167     // Return a NodeList.
168 return list.nodelist();
169   }
170
171   /**
172    * Evaluate XPath string to an XObject. Using this method,
173    * XPath namespace prefixes will be resolved from the namespaceNode.
174    * @param contextNode The node to start searching from.
175    * @param str A valid XPath string.
176    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
177    * @return An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
178    * @see org.apache.xpath.objects.XObject
179    * @see org.apache.xpath.objects.XNull
180    * @see org.apache.xpath.objects.XBoolean
181    * @see org.apache.xpath.objects.XNumber
182    * @see org.apache.xpath.objects.XString
183    * @see org.apache.xpath.objects.XRTreeFrag
184    *
185    * @throws TransformerException
186    */
187   public static XObject eval(Node JavaDoc contextNode, String JavaDoc str)
188           throws TransformerException JavaDoc
189   {
190     return eval(contextNode, str, contextNode);
191   }
192
193   /**
194    * Evaluate XPath string to an XObject.
195    * XPath namespace prefixes are resolved from the namespaceNode.
196    * The implementation of this is a little slow, since it creates
197    * a number of objects each time it is called. This could be optimized
198    * to keep the same objects around, but then thread-safety issues would arise.
199    *
200    * @param contextNode The node to start searching from.
201    * @param str A valid XPath string.
202    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
203    * @return An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
204    * @see org.apache.xpath.objects.XObject
205    * @see org.apache.xpath.objects.XNull
206    * @see org.apache.xpath.objects.XBoolean
207    * @see org.apache.xpath.objects.XNumber
208    * @see org.apache.xpath.objects.XString
209    * @see org.apache.xpath.objects.XRTreeFrag
210    *
211    * @throws TransformerException
212    */
213   public static XObject eval(Node JavaDoc contextNode, String JavaDoc str, Node JavaDoc namespaceNode)
214           throws TransformerException JavaDoc
215   {
216
217     // Since we don't have a XML Parser involved here, install some default support
218 // for things like namespaces, etc.
219 // (Changed from: XPathContext xpathSupport = new XPathContext();
220 // because XPathContext is weak in a number of areas... perhaps
221 // XPathContext should be done away with.)
222 XPathContext xpathSupport = new XPathContext();
223
224     // Create an object to resolve namespace prefixes.
225 // XPath namespaces are resolved from the input context node's document element
226 // if it is a root node, or else the current context node (for lack of a better
227 // resolution space, given the simplicity of this sample code).
228 PrefixResolverDefault prefixResolver = new PrefixResolverDefault(
229       (namespaceNode.getNodeType() == Node.DOCUMENT_NODE)
230       ? ((Document JavaDoc) namespaceNode).getDocumentElement() : namespaceNode);
231
232     // Create the XPath object.
233 XPath xpath = new XPath(str, null, prefixResolver, XPath.SELECT, null);
234
235     // Execute the XPath, and have it return the result
236 // return xpath.execute(xpathSupport, contextNode, prefixResolver);
237 int ctxtNode = xpathSupport.getDTMHandleFromNode(contextNode);
238
239     return xpath.execute(xpathSupport, ctxtNode, prefixResolver);
240   }
241
242   /**
243    * Evaluate XPath string to an XObject.
244    * XPath namespace prefixes are resolved from the namespaceNode.
245    * The implementation of this is a little slow, since it creates
246    * a number of objects each time it is called. This could be optimized
247    * to keep the same objects around, but then thread-safety issues would arise.
248    *
249    * @param contextNode The node to start searching from.
250    * @param str A valid XPath string.
251    * @param namespaceNode The node from which prefixes in the XPath will be resolved to namespaces.
252    * @param prefixResolver Will be called if the parser encounters namespace
253    * prefixes, to resolve the prefixes to URLs.
254    * @return An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
255    * @see org.apache.xpath.objects.XObject
256    * @see org.apache.xpath.objects.XNull
257    * @see org.apache.xpath.objects.XBoolean
258    * @see org.apache.xpath.objects.XNumber
259    * @see org.apache.xpath.objects.XString
260    * @see org.apache.xpath.objects.XRTreeFrag
261    *
262    * @throws TransformerException
263    */
264   public static XObject eval(
265           Node JavaDoc contextNode, String JavaDoc str, PrefixResolver prefixResolver)
266             throws TransformerException JavaDoc
267   {
268
269     // Since we don't have a XML Parser involved here, install some default support
270 // for things like namespaces, etc.
271 // (Changed from: XPathContext xpathSupport = new XPathContext();
272 // because XPathContext is weak in a number of areas... perhaps
273 // XPathContext should be done away with.)
274 // Create the XPath object.
275 XPath xpath = new XPath(str, null, prefixResolver, XPath.SELECT, null);
276
277     // Execute the XPath, and have it return the result
278 XPathContext xpathSupport = new XPathContext();
279     int ctxtNode = xpathSupport.getDTMHandleFromNode(contextNode);
280
281     return xpath.execute(xpathSupport, ctxtNode, prefixResolver);
282   }
283 }
284
Popular Tags