View Javadoc

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