Package org.apache.sis.filter
Class Optimization
java.lang.Object
org.apache.sis.filter.Optimization
Description of optimizations or simplifications to attempt on filters and expressions.
Optimizations can include the following changes:
- Application of some logical identities such as
NOT(NOT(A)) == A
. - Application of logical short circuits such as
A & FALSE == FALSE
. - Immediate evaluation of expressions where all parameters are literal values.
- The type of the
Feature
instances to be filtered.
Usage in multi-threads context
This class is not thread-safe. A new instance shall be created for each thread applying optimizations. Example:How optimizations are applied
Optimizations are specific to each expression and filter type. For optimizations to happen, classes must implement theOptimization.OnExpression
or Optimization.OnFilter
interface.
The apply(Filter)
and apply(Expression)
methods in this Optimization
class merely
delegate to the methods defined in above-cited interfaces, with safety guards against infinite recursivity.
Behavioral changes
Optimized filters shall produce the same results than non-optimized filters. However side-effects may differ, in particular regarding exceptions that may be thrown. For example if a filter testsA & B
and if Optimization
determines that the B
condition will always evaluate to false
, then the A
condition will never be tested.
If that condition had side-effects or threw an exception,
those effects will disappear in the optimized filter.- Since:
- 1.1
- Version:
- 1.1
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Expression that can be optimized.static interface
Filter that can be optimized. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final Object
An arbitrary object meaning that a filter or expression optimization is under progress.Filters and expressions already optimized.private DefaultFeatureType
The type of feature instances to be filtered, ornull
if unknown. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription<R,
V> Expression<? super R, ? extends V> apply
(Expression<R, V> expression) Optimizes or simplifies the given expression.<R> Filter<? super R>
Optimizes or simplifies the given filter.applyAndDecompose
(Filter<R> filter) Optimizes or simplifies the given filter and returns it as a list ofAND
operands.Returns the type of feature instances to be filtered, ornull
if unknown.private static <R> Filter<? super R>
getNotOperand
(Filter<R> filter) Returns the singleton operand of the givenNOT
filter.static <R,
V> Expression<R, V> literal
(V value) Creates a constant, literal value that can be used in expressions.void
Sets the type of feature instances to be filtered.toAndOperands
(Filter<R> filter) Returns the given filter as a list ofAND
operands.
-
Field Details
-
COMPUTING
An arbitrary object meaning that a filter or expression optimization is under progress. -
featureType
The type of feature instances to be filtered, ornull
if unknown. -
done
Filters and expressions already optimized. Also used for avoiding never-ending loops. The map is created when first needed.Note: the same map is used for filters and expressions. It is not a problem if keys do not implement the two interfaces at the same time. If it happens anyway, it should still be okay because the method signatures are the same in both interfaces (only the return type changes), so the same methods would be invoked no matter if we consider the keys as a filter or an expression.
-
-
Constructor Details
-
Optimization
public Optimization()Creates a new instance.
-
-
Method Details
-
getFeatureType
Returns the type of feature instances to be filtered, ornull
if unknown. This is the last value specified by a call tosetFeatureType(DefaultFeatureType)
. The default value isnull
.- Returns:
- the type of feature instances to be filtered, or
null
if unknown.
-
setFeatureType
Sets the type of feature instances to be filtered. If this type is known in advance, specifying it may allow to compute more specificObjectConverter
s or to apply some geometry reprojection in advance.- Parameters:
type
- the type of feature instances to be filtered, ornull
if unknown.
-
apply
Optimizes or simplifies the given filter. If the given instance implements theOptimization.OnFilter
interface, then itsoptimize(this)
method is invoked. Otherwise this method returns the given filter as-is.- Type Parameters:
R
- the type of resources (e.g.Feature
) used as inputs.- Parameters:
filter
- the filter to optimize, ornull
.- Returns:
- the optimized filter, or
null
if the given filter was null. May befilter
if no optimization or simplification has been applied. - Throws:
IllegalArgumentException
- if the given filter is already in process of being optimized (i.e. there is a recursive call toapply(…)
for the same filter).
-
apply
Optimizes or simplifies the given expression. If the given instance implements theOptimization.OnExpression
interface, then itsoptimize(this)
method is invoked. Otherwise this method returns the given expression as-is.- Type Parameters:
R
- the type of resources (e.g.Feature
) used as inputs.V
- the type of values computed by the expression.- Parameters:
expression
- the expression to optimize, ornull
.- Returns:
- the optimized expression, or
null
if the given expression was null. May beexpression
if no optimization or simplification has been applied. - Throws:
IllegalArgumentException
- if the given expression is already in process of being optimized (i.e. there is a recursive call toapply(…)
for the same expression).
-
applyAndDecompose
Optimizes or simplifies the given filter and returns it as a list ofAND
operands. If such list cannot be built, then this method returns the optimized filter in a singleton list.Use case
This method tries to transform a filter into aF₀ AND F₁ AND F₂ AND F₃ AND ...
sequence. This transformation is useful when some operands can be handled by the storage engine (for example a SQL database) and other operands cannot. For example, when reading features from a relational database, the implementation may choose to express the F₁ and F₃ operands as SQL statements and apply the other operands in Java code.- Type Parameters:
R
- the type of resources (e.g.Feature
) used as inputs.- Parameters:
filter
- the filter to decompose.- Returns:
- a sequence of
AND
operands, or an empty list if the given filter was null. - Throws:
ClassCastException
- if a filter declares theAND
,OR
orNOT
type without implementing theLogicalOperator
interface.
-
toAndOperands
Returns the given filter as a list ofAND
operands. If such list cannot be built, then this method returns the given filter in a singleton list.- Type Parameters:
R
- the type of resources (e.g.Feature
) used as inputs.- Parameters:
filter
- the filter to decompose.- Returns:
- a sequence of
AND
operands, or an empty list if the given filter was null. - Throws:
ClassCastException
- if a filter declares theAND
,OR
orNOT
type without implementing theLogicalOperator
interface.
-
getNotOperand
Returns the singleton operand of the givenNOT
filter.- Parameters:
filter
- theNOT
filter.- Returns:
- the single operand of the
NOT
filter (never null). - Throws:
ClassCastException
- if the filter does not implement theLogicalOperator
interface.IllegalArgumentException
- if the filter does not have a single operand.
-
literal
Creates a constant, literal value that can be used in expressions. This is a helper methods for optimizations which simplified an expression to a constant value.- Type Parameters:
R
- the type of resources used as inputs.V
- the type of the value of the literal.- Parameters:
value
- the literal value. May benull
.- Returns:
- a literal for the given value.
- See Also:
-