1 /*
2 * $Header$
3 * $Revision$
4 * $Date$
5 *
6 * ====================================================================
7 *
8 * Copyright 2000-2002 bob mcwhirter & James Strachan.
9 * All rights reserved.
10 *
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are
14 * met:
15 *
16 * * Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * * Redistributions in binary form must reproduce the above copyright
20 * notice, this list of conditions and the following disclaimer in the
21 * documentation and/or other materials provided with the distribution.
22 *
23 * * Neither the name of the Jaxen Project nor the names of its
24 * contributors may be used to endorse or promote products derived
25 * from this software without specific prior written permission.
26 *
27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
28 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
29 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
31 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
34 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
35 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
36 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
37 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 *
39 * ====================================================================
40 * This software consists of voluntary contributions made by many
41 * individuals on behalf of the Jaxen Project and was originally
42 * created by bob mcwhirter <bob@werken.com> and
43 * James Strachan <jstrachan@apache.org>. For more information on the
44 * Jaxen Project, please see <http://www.jaxen.org/>.
45 *
46 * $Id$
47 */
48
49
50
51
52 package org.jaxen.saxpath;
53
54
55 /** Interface for event-based XPath parsing.
56 *
57 * <p>
58 * A {@link org.jaxen.saxpath.XPathReader} generates callbacks into
59 * an <code>XPathHandler</code> to allow for custom
60 * handling of the parse.
61 * </p>
62 *
63 * <p>
64 * The callbacks very closely match the productions
65 * listed in the W3C XPath specification. Gratuitous
66 * productions (e.g. Expr/startExpr()/endExpr()) are not
67 * included in this API.
68 * </p>
69 *
70 * @author bob mcwhirter (bob@werken.com)
71 */
72 public interface XPathHandler
73 {
74 /** Receive notification of the start of an XPath expression parse.
75 */
76 void startXPath() throws org.jaxen.saxpath.SAXPathException;
77
78 /** Receive notification of the end of an XPath expression parse.
79 */
80 void endXPath() throws org.jaxen.saxpath.SAXPathException;
81
82 /** Receive notification of the start of a path expression.
83 */
84 void startPathExpr() throws org.jaxen.saxpath.SAXPathException;
85
86 /** Receive notification of the end of a path expression.
87 */
88 void endPathExpr() throws org.jaxen.saxpath.SAXPathException;
89
90 /** Receive notification of the start of an absolute location path expression.
91 */
92 void startAbsoluteLocationPath() throws org.jaxen.saxpath.SAXPathException;
93
94 /** Receive notification of the end of an absolute location path expression.
95 */
96 void endAbsoluteLocationPath() throws org.jaxen.saxpath.SAXPathException;
97
98 /** Receive notification of the start of a relative location path expression.
99 */
100 void startRelativeLocationPath() throws org.jaxen.saxpath.SAXPathException;
101
102 /** Receive notification of the end of a relative location path expression.
103 */
104 void endRelativeLocationPath() throws org.jaxen.saxpath.SAXPathException;
105
106 /** Receive notification of the start of a name step.
107 *
108 * @param axis the axis of this step
109 * @param prefix the namespace prefix for the name to test,
110 * or the empty string if no prefix is specified
111 * @param localName the local part of the name to test
112 */
113 void startNameStep(int axis,
114 String prefix,
115 String localName) throws org.jaxen.saxpath.SAXPathException;
116
117 /** Receive notification of the end of a NameStep
118 */
119 void endNameStep() throws org.jaxen.saxpath.SAXPathException;
120
121 /** Receive notification of the start of a text() step.
122 *
123 * @param axis the axis of this step
124 */
125 void startTextNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;
126
127 /** Receive notification of the end of a text() step.
128 */
129 void endTextNodeStep() throws org.jaxen.saxpath.SAXPathException;
130
131 /** Receive notification of the start of a comment() step.
132 *
133 * @param axis the axis of this step
134 */
135 void startCommentNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;
136
137 /** Receive notification of the end of a comment() step.
138 */
139 void endCommentNodeStep() throws org.jaxen.saxpath.SAXPathException;
140
141 /** Receive notification of the start of a node() step.
142 *
143 * @param axis the axis of this step
144 */
145 void startAllNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;
146
147 /** Receive notification of the end of a node() step.
148 */
149 void endAllNodeStep() throws org.jaxen.saxpath.SAXPathException;
150
151 /** Receive notification of the start of a processing-instruction(...) step.
152 *
153 * @param axis the axis of this step
154 * @param name the name of the processing-instruction, or
155 * the empty string if none is specified
156 */
157 void startProcessingInstructionNodeStep(int axis,
158 String name) throws org.jaxen.saxpath.SAXPathException;
159
160 /** Receive notification of the end of a processing-instruction(...) step.
161 */
162 void endProcessingInstructionNodeStep() throws org.jaxen.saxpath.SAXPathException;
163
164 /** Receive notification of the start of a predicate.
165 */
166 void startPredicate() throws org.jaxen.saxpath.SAXPathException;
167
168 /** Receive notification of the end of a predicate.
169 */
170 void endPredicate() throws org.jaxen.saxpath.SAXPathException;
171
172 /** Receive notification of the start of a filter expression.
173 */
174 void startFilterExpr() throws org.jaxen.saxpath.SAXPathException;
175
176 /** Receive notification of the end of a filter expression.
177 */
178 void endFilterExpr() throws org.jaxen.saxpath.SAXPathException;
179
180 /** Receive notification of the start of an 'or' expression.
181 */
182 void startOrExpr() throws org.jaxen.saxpath.SAXPathException;
183
184 /** Receive notification of the end of an 'or' expression.
185 *
186 * @param create flag that indicates if this expression
187 * should truly be instantiated, or if it was just
188 * a pass-through, based upon the grammar productions
189 */
190 void endOrExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;
191
192 /** Receive notification of the start of an 'and' expression.
193 */
194 void startAndExpr() throws org.jaxen.saxpath.SAXPathException;
195
196 /** Receive notification of the end of an 'and' expression.
197 *
198 * @param create flag that indicates if this expression
199 * should truly be instantiated, or if it was just
200 * a pass-through, based upon the grammar productions
201 */
202 void endAndExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;
203
204 /** Receive notification of the start of an equality ('=' or '!=') expression.
205 */
206 void startEqualityExpr() throws org.jaxen.saxpath.SAXPathException;
207
208 /** Receive notification of the end of an equality ('=' or '!=') expression.
209 *
210 * @param equalityOperator the operator specific to this particular
211 * equality expression. If null, this expression
212 * is only a pass-through, and should not actually
213 * be instantiated.
214 */
215 void endEqualityExpr(int equalityOperator) throws org.jaxen.saxpath.SAXPathException;
216
217 /** Receive notification of the start of a relational ('<', '>', '<=', or '>=') expression.
218 */
219 void startRelationalExpr() throws org.jaxen.saxpath.SAXPathException;
220
221 /** Receive notification of the start of a relational ('<', '>', '<=', or '>=') expression.
222 *
223 * @param relationalOperator the operator specific to this particular
224 * relational expression. If NO_OP, this expression
225 * is only a pass-through, and should not actually
226 * be instantiated.
227 */
228 void endRelationalExpr(int relationalOperator) throws org.jaxen.saxpath.SAXPathException;
229
230 /** Receive notification of the start of an additive ('+' or '-') expression.
231 */
232 void startAdditiveExpr() throws org.jaxen.saxpath.SAXPathException;
233
234 /** Receive notification of the end of an additive ('+' or '-') expression.
235 *
236 * @param additiveOperator the operator specific to this particular
237 * additive expression. If NO_OP, this expression
238 * is only a pass-through, and should not actually
239 * be instantiated.
240 */
241 void endAdditiveExpr(int additiveOperator) throws org.jaxen.saxpath.SAXPathException;
242
243 /** Receive notification of the start of a multiplicative ('*', 'div' or 'mod') expression.
244 */
245 void startMultiplicativeExpr() throws org.jaxen.saxpath.SAXPathException;
246
247 /** Receive notification of the start of a multiplicative ('*', 'div' or 'mod') expression.
248 *
249 * @param multiplicativeOperator the operator specific to this particular
250 * multiplicative expression. If null, this expression
251 * is only a pass-through, and should not actually
252 * be instantiated.
253 */
254 void endMultiplicativeExpr(int multiplicativeOperator) throws org.jaxen.saxpath.SAXPathException;
255
256 /** Receive notification of the start of a unary ('+' or '-') expression.
257 */
258 void startUnaryExpr() throws org.jaxen.saxpath.SAXPathException;
259
260 /** Receive notification of the end of a unary ('+' or '-') expression.
261 *
262 * @param unaryOperator the operator specific to this particular
263 * unary expression. If NO_OP, this expression is only
264 * a pass-through, and should not actually be instantiated.
265 * If not {@link org.jaxen.saxpath.Operator#NO_OP}, it will
266 * always be {@link org.jaxen.saxpath.Operator#NEGATIVE}.
267 */
268 void endUnaryExpr(int unaryOperator) throws org.jaxen.saxpath.SAXPathException;
269
270 /** Receive notification of the start of a union ('|') expression.
271 */
272 void startUnionExpr() throws org.jaxen.saxpath.SAXPathException;
273
274 /** Receive notification of the end of a union ('|') expression.
275 *
276 * @param create flag that indicates if this expression
277 * should truly be instantiated, or if it was just
278 * a pass-through, based upon the grammar productions
279 */
280 void endUnionExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;
281
282 /** Receive notification of a number expression.
283 *
284 * @param number the number value
285 */
286 void number(int number) throws org.jaxen.saxpath.SAXPathException;
287
288 /** Receive notification of a number expression.
289 *
290 * @param number the number value
291 */
292 void number(double number) throws org.jaxen.saxpath.SAXPathException;
293
294 /** Receive notification of a literal expression.
295 *
296 * @param literal the string literal value
297 */
298 void literal(String literal) throws org.jaxen.saxpath.SAXPathException;
299
300 /** Receive notification of a variable-reference expression.
301 *
302 * @param prefix the namespace prefix of the variable
303 * @param variableName the local name of the variable
304 */
305 void variableReference(String prefix,
306 String variableName) throws org.jaxen.saxpath.SAXPathException;
307
308 /** Receive notification of a function call.
309 *
310 * @param prefix the namespace prefix of the function
311 * @param functionName the local name of the function
312 */
313 void startFunction(String prefix,
314 String functionName) throws org.jaxen.saxpath.SAXPathException;
315
316 /** Receive notification of the end of a function call
317 */
318 void endFunction() throws org.jaxen.saxpath.SAXPathException;
319 }