Module org.opengis.geoapi

Package org.opengis.filter

Interface Expression<R,V>

Type Parameters:

R - the type of resources (e.g. Feature) used as inputs.

V - the type of values computed by the expression.

All Superinterfaces:

Function<R,V>

All Known Subinterfaces:

Literal<R,V>, ValueReference<R,V>

@Classifier(ABSTRACT)
@UML(identifier="Expression",
     specification=ISO_19143)
public interface Expression<R,V>
extends Function<R,V>

A literal or a named procedure that performs a distinct computation. An expression can accept zero or more arguments as input and generates a single result. The arguments themselves are in-turn expressions and shall appear in the order in which they are defined in the FilterCapabilities.

Expressions are applied on objects of type <R>. Those objects are typically Feature instances, but expressions can also be used with other kind of objects such as coverage's geometry-value pairs. The value of <? super R> can be obtained at runtime by a call to getResourceClass().

Expressions return a value of type <V>. Expressions that can be used as Filter operators shall return a Boolean result.

Expressions can be implementation-specific functions. Each execution environment should provide a list of supported functions (and the number of arguments they expect) in their FilterCapabilities.

Since:

3.1

Method Summary

Modifier and Type	Method	Description
V	apply(R input)	Evaluates the expression value based on the content of the given object.
ScopedName	getFunctionName()	Returns the name of the function to be called.
List<Expression<R,?>>	getParameters()	Returns the list sub-expressions that will be evaluated to provide the parameters to the function.
Class<? super R>	getResourceClass()	Returns the class of resources expected by this expression.
<N> Expression<R,N>	toValueType(Class<N> target)	Returns an expression doing the same evaluation as this method, but returning results as values of the specified type.

Methods inherited from interface java.util.function.Function

andThen, compose

Method Details

getFunctionName

@UML(identifier="Function.name",
     obligation=MANDATORY,
     specification=ISO_19143)
ScopedName getFunctionName()

Returns the name of the function to be called. The head should identify the defining authority and the tail should identify the function.

Examples: This might be "foo:cos" or "foo:atan2" where "foo" is the name or abbreviation of the specification or software defining the function.

The name can be used to look up the number of required parameters in a FilterCapabilities. For the specific meaning of the required parameters, see implementation documentation.

Returns:

name of the function to be called.

getResourceClass

Class<? super R> getResourceClass()

Returns the class of resources expected by this expression. 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 Literal may put no restriction on the resource type because it ignores the given resource.

Implementation note

For some expressions like ValueReference, the resource class may be an implementation-dependent hard-coded value. For other expressions, the return value should be assignable to all resource classes expected by the parameters. 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 expression.

See Also:

• Filter.getResourceClass()

getParameters

@UML(identifier="Function.expression",
     obligation=MANDATORY,
     specification=ISO_19143)
List<Expression<R,?>> getParameters()

Returns the list sub-expressions that will be evaluated to provide the parameters to the function.

Returns:

the sub-expressions to be evaluated, or an empty list if none.

apply

V apply(R input)
 throws InvalidFilterValueException

Evaluates the expression value based on the content of the given object.

Specified by:

apply in interface Function<R,V>

Parameters:

input - the object to be evaluated by the expression. Can be null if this expression allows null values.

Returns:

value computed by the expression.

Throws:

NullPointerException - if input is null and this expression requires non-null values.

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

toValueType

<N> Expression<R,N> toValueType(Class<N> target)

Returns an expression doing the same evaluation as this method, but returning results as values of the specified type. This method can return this if this expression is already guaranteed to provide results of the specified type. Otherwise this method can either (at implementer choice) return a new expression which will convert values on-the-fly, or throw a ClassCastException. Exceptions should be thrown as early as possible (see below for more details).

Use case

This method is useful when a client needs to narrow the type of values provided by an expression. For example, a method doing spatial operations may accept only expressions returning geometry objects. A call to expression.toValueType(Geometry.class) gives a chance to detect early if an expression is not suitable to spatial operations.

Exceptions

An ClassCastException should be thrown at this method invocation time if values are known to be unconvertible to the specified type. But if convertibility can only be determined at apply(R) invocation time, then a ClassCastException can be thrown at evaluation time. In this paragraph, "convertible" does not necessarily mean that implementations must be able to copy values into objects of specified type. It is okay to apply only standard Java casts.

Type Parameters:

N - compile-time value of target type.

Parameters:

target - desired type of expression results.

Returns:

expression doing the same operation this this expression but with results of the specified type.

Throws:

ClassCastException - if the specified type is not a target type supported by implementation.