org.biojava.utils.walker

Interface Visitor

All Known Implementing Classes:

FilteringContentHandler.FilterVisitor, FilterTransformer

public interface Visitor

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.

Writing Handler Methods.

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.

How Handler Methods Will Be Chosen

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.

Handler Methods for 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)

Since:

1.4

Author:

Matthew Pocock