com.luciad.ogc.filter.evaluator

LuciadLightspeedClass TLcdOGCFilterEvaluator

java.lang.Object

com.luciad.ogc.filter.evaluator.TLcdOGCFilterEvaluator

All Implemented Interfaces:

ILcdOGCFilterEvaluator

Direct Known Subclasses:

TLcdOGCFilterSpatialEvaluator

public class TLcdOGCFilterEvaluator
extends Object
implements ILcdOGCFilterEvaluator

This class allows to convert a TLcdOGCFilter into an ILcdDynamicFilter which can be used to determine whether objects pass the filter or not. It supports all filter expressions, logic operators, comparison operators. It supports all spatial operators when the "Advanced GIS Engine component" is available on the class path. When this component is not available, only the BBOX operator can be evaluated.

Example usage

   List<Object> elementsToEvaluate = ...;
   TLcdOGCFilter ogcFilter = ...;

   TLcdOGCFilterEvaluator evaluator = new TLcdOGCFilterEvaluator();
   TLcdOGCFilterContext filterContext = new TLcdOGCFilterContext();

   ILcdDynamicFilter filter = evaluator.buildFilter(ogcFilter, filterContext);
   for(Object element : elementsToEvaluate){
     if(filter.accept(element)){
       //Do something
     }
   }
 

Arithmetic operations

All arithmetic operations (addition, subtraction, multiplication and division) can operate on Number instances. When not using numbers, the following conversions are done:

• String values containing only numbers will be converted to Long instances: e.g. "123"
• String values containing a decimal separator (".") or using exponential notation (using an "e" or "E") will be converted to Double instances: e.g. "123.45" or "123e3"

The result of the arithmetic operation will be:

• A Long value when both operands are integer numbers (longs or ints) (except for divisions, see below).
• A Double value for all divisions.
• A Double value when at least one operand is not an integer number.
• null when at least one operand is null, or at least one operand cannot be converted to a number.

Binary comparison operations

All the binary comparison operations can operate on

• Number instances
• Comparable instances, including booleans and strings.

Equality checks

This section covers the equality and not equality operators. For those operators, the evaluation will happen in the following order:

• When both arguments are null, they are considered equal. When only one of the arguments is null, the arguments are considered not-equal.
• When one of the arguments is a collection, the collection is considered equal to the other argument if the collection contains a value to the other argument.
• When both arguments can be interpreted as numbers, the numbers are converted to doubles and Double.compareTo(Double) is used.
• When both arguments can be interpreted as booleans, the Boolean.compareTo(java.lang.Boolean) logic is used.
• When both arguments implement the Comparable interface, the Comparable.compareTo(Object) logic is used.

Mathematical comparison checks

This section covers the mathematical operators (greater, greater or equal, less, less or equal). For those operators, the evaluation will happen in the following order:

• When the mathematical comparison check includes an equal check (for example "greater or equal"), an equality check will be done first following the rules described in the "Equality checks" section.
• When any of the arguments is null, null is returned as no comparison can be done.
• When both arguments can be interpreted as numbers, the numbers are converted to doubles and Double.compareTo(Double) is used.
• When both arguments implement the Comparable interface, the Comparable.compareTo(Object) logic is used.

Is between check

This section covers the is between operator which checks whether a value lies between a lower and upper boundary. This check is an inclusive check at the boundaries: lowerBoundary <= value <= upperBoundary. The evaluation will:

• When either the value or any of the boundaries is null, the operator will evaluate to null.
• When the value is a collection, the operator will evaluate to true as soon as one element of the collection lies between the lower and upper boundary.
• The comparison between the value and the bounds follows the rules described in the "Equality checks" and "Mathematical comparison checks" sections above.
• The is between operator also supports dates. This allows to check whether the value is included in a certain time range.

Is like check

This section covers the is like operator which checks whether a string value matches a regular expression. The evaluation will:

• When either the regular expression or the string value to evaluate are null, the operator will evaluate to null.
• When the value is a collection, the operator will evaluate to true as soon as one of the entries in the collection is a match.

Binary logic operations

The evaluation of the AND, OR and NOT operations uses the traditional definitions: AND only evaluates to true when all conditions are true, OR evaluates to true as soon as one condition is true and NOT evaluates to true when the condition is false.

It is possible that one of the conditions evaluates to null. In that case, it is possible that the binary logic operation also evaluates to null. The following list shows the different combinations and their result after evaluation:

• false AND null evaluates to false
• true AND null evaluates to null
• false OR null evaluates to null
• true OR null evaluates to true
• NOT null evaluates to null

Field Summary

Fields

Modifier and Type	Field and Description
static Integer	CONTEXT Deprecated. This constant is no longer used.
static Integer	CURRENT_OBJECT Deprecated. This constant is no longer used.

Constructor Summary

Constructors

Constructor and Description
TLcdOGCFilterEvaluator() Creates a new TLcdOGCFilterEvaluator instance.

Method Summary

Modifier and Type	Method and Description
ILcdDynamicFilter	buildFilter(TLcdOGCFilter aFilter, TLcdOGCFilterContext aContext) Builds an ILcdDynamicFilter instance for a given OGC filter.
ILcdPropertyRetriever	buildPropertyRetriever(ILcdOGCExpression aExpression, TLcdOGCFilterContext aContext) Builds an ILcdPropertyRetriever instance for a given OGC expression.
protected ILcdEvaluatorFactory	createEvaluatorFactory(TLcdOGCFilterContext aContext) Deprecated. In order to add support for custom OGC functions to a TLcdOGCFilterEvaluator, you should create an ILcdEvaluatorFunction and register it either globally (using registerDefaultFunction(TLcdXMLName, ILcdEvaluatorFunction)) or on a specific TLcdOGCFilterEvaluator instance (using registerFunction(TLcdXMLName, ILcdEvaluatorFunction)). Consult the class javadoc of ILcdEvaluatorFunction for more information and example code.
TLcdOGCFilterCapabilities	getFilterCapabilities() Returns the filter capabilities for this evaluator.
static void	registerDefaultFunction(TLcdXMLName aXMLName, ILcdEvaluatorFunction aFunction) Registers a custom function which will be available on all TLcdOGCFilterEvaluator instances which are created in the future.
void	registerFunction(TLcdXMLName aXMLName, ILcdEvaluatorFunction aFunction) Registers a custom function on this evaluator.

Methods inherited from class java.lang.Object

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

Field Detail

CONTEXT

@Deprecated
public static final Integer CONTEXT

Deprecated. This constant is no longer used.

CURRENT_OBJECT

@Deprecated
public static final Integer CURRENT_OBJECT

Deprecated. This constant is no longer used.

Constructor Detail

TLcdOGCFilterEvaluator

public TLcdOGCFilterEvaluator()

Creates a new TLcdOGCFilterEvaluator instance. The instance will already support all custom functions which were registered earlier by calling the registerDefaultFunction(TLcdXMLName, ILcdEvaluatorFunction) method.

Method Detail

registerDefaultFunction

public static void registerDefaultFunction(TLcdXMLName aXMLName,
                                           ILcdEvaluatorFunction aFunction)

Registers a custom function which will be available on all TLcdOGCFilterEvaluator instances which are created in the future. If you want to register a custom function on a single evaluator, use registerFunction(TLcdXMLName, ILcdEvaluatorFunction) instead.

An OGC filter allows to define your own functions (modeled by an TLcdOGCFunction). When such a filter must be evaluated, the evaluator must be able to match the name of that custom function to an ILcdEvaluatorFunction. Calling this method for a custom function will ensure that all future evaluators will support it.

Parameters:

aXMLName - The name of the function. The namespace should be the empty string.

aFunction - The implementation of the function behavior.

Since:

2017.0

buildFilter

public ILcdDynamicFilter buildFilter(TLcdOGCFilter aFilter,
                                     TLcdOGCFilterContext aContext)

Builds an ILcdDynamicFilter instance for a given OGC filter. This ILcdDynamicFilter instance can be invoked for a given object to check whether the given OGC filter accepts it or not.

The returned ILcdFilter instance must be thread-safe.

This implementation calls createEvaluatorFactory to create an evaluator factory that can handle all elements in the TLcdOGCFilter passed.

Specified by:

buildFilter in interface ILcdOGCFilterEvaluator

Parameters:

aFilter - the OGC filter to create an ILcdDynamicFilter for.

aContext - the context in which to create the filter. The context defines amongst others how a property is retrieved from an (OGC) feature and how feature IDs are retrieved.

Returns:

an ILcdDynamicFilter that will only accept those objects that comply to the description as given by the OGC filter passed. The returned filter can throw IllegalArgumentExceptions when called with unsupported objects, or when aFilter does not return a boolean value when evaluated.

Throws:

IllegalArgumentException - When it's impossible to create a filter for aFilter and aContext

createEvaluatorFactory

@Deprecated
protected ILcdEvaluatorFactory createEvaluatorFactory(TLcdOGCFilterContext aContext)

Deprecated. In order to add support for custom OGC functions to a TLcdOGCFilterEvaluator, you should create an ILcdEvaluatorFunction and register it either globally (using registerDefaultFunction(TLcdXMLName, ILcdEvaluatorFunction)) or on a specific TLcdOGCFilterEvaluator instance (using registerFunction(TLcdXMLName, ILcdEvaluatorFunction)). Consult the class javadoc of ILcdEvaluatorFunction for more information and example code.

Creates the evaluator factory that will be used to create evaluators for every expression and condition that can be part of an OGC filter. This method is called from buildFilter.

To support extensions of OGC filters override this method. The recommended way to do this is by creating a factory that filters out and handles the extensions and delegates to the factory created by this implementation for all other elements of an OGC filter.

Note that the buildFilter method will throw an exception when ILcdEvaluatorFactory.canBuildEvaluator(ILcdGenericExpression) returns false for the filter.

Parameters:

aContext - the context in which the filter will be evaluated.

Returns:

an evaluator factory that is capable of handling all types of expressions and conditions that can appear in a TLcdOGCFilter.

buildPropertyRetriever

public ILcdPropertyRetriever buildPropertyRetriever(ILcdOGCExpression aExpression,
                                                    TLcdOGCFilterContext aContext)

Description copied from interface: ILcdOGCFilterEvaluator

Builds an ILcdPropertyRetriever instance for a given OGC expression. This ILcdPropertyRetriever instance can be invoked for a given object to obtain the value of the given OGC filter expression.

Specified by:

buildPropertyRetriever in interface ILcdOGCFilterEvaluator

Parameters:

aExpression - the given OGC expression.

aContext - a filter context.

Returns:

the value of the expression.

registerFunction

public void registerFunction(TLcdXMLName aXMLName,
                             ILcdEvaluatorFunction aFunction)

Registers a custom function on this evaluator. The custom function will only be available on this instance. Use registerDefaultFunction(TLcdXMLName, ILcdEvaluatorFunction) for functions which should be available on all evaluators.

An OGC filter allows to define your own functions (modeled by an TLcdOGCFunction). When such a filter must be evaluated, the evaluator must be able to match the name of that custom function to an ILcdEvaluatorFunction. This is done by calling this method for each of the custom functions the evaluator must support.

Parameters:

aXMLName - The name of the function. The namespace should be the empty string.

aFunction - The implementation of the function behavior.

See Also:

registerDefaultFunction(TLcdXMLName, ILcdEvaluatorFunction)

getFilterCapabilities

public TLcdOGCFilterCapabilities getFilterCapabilities()

Description copied from interface: ILcdOGCFilterEvaluator

Returns the filter capabilities for this evaluator.

Specified by:

getFilterCapabilities in interface ILcdOGCFilterEvaluator

Returns:

the filter capabilities for this evaluator.