org.geotools.filter.visitor

Class CapabilitiesFilterSplitter

Object

CapabilitiesFilterSplitter

All Implemented Interfaces:

ExpressionVisitor, FilterVisitor

public class CapabilitiesFilterSplitter
extends Object
implements FilterVisitor, ExpressionVisitor

Determines what queries can be processed server side and which can be processed client side.

IMPLEMENTATION NOTE: This class is implemented as a stack processor. If you're curious how it works, compare it with the old SQLUnpacker class, which did the same thing using recursion in a more straightforward way.

Here's a non-implementors best-guess at the algorithm: Starting at the top of the filter, split each filter into its constituent parts. If the given FilterCapabilities support the given operator, then keep checking downwards.

The key is in knowing whether or not something "down the tree" from you wound up being supported or not. This is where the stacks come in. Right before handing off to accept() the sub- filters, we count how many things are currently on the "can be proccessed by the underlying datastore" stack (the preStack) and we count how many things are currently on the "need to be post- processed" stack.

After the accept() call returns, we look again at the preStack.size() and postStack.size(). If the postStack has grown, that means that there was stuff down in the accept()-ed filter that wasn't supportable. Usually this means that our filter isn't supportable, but not always.

In some cases a sub-filter being unsupported isn't necessarily bad, as we can 'unpack' OR statements into AND statements (DeMorgans rule/modus poens) and still see if we can handle the other side of the OR. Same with NOT and certain kinds of AND statements.

In addition this class supports the case where we're doing an split in the middle of a client-side transaction. I.e. imagine doing a against a WFS-T where you have to filter against actions that happened previously in the transaction. That's what the ClientTransactionAccessor interface does, and this class splits filters while respecting the information about deletes and updates that have happened previously in the Transaction. I can't say with certainty exactly how the logic for that part of this works, but the test suite does seem to test it and the tests do pass.

Since GeoTools 8.0, the ClientTransactionAccessor interface can also be used to instruct the splitter that a filter referencing a given PropertyName can't be encoded by the back-end, by returning Filter.EXCLUDE in getUpdateFilter(String). This is so because there may be the case where some attribute names are encodable to the back-end's query language, while others may not be, or may not be part of the stored data model. In such case, returning Filter.EXCLUDE makes the filter referencing the property name part of the post-processing filter instead of the pre-processing filter.

Since:

2.5.3

Author:

dzwiers, commented and ported from gt to ogc filters by saul.farber, ported to work upon org.geotools.filter.Capabilities by Gabriel Roldan

Constructor Summary

Constructors

Constructor and Description
CapabilitiesFilterSplitter(Capabilities fcs, FeatureType parent, ClientTransactionAccessor transactionAccessor) Create a new instance.

Method Summary

Modifier and Type	Method and Description
Filter	getFilterPost() Gets the filter that cannot be sent to the server and must be post-processed on the client by geotools.
Filter	getFilterPre() Gets the filter that can be sent to the server for pre-processing.
Object	visit(Add filter, Object notUsed)
Object	visit(After after, Object extraData)
Object	visit(And filter, Object notUsed)
Object	visit(AnyInteracts anyInteracts, Object extraData)
Object	visit(BBOX filter, Object notUsed)
Object	visit(Before before, Object extraData)
Object	visit(Begins begins, Object extraData)
Object	visit(BegunBy begunBy, Object extraData)
Object	visit(Beyond filter, Object notUsed)
protected Object	visit(BinaryTemporalOperator filter, Object data)
Object	visit(Contains filter, Object notUsed)
Object	visit(Crosses filter, Object notUsed)
Object	visit(Disjoint filter, Object notUsed)
Object	visit(Divide filter, Object notUsed)
Object	visit(During during, Object extraData)
Object	visit(DWithin filter, Object notUsed)
Object	visit(EndedBy endedBy, Object extraData)
Object	visit(Ends ends, Object extraData)
Object	visit(Equals filter, Object notUsed)
void	visit(ExcludeFilter filter)
Object	visit(ExcludeFilter filter, Object notUsed) Visit Filter.EXCLUDE (often used during data structure transformations).
Object	visit(Function expression, Object notUsed)
Object	visit(Id filter, Object notUsed)
void	visit(IncludeFilter filter)
Object	visit(IncludeFilter filter, Object notUsed) Visit Filter.INCLUDE (often used during data structure transformations).
Object	visit(Intersects filter, Object notUsed)
Object	visit(Literal expression, Object notUsed)
Object	visit(Meets meets, Object extraData)
Object	visit(MetBy metBy, Object extraData)
Object	visit(Multiply filter, Object notUsed)
Object	visit(NativeFilter filter, Object extraData)
Object	visit(NilExpression nilExpression, Object notUsed) Used to visit a Expression.NIL, also called for null where an expression is expected.
Object	visit(Not filter, Object notUsed)
Object	visit(Or filter, Object notUsed)
Object	visit(OverlappedBy overlappedBy, Object extraData)
Object	visit(Overlaps filter, Object notUsed)
Object	visit(PropertyIsBetween filter, Object extradata)
Object	visit(PropertyIsEqualTo filter, Object notUsed)
Object	visit(PropertyIsGreaterThan filter, Object notUsed)
Object	visit(PropertyIsGreaterThanOrEqualTo filter, Object notUsed)
Object	visit(PropertyIsLessThan filter, Object notUsed)
Object	visit(PropertyIsLessThanOrEqualTo filter, Object notUsed)
Object	visit(PropertyIsLike filter, Object notUsed)
Object	visit(PropertyIsNil filter, Object extraData)
Object	visit(PropertyIsNotEqualTo filter, Object notUsed)
Object	visit(PropertyIsNull filter, Object notUsed)
Object	visit(PropertyName expression, Object notUsed)
Object	visit(Subtract filter, Object notUsed)
Object	visit(TContains contains, Object extraData)
Object	visit(TEquals equals, Object extraData)
Object	visit(Touches filter, Object notUsed)
Object	visit(TOverlaps contains, Object extraData)
Object	visit(Within filter, Object notUsed)
Object	visitNullFilter(Object notUsed) Used to account for a null filter value.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CapabilitiesFilterSplitter

public CapabilitiesFilterSplitter(Capabilities fcs,
                                  FeatureType parent,
                                  ClientTransactionAccessor transactionAccessor)

Create a new instance.

Parameters:

fcs - The FilterCapabilties that describes what Filters/Expressions the server can process.

parent - The FeatureType that this filter involves. Why is this needed?

transactionAccessor - If the transaction is handled on the client and not the server then different filters must be sent to the server. This class provides a generic way of obtaining the information from the transaction.

Method Detail

getFilterPost

public Filter getFilterPost()

Gets the filter that cannot be sent to the server and must be post-processed on the client by geotools.

Returns:

the filter that cannot be sent to the server and must be post-processed on the client by geotools.

getFilterPre

public Filter getFilterPre()

Gets the filter that can be sent to the server for pre-processing.

Returns:

the filter that can be sent to the server for pre-processing.

visit

public void visit(IncludeFilter filter)

Parameters:

filter - the Filter to visit

See Also:

FilterVisitor.visit(IncludeFilter, Object)

visit

public void visit(ExcludeFilter filter)

Parameters:

filter - the Filter to visit

See Also:

FilterVisitor.visit(ExcludeFilter, Object)

visit

public Object visit(PropertyIsBetween filter,
                    Object extradata)

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the Filter to visit

See Also:

NOTE: This method is extra documented as an example of how all the other methods are implemented. If you want to know how this class works read this method first!

visit

public Object visit(PropertyIsEqualTo filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsGreaterThan filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsGreaterThanOrEqualTo filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsLessThan filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsLessThanOrEqualTo filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsNotEqualTo filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(BBOX filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Beyond filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Contains filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Crosses filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Disjoint filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(DWithin filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Equals filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Intersects filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Overlaps filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Touches filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Within filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsLike filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(And filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Not filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Or filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visitNullFilter

public Object visitNullFilter(Object notUsed)

Description copied from interface: FilterVisitor

Used to account for a null filter value.

This is particularly used during data structure transofrmations, however the use of null is not recommended. Please make use of Filter.NONE and Filter.ALL as placeholder objects that communicate intent.

Specified by:

visitNullFilter in interface FilterVisitor

Parameters:

notUsed - Value object provided to visitor

Returns:

subclass defined

visit

public Object visit(IncludeFilter filter,
                    Object notUsed)

Description copied from interface: FilterVisitor

Visit Filter.INCLUDE (often used during data structure transformations).

Specified by:

visit in interface FilterVisitor

Parameters:

filter - Filter.INCLUDE.

notUsed - Value object provided to visitor

Returns:

subclass supplied

visit

public Object visit(ExcludeFilter filter,
                    Object notUsed)

Description copied from interface: FilterVisitor

Visit Filter.EXCLUDE (often used during data structure transformations).

Specified by:

visit in interface FilterVisitor

Parameters:

filter - Filter.EXCLUDE.

notUsed - Value object provided to visitor

Returns:

subclass supplied

visit

public Object visit(PropertyIsNull filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyIsNil filter,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Id filter,
                    Object notUsed)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(PropertyName expression,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Literal expression,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Add filter,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Divide filter,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Multiply filter,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Subtract filter,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

visit

public Object visit(Function expression,
                    Object notUsed)

Specified by:

visit in interface ExpressionVisitor

See Also:

org.geotools.filter.FilterVisitor#visit(org.geotools.filter.FunctionExpression)

visit

public Object visit(NilExpression nilExpression,
                    Object notUsed)

Description copied from interface: ExpressionVisitor

Used to visit a Expression.NIL, also called for null where an expression is expected.

This is particularly useful when doing data transformations, as an example when using a StyleSymbolizer Expression.NIL can be used to represent the default stroke color.

Specified by:

visit in interface ExpressionVisitor

Returns:

implementation specific

visit

public Object visit(After after,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(AnyInteracts anyInteracts,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Before before,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Begins begins,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(BegunBy begunBy,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(During during,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(EndedBy endedBy,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Ends ends,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(Meets meets,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(MetBy metBy,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(OverlappedBy overlappedBy,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(TContains contains,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(TEquals equals,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

public Object visit(TOverlaps contains,
                    Object extraData)

Specified by:

visit in interface FilterVisitor

visit

protected Object visit(BinaryTemporalOperator filter,
                       Object data)

visit

public Object visit(NativeFilter filter,
                    Object extraData)

Specified by:

visit in interface FilterVisitor