001package org.biojava.utils.walker;
002
003/**
004 * Things that will be shown filters.
005 *
006 * <p>
007 * Visitors will be shown filters by Walker instances. The walker will take care
008 * of traversing filters like And, Or and ByParent that wrap other filters.
009 * </p>
010 *
011 * <p>
012 * Visitor implementations must be public or package-private. This is because
013 * the walker implementation needs to bind to methods directly, and not via a
014 * publicly accessible interface.
015 * </p>
016 * 
017 * <p>
018 * The simplest form of a
019 * visitor has the single method void featureFilter(FeatureFilter ff). In this
020 * case, the visitor will have this one method called for all filters.
021 * </p>
022 *
023 * <h2>Writing Handler Methods.</h2>
024 *
025 * <p>
026 * Visitor Handler methods should all follow the same pattern. This will allow
027 * them to be recognised by introspection. For a feature filter class called
028 * <code>Foo</code> or called <code>FeatureFilter.Foo</code>, the visitor
029 * method should have the signature:
030 * <pre>public void foo(Foo)</pre>
031 * or
032 * <pre>public Bar foo(Foo)</pre>
033 * It is an error to provide both handlers, but then your compiler will tell
034 * you this in advance.
035 * </p>
036 *
037 * <p>
038 * A given visitor should either provide void handlers, or always provide
039 * handlers with the same return type. Do not mix these two. If you do, then
040 * either the walker will not be created by WalkerFactory, or you will
041 * experience strange run-time problems.
042 * </p>
043 *
044 * <h2>How Handler Methods Will Be Chosen</h2>
045 *
046 * <p>
047 * There may potentialy be several methods that could be used to handle a
048 * feature filter. Using the above example, <code>Foo</code> obviously extends
049 * <code>FeatureFilter</code>, so if there is a handler method for both classes,
050 * there is an ambiguity. The tree walker will always call the handler method
051 * that implements the most derived class. Only one handler will ever be
052 * called for one filter.
053 * </p>
054 *
055 * <p>
056 * If there is no handler for a particular filter class, then no action will
057 * be taken. In particular, if you supply a handler for just <code>Foo</code>,
058 * and for no other filter types, even <code>FeatureFilter</code>, then only
059 * <code>Foo</code> filters will be shown to the visitor. In most cases, it will
060 * be wise to provide a handler for <code>FeatureFilter</code> even if you think
061 * you handle all filter types, because this lets you throw a warning message.
062 * </p>
063 *
064 * <h2>Handler Methods for <code>And</code> and Other Things</h2>
065 *
066 * <p>
067 * Some feature filters, such as <code>FeatureFilter.And</code> wrap other
068 * filters. In some circumstances, it is usefull to know about these, and
069 * possibly to know about the results of visiting their children. The handler
070 * for filters with child filters will always be invoked after all children
071 * have been processed.
072 * </p>
073 *
074 * <p>
075 * In the case where all handlers return void, the handler for filters with
076 * children will follow the normal pattern. So, the handler for
077 * <code>FeatureFilter.And</code> will be
078 * <pre>public void and(FeatureFilter.And)</pre>
079 * In the case where all handlers return instances of some class, the handlers
080 * for filters with children will contain one extra argument per child. So, the
081 * handler in this case would be
082 * <pre>public Bar and(FeatureFilter.And, Bar, Bar)</pre>
083 *
084 * @author Matthew Pocock
085 * @since 1.4
086 */
087public interface Visitor {
088}