/*

  * $Header$

  * $Revision: 1128 $

  * $Date: 2006-02-05 13:49:04 -0800 (Sun, 05 Feb 2006) $

  *

  * ====================================================================

  *

  * Copyright 2000-2002 bob mcwhirter & James Strachan.

  * All rights reserved.

  *

  *

  * Redistribution and use in source and binary forms, with or without

  * modification, are permitted provided that the following conditions are

  * met:

  * 

  *   * Redistributions of source code must retain the above copyright

  *     notice, this list of conditions and the following disclaimer.

  * 

  *   * Redistributions in binary form must reproduce the above copyright

  *     notice, this list of conditions and the following disclaimer in the

  *     documentation and/or other materials provided with the distribution.

  * 

  *   * Neither the name of the Jaxen Project nor the names of its

  *     contributors may be used to endorse or promote products derived 

  *     from this software without specific prior written permission.

  * 

  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED

  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER

  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  *

  * ====================================================================

  * This software consists of voluntary contributions made by many

  * individuals on behalf of the Jaxen Project and was originally

  * created by bob mcwhirter <bob@werken.com> and

  * James Strachan <jstrachan@apache.org>.  For more information on the

  * Jaxen Project, please see <http://www.jaxen.org/>.

  *

  * $Id: XPathHandler.java 1128 2006-02-05 21:49:04Z elharo $

  */

 package org.jaxen.saxpath;

 /** Interface for event-based XPath parsing.

  *

  *  <p>

  *  A {@link org.jaxen.saxpath.XPathReader} generates callbacks into

  *  an <code>XPathHandler</code> to allow for custom

  *  handling of the parse.

  *  </p>

  *

  *  <p>

  *  The callbacks very closely match the productions

  *  listed in the W3C XPath specification.  Gratuitous

  *  productions (e.g. Expr/startExpr()/endExpr()) are not

  *  included in this API.

  *  </p>

  *

  *  @author bob mcwhirter (bob@werken.com)

  */

 public interface XPathHandler

 {

     /** Receive notification of the start of an XPath expression parse.

      */

     void startXPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an XPath expression parse.

      */

     void endXPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a path expression.

      */

     void startPathExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a path expression.

      */

     void endPathExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of an absolute location path expression.

      */

     void startAbsoluteLocationPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an absolute location path expression.

      */

     void endAbsoluteLocationPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a relative location path expression.

      */

     void startRelativeLocationPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a relative location path expression.

      */

     void endRelativeLocationPath() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a name step.

      *

      *  @param axis the axis of this step

      *  @param prefix the namespace prefix for the name to test,

      *         or the empty string if no prefix is specified

      *  @param localName the local part of the name to test

      */

     void startNameStep(int axis,

                        String prefix,

                        String localName) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a NameStep

      */

     void endNameStep() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a text() step.

      *

      *  @param axis the axis of this step

      */

     void startTextNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a text() step.

      */

     void endTextNodeStep() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a comment() step.

      *

      *  @param axis the axis of this step

      */

     void startCommentNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a comment() step.

      */

     void endCommentNodeStep() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a node() step.

      *

      *  @param axis the axis of this step

      */

     void startAllNodeStep(int axis) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a node() step.

      */

     void endAllNodeStep() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a processing-instruction(...) step.

      *

      *  @param axis the axis of this step

      *  @param name the name of the processing-instruction, or

      *         the empty string if none is specified

      */

     void startProcessingInstructionNodeStep(int axis,

                                             String name) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a processing-instruction(...) step.

      */

     void endProcessingInstructionNodeStep() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a predicate.

      */

     void startPredicate() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a predicate.

      */

     void endPredicate() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a filter expression.

      */

     void startFilterExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a filter expression.

      */

     void endFilterExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of an 'or' expression.

      */

     void startOrExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an 'or' expression.

      *

      *  @param create flag that indicates if this expression

      *         should truly be instantiated, or if it was just

      *         a pass-through, based upon the grammar productions

      */

     void endOrExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of an 'and' expression.

      */

     void startAndExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an 'and' expression.

      *

      *  @param create flag that indicates if this expression

      *         should truly be instantiated, or if it was just

      *         a pass-through, based upon the grammar productions

      */

     void endAndExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of an equality ('=' or '!=') expression.

      */

     void startEqualityExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an equality ('=' or '!=') expression.

      *

      *  @param equalityOperator the operator specific to this particular

      *         equality expression.  If null, this expression

      *         is only a pass-through, and should not actually

      *         be instantiated.

      */

     void endEqualityExpr(int equalityOperator) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a relational ('<', '>', '<=', or '>=') expression.

      */

     void startRelationalExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a relational ('<', '>', '<=', or '>=') expression.

      *

      *  @param relationalOperator the operator specific to this particular

      *         relational expression.  If NO_OP, this expression

      *         is only a pass-through, and should not actually

      *         be instantiated.

      */

     void endRelationalExpr(int relationalOperator) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of an additive ('+' or '-') expression.

      */

     void startAdditiveExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of an additive ('+' or '-') expression.

      *

      *  @param additiveOperator the operator specific to this particular

      *         additive expression.   If NO_OP, this expression

      *         is only a pass-through, and should not actually

      *         be instantiated.

      */

     void endAdditiveExpr(int additiveOperator) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a multiplicative ('*', 'div' or 'mod') expression.

      */

     void startMultiplicativeExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a multiplicative ('*', 'div' or 'mod') expression.

      *

      *  @param multiplicativeOperator the operator specific to this particular

      *         multiplicative expression.  If null, this expression

      *         is only a pass-through, and should not actually

      *         be instantiated.

      */

     void endMultiplicativeExpr(int multiplicativeOperator) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a unary ('+' or '-') expression.

      */

     void startUnaryExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a unary ('+' or '-') expression.

      *

      *  @param unaryOperator the operator specific to this particular

      *         unary expression. If NO_OP, this expression is only

      *         a pass-through, and should not actually be instantiated.

      *         If not {@link org.jaxen.saxpath.Operator#NO_OP}, it will 

      *         always be {@link org.jaxen.saxpath.Operator#NEGATIVE}.

      */

     void endUnaryExpr(int unaryOperator) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the start of a union ('|') expression.

      */

     void startUnionExpr() throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a union ('|') expression.

      *

      *  @param create flag that indicates if this expression

      *         should truly be instantiated, or if it was just

      *         a pass-through, based upon the grammar productions

      */

     void endUnionExpr(boolean create) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of a number expression.

      *

      *  @param number the number value

      */

     void number(int number) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of a number expression.

      *

      *  @param number the number value

      */

     void number(double number) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of a literal expression.

      *

      *  @param literal the string literal value

      */

     void literal(String literal) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of a variable-reference expression.

      *

      *  @param prefix the namespace prefix of the variable

      *  @param variableName the local name of the variable

      */

     void variableReference(String prefix,

                            String variableName) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of a function call.

      *

      *  @param prefix the namespace prefix of the function

      *  @param functionName the local name of the function

      */

     void startFunction(String prefix,

                        String functionName) throws org.jaxen.saxpath.SAXPathException;

     /** Receive notification of the end of a function call

      */

     void endFunction() throws org.jaxen.saxpath.SAXPathException;

 }