# Package org.apache.sis.filter

package org.apache.sis.filter
Filters features according their properties. A filter expression is a construct used to constraint a feature set to a subset. Operations in this package follow the rules of OGC® Filter Encoding and ISO 13249-3 - SQLMM standards.

## Coordinate reference system handling

Filters and expressions may contain heterogeneous coordinate reference systems. Apache SIS tries to handle differences in the following way:

- If at least one geometry does not has a CRS, then SIS assumes that the geometries are in the same space.
- If all geometries are in the same CRS, no coordinate operation is applied.
- If geometries have non-null but different CRS, then SIS tries to project the geometries in a common space:
  - For SQLMM operations, the CRS of the first operand is used (as required by the specification).
  - For other operations, the common CRS is chosen by referencing utility method. If that method cannot provide a common space, then an `IllegalArgumentException` is thrown.

## Performance tips

In expressions like `ST_Intersects(A,B)` where the A and B parameters are two sub-expressions evaluating to geometry values, if one of those expressions is a literal, then that literal should be B. The reason is because SQLMM specification requires us to project B in the Coordinate Reference System of A. If B is a literal, Apache SIS can do this transformation only once before to start any evaluation instead of every time that the expression needs to be evaluated.

Data store implementations should apply `Optimization` on the filters before to evaluate them.

## Thread-safety

All filter and expression implementations provided by Apache SIS are thread-safe. They are not necessarily stateless however; for example a filter may remember which warnings have been reported in order to avoid to report the same warning twice.

Since:
  1.1

Defined in the `sis-feature` module

- Class
  Description
  DefaultFilterFactory<R,G,T>
  A factory of default `Filter` and `Expression` implementations.
  DefaultFilterFactory.Features<G,T>
  A filter factory operating on `AbstractFeature` instances.
  Expression<R,V>
  A literal or a named procedure that performs a distinct computation.
  Filter<R>
  Identification of a subset of resources from a collection of resources whose property values satisfy a set of logically connected predicates.
  Optimization
  Description of optimizations or simplifications to attempt on filters and expressions.
  Optimization.OnExpression<R,V>
  Expression that can be optimized.
  Optimization.OnFilter<R>
  Filter that can be optimized.