Module org.apache.sis.feature
Package org.apache.sis.filter

Class Optimization

Object
Optimization
public class Optimization extends Object
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 following options can enable some additional optimizations:
  • 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: 
Filter<R> filter = ...;
filter = new Optimization().apply(filter);

How optimizations are applied

Optimizations are specific to each expression and filter type. For optimizations to happen, classes must implement the Optimization​.On­Expression or Optimization​.On­Filter 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 tests A & 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

  • Constructor Details

    • Optimization

      public Optimization()
      Creates a new instance.

  • Method Details

    • getFeatureType

      public DefaultFeatureType getFeatureType()
      Returns the type of feature instances to be filtered, or null if unknown. This is the last value specified by a call to set­Feature­Type(Default­Feature­Type). The default value is null.
      Returns:
      the type of feature instances to be filtered, or null if unknown.

    • setFeatureType

      public void setFeatureType(DefaultFeatureType type)
      Sets the type of feature instances to be filtered. If this type is known in advance, specifying it may allow to compute more specific Object­Converters or to apply some geometry reprojection in advance.
      Parameters:
      type - the type of feature instances to be filtered, or null if unknown.

    • apply

      public <R> Filter<R> apply(Filter<R> filter)
      Optimizes or simplifies the given filter. If the given instance implements the Optimization​.On­Filter interface, then its optimize(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, or null.
      Returns:
      the optimized filter, or null if the given filter was null. May be filter if no optimization or simplification has been applied.
      Throws:
      Illegal­Argument­Exception - if the given filter is already in process of being optimized (i.e. there is a recursive call to apply(…) for the same filter).

    • apply

      public <R, V> Expression<R,? extends V> apply(Expression<R,V> expression)
      Optimizes or simplifies the given expression. If the given instance implements the Optimization​.On­Expression interface, then its optimize(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, or null.
      Returns:
      the optimized expression, or null if the given expression was null. May be expression if no optimization or simplification has been applied.
      Throws:
      Illegal­Argument­Exception - if the given expression is already in process of being optimized (i.e. there is a recursive call to apply(…) for the same expression).

    • applyAndDecompose

      public <R> List<Filter<R>> applyAndDecompose(Filter<R> filter)
      Optimizes or simplifies the given filter and returns it as a list of AND 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 a F₀ 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:
      Class­Cast­Exception - if a filter declares the AND, OR or NOT type without implementing the Logical­Operator interface.

    • properties

      public static Set<FunctionProperty> properties(Filter<?> filter)
      Returns the manner in which values are computed from resources given to the specified filter. This set of properties may determine which optimizations are allowed. The values of particular interest are:
      • Function­Property​.VOLATILE if the computed value changes each time that the filter is evaluated, even if the resource to evaluate stay the same immutable instance.
      Parameters:
      filter - the filter for which to query function properties.
      Returns:
      the manners in which values are computed from resources.
      Since:
      1.4

    • properties

      public static Set<FunctionProperty> properties(Expression<?,?> expression)
      Returns the manner in which values are computed from resources given to the specified expression. This set of properties may determine which optimizations are allowed. The values of particular interest are:
      Parameters:
      expression - the expression for which to query function properties.
      Returns:
      the manners in which values are computed from resources.
      Since:
      1.4

    • literal

      public static <R, V> Expression<R,V> literal(V value)
      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 be null.
      Returns:
      a literal for the given value.
      See Also: