001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-2012 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.expression.Add;
050 import org.opengis.filter.expression.Divide;
051 import org.opengis.filter.expression.Expression;
052 import org.opengis.filter.expression.Function;
053 import org.opengis.filter.expression.Literal;
054 import org.opengis.filter.expression.Multiply;
055 import org.opengis.filter.expression.PropertyName;
056 import org.opengis.filter.expression.Subtract;
057 import org.opengis.filter.identity.FeatureId;
058 import org.opengis.filter.identity.GmlObjectId;
059 import org.opengis.filter.identity.Identifier;
060 import org.opengis.filter.sort.SortBy;
061 import org.opengis.filter.sort.SortOrder;
062 import org.opengis.filter.spatial.BBOX;
063 import org.opengis.filter.spatial.Beyond;
064 import org.opengis.filter.spatial.Contains;
065 import org.opengis.filter.spatial.Crosses;
066 import org.opengis.filter.spatial.DWithin;
067 import org.opengis.filter.spatial.Disjoint;
068 import org.opengis.filter.spatial.Equals;
069 import org.opengis.filter.spatial.Intersects;
070 import org.opengis.filter.spatial.Overlaps;
071 import org.opengis.filter.spatial.Touches;
072 import org.opengis.filter.spatial.Within;
073 import org.opengis.geometry.Geometry;
074
075
076 /**
077 * Interface whose methods allow the caller to create instances of the various
078 * {@link Filter} and {@link Expression} subclasses.
079 * <p>
080 * @version <A HREF="http://www.opengis.org/docs/02-059.pdf">Implementation specification 1.0</A>
081 * @author Chris Dillard (SYS Technologies)
082 * @since GeoAPI 2.0
083 */
084 public interface FilterFactory {
085 /**
086 * The FilterCapabilities data structure is used to describe the abilities of
087 * this FilterFactory, it includes restrictions on the available spatial operations,
088 * scalar operations, lists the supported functions, and describes what geometry
089 * literals are understood.
090 * @return FilterCapabilities describing the abilities of this FilterFactory
091 */
092 // FilterCapabilities getCapabilities();
093
094 ////////////////////////////////////////////////////////////////////////////////
095 //
096 // IDENTIFIERS
097 //
098 ////////////////////////////////////////////////////////////////////////////////
099 /** Creates a new feautre id from a string */
100 FeatureId featureId(String id);
101
102 /** Creates a new gml object id from a string */
103 GmlObjectId gmlObjectId(String id);
104
105 ////////////////////////////////////////////////////////////////////////////////
106 //
107 // FILTERS
108 //
109 ////////////////////////////////////////////////////////////////////////////////
110
111 /** {@code AND} filter between two filters. */
112 And and(Filter f, Filter g);
113
114 /** {@code AND} filter between a list of filters. */
115 And and(List<Filter> f);
116
117 /** {@code OR} filter between two filters. */
118 Or or(Filter f, Filter g);
119
120 /** {@code OR} filter between a list of filters. */
121 Or or (List<Filter> f);
122
123 /** Reverses the logical value of a filter. */
124 Not not(Filter f);
125
126 /** Passes only for objects that have one of the IDs given to this object. */
127 Id id(Set<? extends Identifier> ids);
128
129 /** Retrieves the value of a {@linkplain org.opengis.feature.Feature feature}'s property. */
130 PropertyName property(String name);
131
132 /** A compact way of encoding a range check. */
133 PropertyIsBetween between(Expression expr, Expression lower, Expression upper);
134
135 /** Compares that two sub-expressions are equal to each other.
136 * @todo should be equal (so equals can refer to geometry)
137 */
138 PropertyIsEqualTo equals(Expression expr1, Expression expr2);
139
140 /** Compares that two sub-expressions are equal to eacher other */
141 PropertyIsEqualTo equal(Expression expr1, Expression expr2, boolean matchCase);
142
143 /** Checks that the first sub-expression is not equal to the second subexpression. */
144 PropertyIsNotEqualTo notEqual(Expression expr1, Expression expr2 );
145
146 /**
147 * Checks that the first sub-expression is not equal to the second subexpression.
148 *
149 * @param expr1 first expression
150 * @param expr2 second expression
151 * @param matchCase true if the comparison should be case insensitive
152 * @return evaluates to true of expr1 not equal to expr2
153 */
154 PropertyIsNotEqualTo notEqual(Expression expr1, Expression expr2, boolean matchCase);
155
156 /** Checks that the first sub-expression is greater than the second subexpression. */
157 PropertyIsGreaterThan greater(Expression expr1, Expression expr2);
158
159 /**
160 * Checks that the first sub-expression is greater than the second subexpression.
161 *
162 * @param expr1 first expression
163 * @param expr2 second expression
164 * @param matchCase true if the comparison should be case insensitive
165 * @return evaluates to true of expr1 is greater than expr2
166 */
167 PropertyIsGreaterThan greater(Expression expr1, Expression expr2, boolean matchCase);
168
169 /** Checks that the first sub-expression is greater or equal to the second subexpression. */
170 PropertyIsGreaterThanOrEqualTo greaterOrEqual(Expression expr1, Expression expr2);
171
172 /** Checks that the first sub-expression is greater or equal to the second subexpression. */
173 PropertyIsGreaterThanOrEqualTo greaterOrEqual(Expression expr1, Expression expr2, boolean matchCase);
174
175 /** Checks that its first sub-expression is less than its second subexpression. */
176 PropertyIsLessThan less(Expression expr1, Expression expr2);
177
178 PropertyIsLessThan less(Expression expr1, Expression expr2, boolean matchCase);
179
180 /** Checks that its first sub-expression is less than or equal to its second subexpression. */
181 PropertyIsLessThanOrEqualTo lessOrEqual(Expression expr1, Expression expr2);
182
183 PropertyIsLessThanOrEqualTo lessOrEqual(Expression expr1, Expression expr2, boolean matchCase);
184
185 /** Character string comparison operator with pattern matching and default wildcards. */
186 PropertyIsLike like(Expression expr, String pattern);
187
188 /** Character string comparison operator with pattern matching and specified wildcards. */
189 PropertyIsLike like(Expression expr, String pattern, String wildcard, String singleChar, String escape);
190
191 /** Character string comparison operator with pattern matching and specified wildcards. */
192 PropertyIsLike like(Expression expr, String pattern, String wildcard, String singleChar, String escape, boolean matchCase);
193
194 /** Checks if an expression's value is {@code null}. */
195 PropertyIsNull isNull(Expression expr);
196
197 ////////////////////////////////////////////////////////////////////////////////
198 //
199 // SPATIAL FILTERS
200 //
201 ////////////////////////////////////////////////////////////////////////////////
202
203 /**
204 * Checks if the bounding box of the feature's geometry overlaps the indicated bounds.
205 * <p>
206 * This method is defined in strict accordance with the Filter 1.0 specification, you may
207 * find the FilterFactory2.bbox(Expression, BoundingBox) to be easier to use.
208 * </p>
209 * @param propertyName Name of geometry property (for a PropertyName to access a Feature's Geometry)
210 * @param minx Minimum "x" value (for a literal BoundingBox)
211 * @param miny Minimum "y" value (for a literal BoundingBox)
212 * @param maxx Maximum "x" value (for a literal BoundingBox)
213 * @param maxy Maximum "y" value (for a literal BoundingBox)
214 * @param srs Indicating the CoordianteReferenceSystem to use for a literal BoundingBox
215 */
216 BBOX bbox(String propertyName, double minx, double miny, double maxx, double maxy, String srs);
217
218 /** Check if all of a feature's geometry is more distant than the given distance from this object's geometry. */
219 Beyond beyond(String propertyName, Geometry geometry, double distance, String units);
220
221 /** Checks if the the first geometric operand contains the second. */
222 Contains contains(String propertyName, Geometry geometry);
223
224 /** Checks if the first geometric operand crosses the second. */
225 Crosses crosses(String propertyName, Geometry geometry);
226
227 /** Checks if the first operand is disjoint from the second. */
228 Disjoint disjoint(String propertyName, Geometry geometry);
229
230 /** Checks if any part of the first geometry lies within the given distance of the second geometry. */
231 DWithin dwithin(String propertyName, Geometry geometry, double distance, String units);
232
233 /** Checks if the geometry of the two operands are equal. */
234 Equals equals(String propertyName, Geometry geometry);
235
236 /** Checks if the two geometric operands intersect. */
237 Intersects intersects(String propertyName, Geometry geometry);
238
239 /** Checks if the interior of the first geometry somewhere overlaps the interior of the second geometry. */
240 Overlaps overlaps(String propertyName, Geometry geometry);
241
242 /** Checks if the feature's geometry touches, but does not overlap with the geometry held by this object. */
243 Touches touches(String propertyName, Geometry geometry);
244
245 /** Checks if the feature's geometry is completely contained by the specified constant geometry. */
246 Within within(String propertyName, Geometry geometry);
247
248 ////////////////////////////////////////////////////////////////////////////////
249 //
250 // EXPRESSIONS
251 //
252 ////////////////////////////////////////////////////////////////////////////////
253
254 /** Computes the numeric addition of the first and second operand. */
255 Add add(Expression expr1, Expression expr2);
256
257 /** Computes the numeric quotient resulting from dividing the first operand by the second. */
258 Divide divide(Expression expr1, Expression expr2);
259
260 /** Computes the numeric product of their first and second operand. */
261 Multiply multiply(Expression expr1, Expression expr2);
262
263 /** Computes the numeric difference between the first and second operand. */
264 Subtract subtract(Expression expr1, Expression expr2);
265
266 /** Call into some implementation-specific function. */
267 Function function(String name, Expression ... args);
268
269 /** A constant, literal value that can be used in expressions. */
270 Literal literal(Object obj);
271
272 /** A constant, literal {@link Byte} value that can be used in expressions. */
273 Literal literal(byte b);
274
275 /** A constant, literal {@link Short} value that can be used in expressions. */
276 Literal literal(short s);
277
278 /** A constant, literal {@link Integer} value that can be used in expressions. */
279 Literal literal(int i);
280
281 /** A constant, literal {@link Long} value that can be used in expressions. */
282 Literal literal(long l);
283
284 /** A constant, literal {@link Float} value that can be used in expressions. */
285 Literal literal(float f);
286
287 /** A constant, literal {@link Double} value that can be used in expressions. */
288 Literal literal(double d);
289
290 /** A constant, literal {@link Character} value that can be used in expressions. */
291 Literal literal(char c);
292
293 /** A constant, literal {@link Boolean} value that can be used in expressions. */
294 Literal literal(boolean b);
295
296 ////////////////////////////////////////////////////////////////////////////////
297 //
298 // SORT BY
299 //
300 ////////////////////////////////////////////////////////////////////////////// //
301 /** Indicates an property by which contents should be sorted, along with intended order. */
302 SortBy sort(String propertyName, SortOrder order);
303
304 ////////////////////////////////////////////////////////////////////////////////
305 //
306 // CAPABILITIES
307 //
308 ////////////////////////////////////////////////////////////////////////////////
309 /** operators */
310 Operator operator(String name);
311
312 /** spatial operator */
313 SpatialOperator spatialOperator(String name, GeometryOperand[] geometryOperands);
314
315 /** function name */
316 FunctionName functionName(String name, int nargs);
317
318 /** functions */
319 Functions functions(FunctionName[] functionNames);
320
321 /** spatial operators */
322 SpatialOperators spatialOperators(SpatialOperator[] spatialOperators);
323
324 /** comparison operators */
325 ComparisonOperators comparisonOperators(Operator[] comparisonOperators);
326
327 /** arithmetic operators */
328 ArithmeticOperators arithmeticOperators(boolean simple, Functions functions);
329
330 /** scalar capabilities */
331 ScalarCapabilities scalarCapabilities(ComparisonOperators comparison,
332 ArithmeticOperators arithmetic, boolean logical);
333
334 /** spatial capabilities */
335 SpatialCapabilities spatialCapabilities(GeometryOperand[] geometryOperands,
336 SpatialOperators spatial);
337
338 /** id capabilities */
339 IdCapabilities idCapabilities(boolean eid, boolean fid);
340
341 /** filter capabilities */
342 FilterCapabilities capabilities(String version, ScalarCapabilities scalar,
343 SpatialCapabilities spatial, IdCapabilities id);
344 }