KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > sf > saxon > sxpath > XPathExpression


1 package net.sf.saxon.sxpath;
2
3 import net.sf.saxon.expr.Expression;
4 import net.sf.saxon.expr.XPathContextMajor;
5 import net.sf.saxon.instruct.SlotManager;
6 import net.sf.saxon.trans.XPathException;
7 import net.sf.saxon.value.SequenceExtent;
8 import net.sf.saxon.value.Value;
9 import net.sf.saxon.om.NodeInfo;
10 import net.sf.saxon.om.SequenceIterator;
11 import net.sf.saxon.om.Item;
12
13 import javax.xml.transform.Source JavaDoc;
14 import java.util.Collections JavaDoc;
15 import java.util.List JavaDoc;
16
17 /**
18  * This class is a representation of an XPath Expression for use with the XPathEvaluator class.
19  * It is modelled on the XPath API defined in JAXP 1.3, but is cut down to remove any dependencies on JAXP 1.3,
20  * making it suitable for use on vanilla JDK 1.4 installations.
21  *
22  * @author Michael H. Kay
23  */
24
25
26 public class XPathExpression {
27
28     private XPathEvaluator evaluator;
29     private Expression expression;
30     private SlotManager stackFrameMap;
31
32     /**
33      * The constructor is protected, to ensure that instances can only be
34      * created using the createExpression() method of XPathEvaluator
35      */
36
37     protected XPathExpression(XPathEvaluator evaluator, Expression exp) {
38         expression = exp;
39         this.evaluator = evaluator;
40     }
41
42     /**
43      * Define the number of slots needed for local variables within the expression
44      */
45
46     protected void setStackFrameMap(SlotManager map) {
47         stackFrameMap = map;
48     }
49
50     /**
51      * Execute a prepared XPath expression, returning the results as a List.
52      *
53      * @param source the document or other node against which the XPath expression
54      * will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
55      * existing tree, or it may be any kind of JAXP Source object such as a StreamSource
56      * SAXSource or DOMSource.
57      * @return The results of the expression, as a List. The List represents the sequence
58      * of items returned by the expression. Each item in the list will either be an instance
59      * of net.sf.saxon.om.NodeInfo, representing a node, or a Java object representing an atomic value.
60      */
61
62     public List JavaDoc evaluate(Source JavaDoc source) throws XPathException {
63         NodeInfo origin;
64         if (source instanceof NodeInfo) {
65             origin = (NodeInfo)source;
66         } else {
67             origin = evaluator.build(source);
68         }
69         XPathContextMajor context = new XPathContextMajor(origin, evaluator.getConfiguration());
70         context.openStackFrame(stackFrameMap);
71         SequenceIterator iter = expression.iterate(context);
72         SequenceExtent extent = new SequenceExtent(iter);
73         List JavaDoc result = (List JavaDoc)extent.convertToJava(List JavaDoc.class, context);
74         if (result == null) {
75             result = Collections.EMPTY_LIST;
76         }
77         return result;
78     }
79
80     /**
81      * Execute a prepared XPath expression, returning the first item in the result.
82      * This is useful where it is known that the expression will only return
83      * a singleton value (for example, a single node, or a boolean).
84      * @param source the document or other node against which the XPath expression
85      * will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
86      * existing tree, or it may be any kind of JAXP Source object such as a StreamSource
87      * SAXSource or DOMSource.
88      *
89      * @return The first item in the sequence returned by the expression. If the expression
90      * returns an empty sequence, this method returns null. Otherwise, it returns the first
91      * item in the result sequence, represented as a Java object using the same mapping as for
92      * the evaluate() method
93      */
94
95     public Object JavaDoc evaluateSingle(Source JavaDoc source) throws XPathException {
96         NodeInfo origin;
97         if (source instanceof NodeInfo) {
98             origin = (NodeInfo)source;
99         } else {
100             origin = evaluator.build(source);
101         }
102         XPathContextMajor context = new XPathContextMajor(origin, evaluator.getConfiguration());
103         context.openStackFrame(stackFrameMap);
104         SequenceIterator iterator = expression.iterate(context);
105         Item item = iterator.next();
106         if (item == null) {
107             return null;
108         } else {
109             return Value.convert(item);
110         }
111     }
112
113     /**
114      * Get a raw iterator over the results of the expression. This returns results without
115      * any conversion of the returned items to "native" Java classes. This method is intended
116      * for use by applications that need to process the results of the expression using
117      * internal Saxon interfaces.
118      * @param source the document or other node against which the XPath expression
119      * will be evaluated. This may be a Saxon NodeInfo object, representing a node in an
120      * existing tree, or it may be any kind of JAXP Source object such as a StreamSource
121      * SAXSource or DOMSource.
122      */
123
124     public SequenceIterator rawIterator(Source JavaDoc source) throws XPathException {
125         NodeInfo origin;
126         if (source instanceof NodeInfo) {
127             origin = (NodeInfo)source;
128         } else {
129             origin = evaluator.build(source);
130         }
131         XPathContextMajor context = new XPathContextMajor(origin, evaluator.getConfiguration());
132         context.openStackFrame(stackFrameMap);
133         SequenceIterator iterator = expression.iterate(context);
134         return iterator;
135     }
136
137     /**
138      * Low-level method to get the internal Saxon expression object. This exposes a wide range of
139      * internal methods that may be needed by specialized applications, and allows greater control
140      * over the dynamic context for evaluating the expression.
141      *
142      * @return the underlying Saxon expression object.
143      */
144
145     public Expression getInternalExpression() {
146         return expression;
147     }
148
149 }
150
151 //
152 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
153 // you may not use this file except in compliance with the License. You may obtain a copy of the
154 // License at http://www.mozilla.org/MPL/
155 //
156 // Software distributed under the License is distributed on an "AS IS" basis,
157 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
158 // See the License for the specific language governing rights and limitations under the License.
159 //
160 // The Original Code is: all this file.
161
162 // The Initial Developer of the Original Code is
163 // Michael H. Kay.
164 //
165 // Contributor(s):
166 //
167
Popular Tags