A Filter is a generic way to get features that satisfy certain criteria. In general, a Filter object takes a Feature and reports whether the Feature is contained in it (that is, it satisfies the Filter condition) or not.
An individual Filter can report whether a Feature is contained, but this is much more useful when combined with Data Access . To get data in GeoTools, one passes a Query to a FeatureSource. A Filter can be included in the Query to limit the features returned to only those that meet the coniditions of the Filter.
GeoTools does a number of smart things with a Filter passed in, so that all data formats support all Filters. If the format is a database that can transform the Filter into a SQL "where" clause then it will. If it is a spatial database it will turn spatial filters into the equivalent operations. If the format does not support the Filter operation than it will be performed in GeoTools with Java code.
GeoTools will even split up logic filters into their constituent 'supported' and 'unsupported' compenents, passing as much as possible in the native backend datastore, defaulting to java when not possible. The WFS DataStore goes even further, as different WFS implementations support different Filter sets, so it dynamically figures out how much of the filter to have the WFS perform, and how much to do in Java. For example a 'Contains' filter will be passed as an XML filter to GeoServer, but not to MapServer - but using the Filter in your GeoTools code will have the exact same effect. So the short story is, use a Filter to constrain your data, and just let GeoTools do the work.
As you can see from the following class diagram, there are quite a few Filter subinterfaces that can perform tests both on the Feature attributes and geometry. For example, the CompareFilter, LikeFilter and LogicFilter can be used together to create an equivalent of the "where" clause of an SQL statement, whilst the GeometryFilter can check any kind of topological relation with a given reference geometry by leveraging the JTS capabilities, or native operations of a spatial database. The FIDFilter, on the other hand, will check for FID equality or containment in a set of values, just like a constraint on the primary key of a feature.
Again, you will use a FilterFactory to create actual instances of those filters.
Examples of use (from the Snippets section).
How to use a Compare FilterHere's the source code needed to create a filter that will, using GeoTools,
find only show cities with a population greater than 100,000, in a shapefile
. In this example we will use the citiesx020.shp file from the National Atlas (www.nationalatlas.gov).
From Keith Knudsen on the gt2-users lists 18-8-04
Using a bounding box Filter
This page is out of date - please see:
Given an area of interest stored as an envelope the following code will limit the features returned to those which are not wholy outside the bounding box.
Of course you may still wonder where "road" comes from - that is the name of the geometry attribute.
This code fetches the default geometry for a typeName.
Note that this may or may not still lead to the datastore reading all of the filters in, for example a shapefile reader will still need to examine all the features to determine which to return. However an SQL based datastore will convert the filter into part of the SQL query which will be much faster.
Between Filter ExampleThis shows how to create a Between Filter in code. It asks for all features with values between 5 and 15. This could also be done with a logic filter and PropertyIsGreaterThanOrEqualTo and PropertyIsLessThanOrEqualTo filters.
Create a Filter from XMLSay we have a bit of XML for a filter that we want to parse and get a Filter. First, we need a FilterHandler to receive the Filter from the parser. If we don't need to do anything else at that point, something like the following is sufficient:
Then, given an InputSource for the XML, our parse code would look like: