001package org.biojava.utils.walker;
002
003
004/**
005 * Objects that can walk over a filter expression, showing each element to a
006 * visitor.
007 *
008 * <p>
009 * Walker implementations are not guaranteed to be thread-safe. In particular,
010 * it is not possible to use the same Walker instance with more than one
011 * thread if the visitor has return values. Walker implementations can be
012 * re-used once the previous walk has been completed.
013 * </p>
014 *
015 * 
016 * You should use FilterUtils.visitFilter to apply a visitor to a feature
017 * filter.
018 *
019 * 
020 * You can use WalkerFactory.getInstance().getWalker(visitor) to get a walker
021 * that is suitable for your visitor implementation. This will take care of
022 * all the magic needed to hook up visitor call-back methods to the walkers
023 * traversal of the features.
024 *
025 * If you don't like the walkers that WalkerFactory produces, you can implement
026 * this directly. This will work fine for simple visitors, e.g., which only have
027 * a single method for visting all filters, regardless of type.
028 *
029 * @author Matthew Pocock
030 */
031public interface Walker {
032  /**
033   * This walks the feature tree, showing the visitor each filter in
034   * the expression.
035   *
036   * @param filter
037   * @param visitor
038   */
039  public void walk(Object filter, Visitor visitor);
040
041  /**
042   * If the visitor has a return value, then the result of applying the visitor
043   * to the tree can be obtained using this method, otherwise the result will
044   * be null.
045   *
046   * @return the visitor's return value, or null
047   */
048  public Object getValue();
049}