View Javadoc

1   /*
2    * $Header$
3    * $Revision: 1128 $
4    * $Date: 2006-02-05 13:49:04 -0800 (Sun, 05 Feb 2006) $
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: XPathHandler.java 1128 2006-02-05 21:49:04Z elharo $
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 ('&lt;', '>', '&lt;=', or '>=') expression.
218      */
219     void startRelationalExpr() throws org.jaxen.saxpath.SAXPathException;
220 
221     /** Receive notification of the start of a relational ('&lt;', '>', '&lt;=', 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 }