Module org.opengis.geoapi

Package org.opengis.filter

Interface Filter<R>

Type Parameters:

R - the type of resources (e.g. Feature) to filter.

All Superinterfaces:

Predicate<R>

All Known Subinterfaces:

BetweenComparisonOperator<R>, BinaryComparisonOperator<R>, BinarySpatialOperator<R>, ComparisonOperator<R>, DistanceOperator<R>, LikeOperator<R>, LogicalOperator<R>, NilOperator<R>, NullOperator<R>, ResourceId<R>, SpatialOperator<R>, TemporalOperator<R>

@Classifier(ABSTRACT)
@UML(identifier="Filter",
     specification=ISO_19143)
public interface Filter<R>
extends Predicate<R>

Identification of a subset of resources from a collection of resources whose property values satisfy a set of logically connected predicates. Often a filter is used to define a set of Feature instances that are to be operated upon. The operating set can be comprised of one or more enumerated features or a set of features defined by specifying spatial and non-spatial constraints on the geometric and scalar properties of a FeatureType.

Roughly speaking, a filter encodes the information present in the WHERE clause of a SQL statement. There are various sub-interfaces of this interface that represent many types of filters, such as simple property comparisons or spatial queries.

The second use of Filter focuses on expressing constraints (or Facets). This use places restrictions on the allowable and is captured as part of schema information FeatureType. This is similar to the XML concept of "facets".

Parameter types

Filters are typically used for filtering feature instances. In such case, the <R> type parameter should be Feature. However it is legal to use filters for other kinds of resources, for example coverage's geometry-value pairs. The latter are sometime considered as a kind of features.

The value of <? super R> can be obtained at runtime by a call to getResourceClass().

Since:

3.1

Convenience extension to OGC/ISO standard

In ISO specification, Filter contains a "filter" property of type Operator. Then various Operator subclasses are provided such as SpatialOperator, etc. GeoAPI removes this indirection level and extends Filter directly instead.

Method Summary

Modifier and Type	Method	Description
static <R> Filter<R>	exclude()	A filter that always evaluates to false.
List<Expression<R,?>>	getExpressions()	Returns the expressions used as arguments for this filter.
CodeList<?>	getOperatorType()	Returns the nature of the operator.
Class<? super R>	getResourceClass()	Returns the class of resources expected by this filter.
static <R> Filter<R>	include()	A filter that always evaluates to true.
boolean	test(R object)	Given an object, determines if the test(s) represented by this filter are passed.

Methods inherited from interface java.util.function.Predicate

and, negate, or

Method Details

include

static <R> Filter<R> include()

A filter that always evaluates to true. This is a placeholder for meaning "no filtering". Filtering a set with Filter.INCLUDE results in the original set.

Use with logic operators

Operation	Result
INCLUDE or Filter	INCLUDE
INCLUDE and Filter	Filter
not INCLUDE	EXCLUDE

Type Parameters:

R - the type of resources to filter.

Returns:

the "no filtering" filter.

exclude

static <R> Filter<R> exclude()

A filter that always evaluates to false. Filtering a set with Filter.EXCLUDE results in the empty set.

Use with logic operators

Operation	Result
EXCLUDE or Filter	Filter
EXCLUDE and Filter	EXCLUDE
not EXCLUDE	INCLUDE

Type Parameters:

R - the type of resources to filter.

Returns:

the "exclude all" filter.

getOperatorType

CodeList<?> getOperatorType()

Returns the nature of the operator. The code list can be LogicalOperatorName, SpatialOperatorName, DistanceOperatorName or TemporalOperatorName depending on the Filter sub-interface.

Returns:

the nature of this operator.

Departure from OGC/ISO standard by generalization

The ISO/OGC standard defines an operatorType property in UnaryLogicOperator, BinaryLogicOperator, BinaryComparisonOperator, BinarySpatialOperator and DistanceOperator. This method has been added for providing a single access point for that information without the need to check for each sub-type.

getResourceClass

Class<? super R> getResourceClass()

Returns the class of resources expected by this filter. This is the runtime value of the <R> type, except that some implementations may accept instances of a more generic type such as Object.class. For example include() and exclude() put no restriction on the resource type because those filters ignore the given resource.

Implementation note

This filter resource class should be assignable to all resource classes expected by the expressions that are arguments of this filter. The type parametrization rules guarantee that at least one such specialized class exists: <R>. The behavior of this method is undefined if compile-time type safety was bypassed with unchecked casts, resulting in possible inconsistencies in the tree of expressions. The undefined behavior may be throwing an exception or returning null.

Returns:

type of resources accepted by this filter.

See Also:

• Expression.getResourceClass()

getExpressions

List<Expression<R,?>> getExpressions()

Returns the expressions used as arguments for this filter. This method shall return all parameters used directly by the filter, including the ones also available by dedicated methods (possibly as literals).

Returns:

the expressions used as inputs, or an empty list if none.

Departure from OGC/ISO standard by generalization

This method has been added for providing a single access point for information provided in sub-types. The properties captured here have different names in OGC/ISO specification depending on the sub-type: expression (with a cardinality of 1, 2 or unlimited), operand1, operand2, or valueReference. This method provides a way to access those expressions without the need to make special cases for each sub-type.

test

boolean test(R object)
      throws InvalidFilterValueException

Given an object, determines if the test(s) represented by this filter are passed. This ability is used to allow queries against both features and and non spatial data (such as record) and to express constraints on permissable data values.

Specified by:

test in interface Predicate<R>

Parameters:

object - the object (often a Feature instance) to evaluate.

Returns:

true if the test(s) are passed for the provided object.

Throws:

NullPointerException - if object is null.

InvalidFilterValueException - if the filter cannot be applied on the given object.