org.geotools.filter
Class Filters

Object
  extended by Filters

public class Filters
extends Object

Utility class for working with Filters & Expression.

To get the full benefit you will need to create an instanceof this Object (supports your own custom FilterFactory!). Additional methods to help create expressions are available.

Example use:


 Filters filters = new Filters( factory );
 filters.duplicate( original );
 
The above example creates a copy of the provided Filter, the factory provided will be used when creating the duplicated content.

Expression

Expressions form an interesting little semi scripting language, intended for queries. A interesting Feature of Filter as a language is that it is not strongly typed. This utility class many helper methods that ease the transition from Strongly typed Java to the more relaxed setting of Expression where most everything can be a string.


 double sum = Filters.number( Object ) + Filters.number( Object );
 
The above example will support the conversion of many things into a format suitable for addition - the complete list is something like: A few things (like Geometry and "ABC") will not be considered addative.

In general the scope of these functions should be similar to that allowed by the XML Atomic Types, aka those that can be seperated by whitespace to form a list.

We do our best to be forgiving, any Java class which takes a String as a constructor can be tried, and toString() assumed to be the inverse. This lets many things (like URL and Date) function without modification.

Since:
GeoTools 2.2
Author:
Jody Garnett (LISAsoft)

Field Summary
static int NOTFOUND
          NOTFOUND indicates int value was unavailable
 
Constructor Summary
Filters()
          Create Filters helper object using global FilterFactory provided by CommonFactoryFinder
Filters(FilterFactory2 factory)
          Create a Filters helper using the provided FilterFactory
 
Method Summary
static void accept(Filter filter, FilterVisitor visitor)
          Deprecated. Please update your code to a org.opengis.filter.FilterVisitor
static Filter and(FilterFactory ff, Filter filter1, Filter filter2)
          Safe version of FilterFactory *and* that is willing to combine filter1 and filter2 correctly in the even either of them is already an And filter.
static double asDouble(Expression expr)
          Obtain the provided Expression as a double.
static int asInt(Expression expr)
          Obtain the provided Expression as an integer.
static String asString(Expression expr)
          Obtain the provided Expression as a String.
static
<T> T
asType(Expression expr, Class<T> TYPE)
          Deprecated. This is not a good idea; use expr.evaulate( null, TYPE )
 Set<String> attributeNames(Filter filter)
          Uses FilterAttributeExtractor to return the list of all mentioned attribute names.
static String[] attributeNames(Filter filter, SimpleFeatureType featureType)
          Traverses the filter and returns any encountered property names.
static ArrayList<Filter> children(Filter filter)
          List of child filters.
static ArrayList<Filter> children(Filter filter, boolean all)
          List of child filters.
 Filter duplicate(Filter filter)
          Deep copy the filter.
static String findPropertyName(Filter filter)
          Given a filter which contains a term which is a PropertyName, returns the name of the property.
static short getFilterType(Filter filter)
          Deprecated. please use instanceof checks
static
<T> T
gets(String text, Class<T> TYPE)
          Used to upcovnert a "Text Value" into the provided TYPE.
static boolean hasChildren(Filter filter)
          Check if the provided filter has child filters of some sort.
static double number(Object value)
          Treat provided value as a Number, used for math opperations.
static Filter or(FilterFactory ff, Filter filter1, Filter filter2)
          Safe version of FilterFactory *or* that is willing to combine filter1 and filter2 correctly in the even either of them is already an Or filter.
static Set<PropertyName> propertyNames(Expression expression)
          Traverses the expression and returns any encountered property names.
static Set<PropertyName> propertyNames(Expression expression, SimpleFeatureType featureType)
          Traverses the expression and returns any encountered property names.
static Set<PropertyName> propertyNames(Filter filter)
          Traverses the filter and returns any encountered property names.
static Set<PropertyName> propertyNames(Filter filter, SimpleFeatureType featureType)
          Traverses the filter and returns any encountered property names.
static String puts(Color color)
          Inverse of eval, used to softly type supported types into Text for use as literals.
static String puts(double number)
          Convert provided number to a suitable text representation Examples: Filters.puts( 3.14 ) => "3.14" Filters.puts( 1.0 ) => "1"
static String puts(Object obj)
          Inverse of eval, used to softly type supported types into Text for use as literals.
 Filter remove(Filter baseFilter, Filter targetFilter)
          Removes the targetFilter from the baseFilter if the baseFilter is a group filter (And or Or),recursing into any sub-logic filters to find the targetFilter if necessary.
 Filter remove(Filter baseFilter, Filter targetFilter, boolean recurse)
          Removes the targetFilter from the baseFilter if the baseFilter is a group filter (And or Or).
static Filter removeFilter(Filter baseFilter, Filter targetFilter)
           
static Filter removeFilter(Filter baseFilter, Filter targetFilter, boolean recurse)
           
static
<T extends Filter>
T
search(Filter filter, Class<T> filterType, String propertyName)
          Find the first child-filter (or the base filter itself) that is of the given type and uses the specified property.
 void setFilterFactory(FilterFactory2 factory)
           
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOTFOUND

public static final int NOTFOUND
NOTFOUND indicates int value was unavailable

See Also:
Constant Field Values
Constructor Detail

Filters

public Filters()
Create Filters helper object using global FilterFactory provided by CommonFactoryFinder


Filters

public Filters(FilterFactory2 factory)
Create a Filters helper using the provided FilterFactory

Method Detail

setFilterFactory

public void setFilterFactory(FilterFactory2 factory)

and

public static Filter and(FilterFactory ff,
                         Filter filter1,
                         Filter filter2)
Safe version of FilterFactory *and* that is willing to combine filter1 and filter2 correctly in the even either of them is already an And filter.

Parameters:
ff -
filter1 -
filter2 -
Returns:
And

or

public static Filter or(FilterFactory ff,
                        Filter filter1,
                        Filter filter2)
Safe version of FilterFactory *or* that is willing to combine filter1 and filter2 correctly in the even either of them is already an Or filter.

Parameters:
ff -
filter1 -
filter2 -
Returns:

accept

public static void accept(Filter filter,
                          FilterVisitor visitor)
Deprecated. Please update your code to a org.opengis.filter.FilterVisitor

Safely visit the provided filter.

This method handles the case of:

Please note that when called with a strict *org.opengis.filter.Filter* this method will fail with a ClassCastException

Parameters:
filter -
visitor -

duplicate

public Filter duplicate(Filter filter)
Deep copy the filter.

Filter objects are mutable, when copying a rich data structure (like SLD) you will need to duplicate the Filters referenced therein.


getFilterType

public static short getFilterType(Filter filter)
Deprecated. please use instanceof checks

Utility method used to transition to geoapi filter.

This utility method is designed to help people port their code quickly, an instanceof check is much preferred.

Example:

 BEFORE: filter.getFilterType() == FilterType.GEOMETRY_CONTAINS
 QUICK:  Filters.getFilterType( filter ) == FilterType.GEOMETRY_CONTAINS
 AFTER: filter instanceof Contains
 

Parameters:
filter -

asInt

public static int asInt(Expression expr)
Obtain the provided Expression as an integer.

This method is quickly used to safely check Literal expressions.

Parameters:
expr -
Returns:
int value of first Number, or NOTFOUND

asString

public static String asString(Expression expr)
Obtain the provided Expression as a String.

This method only reliably works when the Expression is a Literal.

Parameters:
expr -
Returns:
Expression as a String, or null

asDouble

public static double asDouble(Expression expr)
Obtain the provided Expression as a double.

Parameters:
expr -
Returns:
int value of first Number, or Double.NaN

asType

public static <T> T asType(Expression expr,
                           Class<T> TYPE)
Deprecated. This is not a good idea; use expr.evaulate( null, TYPE )

Navigate through the expression searching for something that can be a TYPE.

This will work even with dynamic expression that would normally require a feature. It works especially well when the Expression is a Literal literal (which is usually the case).

If you have a specific Feature, please do this:


 Color value = expr.evaualte( feature, Color.class );
 return value instanceof Color ? (Color) value : null;
 

Parameters:
expr - This only really works for down casting literals to a value
Target - type
Returns:
expr smunched into indicated type

number

public static double number(Object value)
Treat provided value as a Number, used for math opperations.

This function allows for the non stongly typed Math Opperations favoured by the Expression standard.

Able to hanle:

Parameters:
value -
Returns:
double or Double.NaN;
Throws:
IllegalArgumentException - For non numerical among us -- like Geometry

gets

public static <T> T gets(String text,
                         Class<T> TYPE)
              throws Throwable
Used to upcovnert a "Text Value" into the provided TYPE.

Used to tread softly on the Java typing system, because Filter/Expression is not strongly typed. Values in in Expression land are often not the the real Java Objects we wish they were - it is reall a small, lax, query language and Java objects need a but of help getting through.

A couple notes: Remember Strong typing is for whimps who know what they are doing ahead of time. Real programmers let their program learn at runtime... :-)

Parameters:
text -
TYPE -
Throws:
open - set of Throwable reflection for TYPE( String )
Throwable

puts

public static String puts(double number)
Convert provided number to a suitable text representation

Examples:

Parameters:
number -
Returns:
text representation

puts

public static String puts(Object obj)
Inverse of eval, used to softly type supported types into Text for use as literals.

This method has been superseeded by Converters which offers a more general and open ended solution.

Returns:
String representation of provided object

puts

public static String puts(Color color)
Inverse of eval, used to softly type supported types into Text for use as literals.

This method has been superseeded by Converters which offers a more general and open ended solution.

Parameters:
color -
Returns:
String representation of provided color.

remove

public Filter remove(Filter baseFilter,
                     Filter targetFilter)
Removes the targetFilter from the baseFilter if the baseFilter is a group filter (And or Or),recursing into any sub-logic filters to find the targetFilter if necessary.

Parameters:
baseFilter -
targetFilter -
Returns:

removeFilter

public static Filter removeFilter(Filter baseFilter,
                                  Filter targetFilter)

remove

public Filter remove(Filter baseFilter,
                     Filter targetFilter,
                     boolean recurse)
Removes the targetFilter from the baseFilter if the baseFilter is a group filter (And or Or). See removeFilter(org.opengis.filter.Filter, org.opengis.filter.Filter) for details, except this method includes the option to not recurse into child filters.

Parameters:
baseFilter -
targetFilter -
recurse - true if the method should descend into child group filters looking for the target
Returns:

removeFilter

public static Filter removeFilter(Filter baseFilter,
                                  Filter targetFilter,
                                  boolean recurse)

attributeNames

public Set<String> attributeNames(Filter filter)
Uses FilterAttributeExtractor to return the list of all mentioned attribute names.

You can use this method to quickly build up the set of any mentioned attribute names.

Parameters:
filter -
Returns:
Set of propertyNames

attributeNames

public static String[] attributeNames(Filter filter,
                                      SimpleFeatureType featureType)
Traverses the filter and returns any encountered property names.

The feature type is supplied as contexts used to lookup expressions in cases where the attributeName does not match the actual name of the type.


propertyNames

public static Set<PropertyName> propertyNames(Filter filter,
                                              SimpleFeatureType featureType)
Traverses the filter and returns any encountered property names.

The feature type is supplied as contexts used to lookup expressions in cases where the attributeName does not match the actual name of the type.


propertyNames

public static Set<PropertyName> propertyNames(Filter filter)
Traverses the filter and returns any encountered property names.


propertyNames

public static Set<PropertyName> propertyNames(Expression expression,
                                              SimpleFeatureType featureType)
Traverses the expression and returns any encountered property names.

The feature type is supplied as contexts used to lookup expressions in cases where the attributeName does not match the actual name of the type.


propertyNames

public static Set<PropertyName> propertyNames(Expression expression)
Traverses the expression and returns any encountered property names.


hasChildren

public static boolean hasChildren(Filter filter)
Check if the provided filter has child filters of some sort.

Where a child filter is considered:

Any other filter will return false.

Parameters:
filter -
Returns:
list of child filters

children

public static ArrayList<Filter> children(Filter filter)
List of child filters. Where a child filter is considered: Any other filters will return false.

This represents the space covered by a number of the search functions.

The returned list is a mutable copy that can be used with filter factory to construct a new filter when you are ready. To make that explicit I am returning an ArrayList so it is clear that the result can be modified.

Parameters:
filter -
Returns:
are belong to us

children

public static ArrayList<Filter> children(Filter filter,
                                         boolean all)
List of child filters. Where a child filter is considered: Any other filters will return false.

This represents the space covered by a number of the search functions, if *all* is true this function will recursively search for additional child filters beyond those directly avaialble from your filter.

The returned list is a mutable copy that can be used with filter factory to construct a new filter when you are ready. To make that explicit I am returning an ArrayList so it is clear that the result can be modified.

Parameters:
filter -
all - true to recurse into the filter and retrieve all children; false to only return the top level children
Returns:
are belong to us

search

public static <T extends Filter> T search(Filter filter,
                                          Class<T> filterType,
                                          String propertyName)
Find the first child-filter (or the base filter itself) that is of the given type and uses the specified property.

Parameters:
filter -
filterType - - class of the filter to look for
property - - name of the property to look for
Returns:

findPropertyName

public static String findPropertyName(Filter filter)
Given a filter which contains a term which is a PropertyName, returns the name of the property. Returns null if no PropertyName is passed

Parameters:
filter -
Returns:


Copyright © 1996-2014 Geotools. All Rights Reserved.