001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.filter;
033
034 import java.util.List;
035 import java.util.Set;
036
037 import org.opengis.filter.capability.ArithmeticOperators;
038 import org.opengis.filter.capability.ComparisonOperators;
039 import org.opengis.filter.capability.FilterCapabilities;
040 import org.opengis.filter.capability.FunctionName;
041 import org.opengis.filter.capability.Functions;
042 import org.opengis.filter.capability.GeometryOperand;
043 import org.opengis.filter.capability.IdCapabilities;
044 import org.opengis.filter.capability.Operator;
045 import org.opengis.filter.capability.ScalarCapabilities;
046 import org.opengis.filter.capability.SpatialCapabilities;
047 import org.opengis.filter.capability.SpatialOperator;
048 import org.opengis.filter.capability.SpatialOperators;
049 import org.opengis.filter.capability.TemporalCapabilities;
050 import org.opengis.filter.capability.TemporalOperand;
051 import org.opengis.filter.capability.TemporalOperators;
052 import org.opengis.filter.expression.Add;
053 import org.opengis.filter.expression.Divide;
054 import org.opengis.filter.expression.Expression;
055 import org.opengis.filter.expression.Function;
056 import org.opengis.filter.expression.Literal;
057 import org.opengis.filter.expression.Multiply;
058 import org.opengis.filter.expression.PropertyName;
059 import org.opengis.filter.expression.Subtract;
060 import org.opengis.filter.identity.FeatureId;
061 import org.opengis.filter.identity.GmlObjectId;
062 import org.opengis.filter.identity.Identifier;
063 import org.opengis.filter.sort.SortBy;
064 import org.opengis.filter.sort.SortOrder;
065 import org.opengis.filter.spatial.BBOX;
066 import org.opengis.filter.spatial.Beyond;
067 import org.opengis.filter.spatial.Contains;
068 import org.opengis.filter.spatial.Crosses;
069 import org.opengis.filter.spatial.DWithin;
070 import org.opengis.filter.spatial.Disjoint;
071 import org.opengis.filter.spatial.Equals;
072 import org.opengis.filter.spatial.Intersects;
073 import org.opengis.filter.spatial.Overlaps;
074 import org.opengis.filter.spatial.Touches;
075 import org.opengis.filter.spatial.Within;
076 import org.opengis.filter.temporal.After;
077 import org.opengis.filter.temporal.AnyInteracts;
078 import org.opengis.filter.temporal.Before;
079 import org.opengis.filter.temporal.Begins;
080 import org.opengis.filter.temporal.BegunBy;
081 import org.opengis.filter.temporal.During;
082 import org.opengis.filter.temporal.EndedBy;
083 import org.opengis.filter.temporal.Ends;
084 import org.opengis.filter.temporal.Meets;
085 import org.opengis.filter.temporal.MetBy;
086 import org.opengis.filter.temporal.OverlappedBy;
087 import org.opengis.filter.temporal.TContains;
088 import org.opengis.filter.temporal.TEquals;
089 import org.opengis.filter.temporal.TOverlaps;
090 import org.opengis.geometry.Geometry;
091
092
093 /**
094 * Interface whose methods allow the caller to create instances of the various
095 * {@link Filter} and {@link Expression} subclasses.
096 * <p>
097 * @version <A HREF="http://www.opengis.org/docs/02-059.pdf">Implementation specification 1.0</A>
098 * @version <A HREF="http://portal.opengeospatial.org/files/?artifact_id=39968">Implementation specification 2.0</A>
099 * @author Chris Dillard (SYS Technologies)
100 * @author Johann Sorel (Geomatys)
101 * @since GeoAPI 2.0
102 */
103 public interface FilterFactory {
104 /**
105 * The FilterCapabilities data structure is used to describe the abilities of
106 * this FilterFactory, it includes restrictions on the available spatial operations,
107 * scalar operations, lists the supported functions, and describes what geometry
108 * literals are understood.
109 * @return FilterCapabilities describing the abilities of this FilterFactory
110 */
111 // FilterCapabilities getCapabilities();
112
113 ////////////////////////////////////////////////////////////////////////////////
114 //
115 // IDENTIFIERS
116 //
117 ////////////////////////////////////////////////////////////////////////////////
118 /** Creates a new feautre id from a string */
119 FeatureId featureId(String id);
120
121 /** Creates a new gml object id from a string */
122 GmlObjectId gmlObjectId(String id);
123
124 ////////////////////////////////////////////////////////////////////////////////
125 //
126 // FILTERS
127 //
128 ////////////////////////////////////////////////////////////////////////////////
129
130 /** {@code AND} filter between two filters. */
131 And and(Filter f, Filter g);
132
133 /** {@code AND} filter between a list of filters. */
134 And and(List<Filter> f);
135
136 /** {@code OR} filter between two filters. */
137 Or or(Filter f, Filter g);
138
139 /** {@code OR} filter between a list of filters. */
140 Or or (List<Filter> f);
141
142 /** Reverses the logical value of a filter. */
143 Not not(Filter f);
144
145 /** Passes only for objects that have one of the IDs given to this object. */
146 Id id(Set<? extends Identifier> ids);
147
148 /** Retrieves the value of a {@linkplain org.opengis.feature.Feature feature}'s property. */
149 PropertyName property(String name);
150
151 /** A compact way of encoding a range check. */
152 PropertyIsBetween between(Expression expr, Expression lower, Expression upper);
153
154 /** Compares that two sub-expressions are equal to each other.
155 * @todo should be equal (so equals can refer to geometry)
156 */
157 PropertyIsEqualTo equals(Expression expr1, Expression expr2);
158
159 /** Compares that two sub-expressions are equal to eacher other */
160 PropertyIsEqualTo equal(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
161
162 /** Checks that the first sub-expression is not equal to the second subexpression. */
163 PropertyIsNotEqualTo notEqual(Expression expr1, Expression expr2 );
164
165 /**
166 * Checks that the first sub-expression is not equal to the second subexpression.
167 *
168 * @param expr1 first expression
169 * @param expr2 second expression
170 * @param matchCase true if the comparison should be case insensitive
171 * @return evaluates to true of expr1 not equal to expr2
172 */
173 PropertyIsNotEqualTo notEqual(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
174
175 /** Checks that the first sub-expression is greater than the second subexpression. */
176 PropertyIsGreaterThan greater(Expression expr1, Expression expr2);
177
178 /**
179 * Checks that the first sub-expression is greater than the second subexpression.
180 *
181 * @param expr1 first expression
182 * @param expr2 second expression
183 * @param matchCase true if the comparison should be case insensitive
184 * @return evaluates to true of expr1 is greater than expr2
185 */
186 PropertyIsGreaterThan greater(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
187
188 /** Checks that the first sub-expression is greater or equal to the second subexpression. */
189 PropertyIsGreaterThanOrEqualTo greaterOrEqual(Expression expr1, Expression expr2);
190
191 /** Checks that the first sub-expression is greater or equal to the second subexpression. */
192 PropertyIsGreaterThanOrEqualTo greaterOrEqual(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
193
194 /** Checks that its first sub-expression is less than its second subexpression. */
195 PropertyIsLessThan less(Expression expr1, Expression expr2);
196
197 PropertyIsLessThan less(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
198
199 /** Checks that its first sub-expression is less than or equal to its second subexpression. */
200 PropertyIsLessThanOrEqualTo lessOrEqual(Expression expr1, Expression expr2);
201
202 PropertyIsLessThanOrEqualTo lessOrEqual(Expression expr1, Expression expr2, boolean matchCase, MatchAction matchAction);
203
204 /** Character string comparison operator with pattern matching and default wildcards. */
205 PropertyIsLike like(Expression expr, String pattern);
206
207 /** Character string comparison operator with pattern matching and specified wildcards. */
208 PropertyIsLike like(Expression expr, String pattern, String wildcard, String singleChar, String escape);
209
210 /** Character string comparison operator with pattern matching and specified wildcards. */
211 PropertyIsLike like(Expression expr, String pattern, String wildcard, String singleChar, String escape, boolean matchCase);
212
213 /** Checks if an expression's value is {@code null}. */
214 PropertyIsNull isNull(Expression expr);
215
216 /** Checks if an expression's value is nil. */
217 PropertyIsNil isNil(Expression expr);
218
219 ////////////////////////////////////////////////////////////////////////////////
220 //
221 // SPATIAL FILTERS
222 //
223 ////////////////////////////////////////////////////////////////////////////////
224
225 /**
226 * Checks if the bounding box of the feature's geometry overlaps the indicated bounds.
227 * <p>
228 * This method is defined in strict accordance with the Filter 1.0 specification, you may
229 * find the FilterFactory2.bbox(Expression, BoundingBox) to be easier to use.
230 * </p>
231 * @param propertyName Name of geometry property (for a PropertyName to access a Feature's Geometry)
232 * @param minx Minimum "x" value (for a literal BoundingBox)
233 * @param miny Minimum "y" value (for a literal BoundingBox)
234 * @param maxx Maximum "x" value (for a literal BoundingBox)
235 * @param maxy Maximum "y" value (for a literal BoundingBox)
236 * @param srs Indicating the CoordianteReferenceSystem to use for a literal BoundingBox
237 */
238 BBOX bbox(String propertyName, double minx, double miny, double maxx, double maxy, String srs);
239
240 /** Check if all of a feature's geometry is more distant than the given distance from this object's geometry. */
241 Beyond beyond(String propertyName, Geometry geometry, double distance, String units);
242
243 /** Checks if the the first geometric operand contains the second. */
244 Contains contains(String propertyName, Geometry geometry);
245
246 /** Checks if the first geometric operand crosses the second. */
247 Crosses crosses(String propertyName, Geometry geometry);
248
249 /** Checks if the first operand is disjoint from the second. */
250 Disjoint disjoint(String propertyName, Geometry geometry);
251
252 /** Checks if any part of the first geometry lies within the given distance of the second geometry. */
253 DWithin dwithin(String propertyName, Geometry geometry, double distance, String units);
254
255 /** Checks if the geometry of the two operands are equal. */
256 Equals equals(String propertyName, Geometry geometry);
257
258 /** Checks if the two geometric operands intersect. */
259 Intersects intersects(String propertyName, Geometry geometry);
260
261 /** Checks if the interior of the first geometry somewhere overlaps the interior of the second geometry. */
262 Overlaps overlaps(String propertyName, Geometry geometry);
263
264 /** Checks if the feature's geometry touches, but does not overlap with the geometry held by this object. */
265 Touches touches(String propertyName, Geometry geometry);
266
267 /** Checks if the feature's geometry is completely contained by the specified constant geometry. */
268 Within within(String propertyName, Geometry geometry);
269
270
271 ////////////////////////////////////////////////////////////////////////////////
272 //
273 // TEMPORAL FILTERS
274 //
275 ////////////////////////////////////////////////////////////////////////////////
276
277 /** Check if first expression is after the second. */
278 After after(Expression expr1, Expression expr2);
279
280 /** Sortcut filter for NOT (Before OR Meets OR MetBy OR After). */
281 AnyInteracts anyInteracts(Expression expr1, Expression expr2);
282
283 /** Check if first expression is before the second. */
284 Before before(Expression expr1, Expression expr2);
285
286 /** Check if first expression begins at the second. */
287 Begins begins(Expression expr1, Expression expr2);
288
289 /** Check if first expression begun by the second. */
290 BegunBy begunBy(Expression expr1, Expression expr2);
291
292 /** Check if first expression is during the second. */
293 During during(Expression expr1, Expression expr2);
294
295 /** Check if first expression ends by the second. */
296 Ends ends(Expression expr1, Expression expr2);
297
298 /** Check if first expression is ended by the second. */
299 EndedBy endedBy(Expression expr1, Expression expr2);
300
301 /** Check if first expression meets the second. */
302 Meets meets(Expression expr1, Expression expr2);
303
304 /** Check if first expression is met by the second. */
305 MetBy metBy(Expression expr1, Expression expr2);
306
307 /** Check if first expression is overlapped by the second. */
308 OverlappedBy overlappedBy(Expression expr1, Expression expr2);
309
310 /** Check if first expression iscontained in the second. */
311 TContains tcontains(Expression expr1, Expression expr2);
312
313 /** Check if first expression equal to the second. */
314 TEquals tequals(Expression expr1, Expression expr2);
315
316 /** Check if first expression overlaps the second. */
317 TOverlaps toverlaps(Expression expr1, Expression expr2);
318
319
320 ////////////////////////////////////////////////////////////////////////////////
321 //
322 // EXPRESSIONS
323 //
324 ////////////////////////////////////////////////////////////////////////////////
325
326 /** Computes the numeric addition of the first and second operand. */
327 Add add(Expression expr1, Expression expr2);
328
329 /** Computes the numeric quotient resulting from dividing the first operand by the second. */
330 Divide divide(Expression expr1, Expression expr2);
331
332 /** Computes the numeric product of their first and second operand. */
333 Multiply multiply(Expression expr1, Expression expr2);
334
335 /** Computes the numeric difference between the first and second operand. */
336 Subtract subtract(Expression expr1, Expression expr2);
337
338 /** Call into some implementation-specific function. */
339 Function function(String name, Expression ... args);
340
341 /** A constant, literal value that can be used in expressions. */
342 Literal literal(Object obj);
343
344 /** A constant, literal {@link Byte} value that can be used in expressions. */
345 Literal literal(byte b);
346
347 /** A constant, literal {@link Short} value that can be used in expressions. */
348 Literal literal(short s);
349
350 /** A constant, literal {@link Integer} value that can be used in expressions. */
351 Literal literal(int i);
352
353 /** A constant, literal {@link Long} value that can be used in expressions. */
354 Literal literal(long l);
355
356 /** A constant, literal {@link Float} value that can be used in expressions. */
357 Literal literal(float f);
358
359 /** A constant, literal {@link Double} value that can be used in expressions. */
360 Literal literal(double d);
361
362 /** A constant, literal {@link Character} value that can be used in expressions. */
363 Literal literal(char c);
364
365 /** A constant, literal {@link Boolean} value that can be used in expressions. */
366 Literal literal(boolean b);
367
368 ////////////////////////////////////////////////////////////////////////////////
369 //
370 // SORT BY
371 //
372 ////////////////////////////////////////////////////////////////////////////// //
373 /** Indicates an property by which contents should be sorted, along with intended order. */
374 SortBy sort(String propertyName, SortOrder order);
375
376 ////////////////////////////////////////////////////////////////////////////////
377 //
378 // CAPABILITIES
379 //
380 ////////////////////////////////////////////////////////////////////////////////
381 /** operators */
382 Operator operator(String name);
383
384 /** spatial operator */
385 SpatialOperator spatialOperator(String name, GeometryOperand[] geometryOperands);
386
387 /** function name */
388 FunctionName functionName(String name, int nargs);
389
390 /** functions */
391 Functions functions(FunctionName[] functionNames);
392
393 /** spatial operators */
394 SpatialOperators spatialOperators(SpatialOperator[] spatialOperators);
395
396 /** comparison operators */
397 ComparisonOperators comparisonOperators(Operator[] comparisonOperators);
398
399 /** arithmetic operators */
400 ArithmeticOperators arithmeticOperators(boolean simple, Functions functions);
401
402 /** scalar capabilities */
403 ScalarCapabilities scalarCapabilities(ComparisonOperators comparison,
404 ArithmeticOperators arithmetic, boolean logical);
405
406 /** spatial capabilities */
407 SpatialCapabilities spatialCapabilities(GeometryOperand[] geometryOperands,
408 SpatialOperators spatial);
409
410 /** temporal capabilities */
411 TemporalCapabilities temporalCapabilities(TemporalOperand[] temporalOperands,
412 TemporalOperators temporal);
413
414 /** id capabilities */
415 IdCapabilities idCapabilities(boolean eid, boolean fid);
416
417 /** filter capabilities */
418 FilterCapabilities capabilities(String version, ScalarCapabilities scalar,
419 SpatialCapabilities spatial, TemporalCapabilities temporal, IdCapabilities id);
420 }