1 /* 2 * $Header$ 3 * $Revision$ 4 * $Date$ 5 * 6 * ==================================================================== 7 * 8 * Copyright 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 are 13 * met: 14 * 15 * * Redistributions of source code must retain the above copyright 16 * notice, this list of conditions and the following disclaimer. 17 * 18 * * Redistributions in binary form must reproduce the above copyright 19 * notice, this list of conditions and the following disclaimer in the 20 * documentation and/or other materials provided with the distribution. 21 * 22 * * Neither the name of the Jaxen Project nor the names of its 23 * contributors may be used to endorse or promote products derived 24 * from this software without specific prior written permission. 25 * 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 27 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 29 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 30 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 31 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 32 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 33 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 34 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 35 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 36 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37 * 38 * ==================================================================== 39 * This software consists of voluntary contributions made by many 40 * individuals on behalf of the Jaxen Project and was originally 41 * created by bob mcwhirter <bob@werken.com> and 42 * James Strachan <jstrachan@apache.org>. For more information on the 43 * Jaxen Project, please see <http://www.jaxen.org/>. 44 * 45 * $Id$ 46 */ 47 48 package org.jaxen.expr; 49 50 import java.util.Iterator; 51 import java.util.List; 52 53 import org.jaxen.Context; 54 import org.jaxen.ContextSupport; 55 import org.jaxen.JaxenException; 56 import org.jaxen.UnsupportedAxisException; 57 58 /** 59 * <p>Represents a location step in a LocationPath. The node-set selected by 60 * the location step is the node-set that results from generating an initial 61 * node-set from the axis and node-test, and then filtering that node-set by 62 * each of the predicates in turn.</p> 63 * 64 * <p> 65 * The initial node-set consists of the nodes having the relationship to the 66 * context node specified by the axis, and having the node type and expanded-name 67 * specified by the node test.</p> 68 */ 69 public interface Step extends Predicated 70 { 71 72 /** 73 * Performs the node-test part of evaluating the step for the given node 74 * (which must be on the axis). 75 * 76 * @param node the node to test 77 * @param contextSupport function, namespace, and variable contexts 78 * @return true if the node matches this step; false if it doesn't 79 */ 80 boolean matches(Object node, 81 ContextSupport contextSupport) throws JaxenException; 82 83 /** 84 * Returns a <code>String</code> containing the XPath expression. 85 * 86 * @return the text form of this step 87 */ 88 String getText(); 89 90 /** 91 * Simplifies the XPath step. In practice, this is usually a noop. 92 * Jaxen does not currently perform any simplification. 93 */ 94 void simplify(); 95 96 /** 97 * Get an identifier for the current axis. 98 * 99 * @return the axis identifier 100 * @see org.jaxen.saxpath.Axis 101 */ 102 public int getAxis(); 103 104 /** 105 * Get an Iterator for the current axis starting in the given contextNode. 106 * 107 * @param contextNode the node from which to follow this step 108 * @param support the remaining context for the traversal 109 * @return an iterator over the nodes along the axis 110 * @throws UnsupportedAxisException if the navigator does not support this step's axis 111 */ 112 Iterator axisIterator(Object contextNode, 113 ContextSupport support) throws UnsupportedAxisException; 114 115 116 /** 117 * For each node in the given context calls matches() for every node on the 118 * axis, then filters the result by each of the predicates. 119 * 120 * @param context the node in context of its position in the document 121 * @return a list of matching nodes 122 */ 123 List evaluate(Context context) throws JaxenException; 124 125 } 126