package org.biojava.utils.walker; /** * Things that will be shown filters. * *
* Visitors will be shown filters by Walker instances. The walker will take care * of traversing filters like And, Or and ByParent that wrap other filters. *
* ** Visitor implementations must be public or package-private. This is because * the walker implementation needs to bind to methods directly, and not via a * publicly accessible interface. *
* ** The simplest form of a * visitor has the single method void featureFilter(FeatureFilter ff). In this * case, the visitor will have this one method called for all filters. *
* *
* Visitor Handler methods should all follow the same pattern. This will allow
* them to be recognised by introspection. For a feature filter class called
* Foo
or called FeatureFilter.Foo
, the visitor
* method should have the signature:
*
public void foo(Foo)* or *
public Bar foo(Foo)* It is an error to provide both handlers, but then your compiler will tell * you this in advance. * * *
* A given visitor should either provide void handlers, or always provide * handlers with the same return type. Do not mix these two. If you do, then * either the walker will not be created by WalkerFactory, or you will * experience strange run-time problems. *
* *
* There may potentialy be several methods that could be used to handle a
* feature filter. Using the above example, Foo
obviously extends
* FeatureFilter
, so if there is a handler method for both classes,
* there is an ambiguity. The tree walker will always call the handler method
* that implements the most derived class. Only one handler will ever be
* called for one filter.
*
* If there is no handler for a particular filter class, then no action will
* be taken. In particular, if you supply a handler for just Foo
,
* and for no other filter types, even FeatureFilter
, then only
* Foo
filters will be shown to the visitor. In most cases, it will
* be wise to provide a handler for FeatureFilter
even if you think
* you handle all filter types, because this lets you throw a warning message.
*
And
and Other Things
* Some feature filters, such as FeatureFilter.And
wrap other
* filters. In some circumstances, it is usefull to know about these, and
* possibly to know about the results of visiting their children. The handler
* for filters with child filters will always be invoked after all children
* have been processed.
*
* In the case where all handlers return void, the handler for filters with
* children will follow the normal pattern. So, the handler for
* FeatureFilter.And
will be
*
public void and(FeatureFilter.And)* In the case where all handlers return instances of some class, the handlers * for filters with children will contain one extra argument per child. So, the * handler in this case would be *
public Bar and(FeatureFilter.And, Bar, Bar)* * @author Matthew Pocock * @since 1.4 */ public interface Visitor { }