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​.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 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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `Optimization​.OnExpression<R,V>`
  Expression that can be optimized.
  `static interface`
  `Optimization​.OnFilter<R>`
  Filter that can be optimized.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Optimization()`
  Creates a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<R, V> Expression<? super R,? extends V>`
  `apply(Expression<R,V> expression)`
  Optimizes or simplifies the given expression.
  `<R> Filter<? super R>`
  `apply(Filter<R> filter)`
  Optimizes or simplifies the given filter.
  `<R> List<Filter<? super R>>`
  `applyAndDecompose(Filter<R> filter)`
  Optimizes or simplifies the given filter and returns it as a list of `AND` operands.
  `DefaultFeatureType`
  `getFeatureType()`
  Returns the type of feature instances to be filtered, or `null` if unknown.
  `static <R, V> Expression<R,V>`
  `literal(V value)`
  Creates a constant, literal value that can be used in expressions.
  `void`
  `setFeatureType(DefaultFeatureType type)`
  Sets the type of feature instances to be filtered.

  ### Methods inherited from class Object

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

- ## 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 `setFeatureType(DefaultFeatureType)`. 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 `ObjectConverter`s 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​.OnFilter` 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:
      `IllegalArgumentException` - 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​.OnExpression` 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:
      `IllegalArgumentException` - 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:
      `ClassCastException` - if a filter declares the `AND`, `OR` or `NOT` type without implementing the `LogicalOperator` 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:
      - `DefaultFilterFactory​.literal(Object)`