View Javadoc

    1   /*
    2    * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/saxpath/XPathHandler.java,v 1.8 2005/06/28 13:44:46 elharo Exp $
    3    * $Revision: 1.8 $
    4    * $Date: 2005/06/28 13:44:46 $
    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.8 2005/06/28 13:44:46 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 (e.g. 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 ('&lt;', '>', '&lt;=', or '>=') expression.
    235      *
    236      *  @param relationalOperator the operator specific to this particular
    237      *         relational expression.  If NO_OP, 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 NO_OP, 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 NO_OP, 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 }