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

Defined in the sis-feature module

  • 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<? super 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<? super 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<? super R>> applyAndDecompose(Filter<R> filter)
      Optimizes or simplifies the given filter and returns it as a list of AND operands. If such list can not 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 can not. 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.
    • 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 that 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: