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.

Expressions return a value of type <V>. Expressions that can be used as Filter operators and can thus be combined using logical operations 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<? super R,?>>
    getParameters()
    Returns the list sub-expressions that will be evaluated to provide the parameters to the function.
    <N> Expression<R,N>
    toValueType(Class<N> target)
    Returns an expression doing the same evaluation than this method, but returning results as values of the specified type.

    Methods inherited from interface 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
      invalid @linkplain 
      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.

    • getParameters

      @UML(identifier="Function.expression", obligation=MANDATORY, specification=ISO_19143) List<Expression<? super 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 than 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.