001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.filter;
017:
018: import com.vividsolutions.jts.geom.Envelope;
019: import org.opengis.filter.expression.Expression;
020: import org.opengis.filter.spatial.BBOX;
021: import org.opengis.filter.spatial.Beyond;
022: import org.opengis.filter.spatial.Contains;
023: import org.opengis.filter.spatial.Crosses;
024: import org.opengis.filter.spatial.DWithin;
025: import org.opengis.filter.spatial.Disjoint;
026: import org.opengis.filter.spatial.Equals;
027: import org.opengis.filter.spatial.Intersects;
028: import org.opengis.filter.spatial.Overlaps;
029: import org.opengis.filter.spatial.Touches;
030: import org.opengis.filter.spatial.Within;
031: import org.geotools.factory.Factory;
032: import org.geotools.feature.AttributeType;
033: import org.geotools.feature.FeatureType;
034:
035: /**
036: * This specifies the interface to create filters.
037: *
038: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/filter/FilterFactory.java $
039: * @version $Id: FilterFactory.java 25933 2007-06-19 21:37:21Z chorner $
040: *
041: * @task TODO: This needs to be massively overhauled. This should be the
042: * source of immutability of filters. See {@link FeatureTypeFactory},
043: * as that provides a good example of what this should look like. The
044: * mutable factory to create immutable objects is a good model for this.
045: * The creation methods should only create fully formed filters. This
046: * in turn means that all the set functions in the filters should be
047: * eliminated. When rewriting this class/package, keep in mind
048: * FilterSAXParser in the filter module, as the factory should fit
049: * cleanly with that, and should handle sax parsing without too much
050: * memory overhead.
051: * @task REVISIT: resolve errors, should all throw errors?
052: *
053: * @deprecated use {@link org.opengis.filter.FilterFactory}
054: */
055: public interface FilterFactory extends Factory,
056: org.opengis.filter.FilterFactory2 {
057: /**
058: * Creates a logic filter from two filters and a type.
059: *
060: * @param filter1 the first filter to join.
061: * @param filter2 the second filter to join.
062: * @param filterType must be a logic type.
063: *
064: * @return the newly constructed logic filter.
065: *
066: * @throws IllegalFilterException If there were any problems creating the
067: * filter, including wrong type.
068: * @deprecated use one of {@link org.opengis.filter.FilterFactory#and(Filter, Filter)}
069: * {@link org.opengis.filter.FilterFactory#or(Filter, Filter)}
070: * {@link org.opengis.filter.FilterFactory#not(Filter)}
071: */
072: public LogicFilter createLogicFilter(Filter filter1,
073: Filter filter2, short filterType)
074: throws IllegalFilterException;
075:
076: /**
077: * Creates an empty logic filter from a type.
078: *
079: * @param filterType must be a logic type.
080: *
081: * @return the newly constructed logic filter.
082: *
083: * @throws IllegalFilterException If there were any problems creating the
084: * filter, including wrong type.
085: *
086: * @deprecated use one of {@link org.opengis.filter.FilterFactory#and(Filter, Filter)}
087: * {@link org.opengis.filter.FilterFactory#or(Filter, Filter)}
088: * {@link org.opengis.filter.FilterFactory#not(Filter)}
089: */
090: public LogicFilter createLogicFilter(short filterType)
091: throws IllegalFilterException;
092:
093: /**
094: * Creates a logic filter with an initial filter..
095: *
096: * @param filter the initial filter to set.
097: * @param filterType Must be a logic type.
098: *
099: * @return the newly constructed logic filter.
100: *
101: * @throws IllegalFilterException If there were any problems creating the
102: * filter, including wrong type.
103: * @deprecated use one of {@link org.opengis.filter.FilterFactory#and(Filter, Filter)}
104: * {@link org.opengis.filter.FilterFactory#or(Filter, Filter)}
105: * {@link org.opengis.filter.FilterFactory#not(Filter)}
106: */
107: public LogicFilter createLogicFilter(Filter filter, short filterType)
108: throws IllegalFilterException;
109:
110: /**
111: * Creates a literal geometry expression from an envelope.
112: *
113: * @param env the envelope to use for this bounding box.
114: *
115: * @return The newly created BBoxExpression.
116: * @deprecated Please use filterFactory.literal( JTS.toGeometry( bounds ) )
117: * @throws IllegalFilterException if there were creation problems.
118: */
119: public BBoxExpression createBBoxExpression(Envelope env)
120: throws IllegalFilterException;
121:
122: /**
123: * Creates an Integer Literal Expression.
124: *
125: * @param i the int to serve as literal.
126: *
127: * @return The new Literal Expression
128: */
129: public LiteralExpression createLiteralExpression(int i);
130:
131: /**
132: * Creates a Math Expression
133: *
134: * @return The new Math Expression
135: *
136: * @throws IllegalFilterException if there were creation problems.
137: *
138: * @deprecated use one of
139: * {@link org.opengis.filter.FilterFactory#add(Expression, Expression)}
140: * {@link org.opengis.filter.FilterFactory#subtract(Expression, Expression)}
141: * {@link org.opengis.filter.FilterFactory#multiply(Expression, Expression)}
142: * {@link org.opengis.filter.FilterFactory#divide(Expression, Expression)}
143: */
144: public MathExpression createMathExpression()
145: throws IllegalFilterException;
146:
147: /**
148: * Creates a new Fid Filter with no initial fids.
149: *
150: * @return The new Fid Filter.
151: */
152: public FidFilter createFidFilter();
153:
154: /**
155: * Creates an AttributeExpression using the supplied xpath.
156: *
157: * <p>
158: * The supplied xpath can be used to query a varity of content - most
159: * notably Features.
160: * </p>
161: *
162: * @param xpath XPath used to retrive value
163: *
164: * @return The new Attribtue Expression
165: */
166: public AttributeExpression createAttributeExpression(String xpath);
167:
168: /**
169: * Creates a Attribute Expression given a schema and attribute path.
170: *
171: * <p>
172: * If you supply a schema, it will be used as a sanitch check for the
173: * provided path.
174: * </p>
175: *
176: * @param schema the schema to get the attribute from, or null
177: * @param xpath the xPath of the attribute to compare.
178: *
179: * @return The new Attribute Expression.
180: *
181: * @throws IllegalFilterException if there were creation problems.
182: *
183: * @deprecated use createAttributeExpression( xpath ), will be removed for
184: * GeoTools 2.3
185: */
186: public AttributeExpression createAttributeExpression(
187: FeatureType schema, String xpath)
188: throws IllegalFilterException;
189:
190: /**
191: * Shortcut the process - will only grab values matching AttributeType.
192: *
193: * @param at
194: *
195: * @return The new Attribtue Expression
196: *
197: * @throws IllegalFilterException if there were creation problems
198: *
199: * @deprecated use createAttributeExpression( at ), will be removed for
200: * GeoTools 2.3
201: */
202: public AttributeExpression createAttributeExpression(
203: AttributeType at) throws IllegalFilterException;
204:
205: /**
206: * Creates a Literal Expression from an Object.
207: *
208: * @param o the object to serve as the literal.
209: *
210: * @return The new Literal Expression
211: *
212: * @throws IllegalFilterException if there were creation problems.
213: */
214: public LiteralExpression createLiteralExpression(Object o)
215: throws IllegalFilterException;
216:
217: /**
218: * Creates a new compare filter of the given type.
219: *
220: * @param type the type of comparison - must be a compare type.
221: *
222: * @return The new compare filter.
223: *
224: * @throws IllegalFilterException if there were creation problems.
225: *
226: * @deprecated use one of {@link org.opengis.filter.FilterFactory#less(Expression, Expression)}
227: * {@link org.opengis.filter.FilterFactory#lessOrEqual(Expression, Expression)}
228: * {@link org.opengis.filter.FilterFactory#equals(Expression, Expression)}
229: * {@link org.opengis.filter.FilterFactory#greater(Expression, Expression)}
230: * {@link org.opengis.filter.FilterFactory#greaterOrEqual(Expression, Expression)}
231: * {@link org.opengis.filter.FilterFactory#between(Expression, Expression, Expression)}
232: */
233: public CompareFilter createCompareFilter(short type)
234: throws IllegalFilterException;
235:
236: /**
237: * Creates an empty Literal Expression
238: *
239: * @return The new Literal Expression.
240: */
241: public LiteralExpression createLiteralExpression();
242:
243: /**
244: * Creates a String Literal Expression
245: *
246: * @param s the string to serve as the literal.
247: *
248: * @return The new Literal Expression
249: */
250: public LiteralExpression createLiteralExpression(String s);
251:
252: /**
253: * Creates a Double Literal Expression
254: *
255: * @param d the double to serve as the literal.
256: *
257: * @return The new Literal Expression
258: */
259: public LiteralExpression createLiteralExpression(double d);
260:
261: /**
262: * Creates a Attribute Expression with an initial schema.
263: *
264: * @param schema the schema to create with.
265: *
266: * @return The new Attribute Expression.
267: * @deprecated use {@link #createAttributeExpression(String)} instead.
268: */
269: public AttributeExpression createAttributeExpression(
270: FeatureType schema);
271:
272: /**
273: * Creates a Math Expression of the given type.
274: *
275: * @param expressionType must be a math expression type.
276: *
277: * @return The new Math Expression.
278: *
279: * @throws IllegalFilterException if there were creation problems.
280: *
281: * @deprecated use one of
282: * {@link org.opengis.filter.FilterFactory#add(Expression, Expression)}
283: * {@link org.opengis.filter.FilterFactory#subtract(Expression, Expression)}
284: * {@link org.opengis.filter.FilterFactory#multiply(Expression, Expression)}
285: * {@link org.opengis.filter.FilterFactory#divide(Expression, Expression)}
286: */
287: public MathExpression createMathExpression(short expressionType)
288: throws IllegalFilterException;
289:
290: /**
291: * Creates an empty Null Filter.
292: *
293: * @return The new Null Filter.
294: */
295: public NullFilter createNullFilter();
296:
297: /**
298: * Creates an empty Between Filter.
299: *
300: * @return The new Between Filter.
301: *
302: * @throws IllegalFilterException if there were creation problems.
303: */
304: public BetweenFilter createBetweenFilter()
305: throws IllegalFilterException;
306:
307: /**
308: * Creates a Geometry Filter.
309: *
310: * @param filterType the type to create, must be a geometry type.
311: *
312: * @return The new Geometry Filter.
313: *
314: * @throws IllegalFilterException if the filterType is not a geometry.
315: *
316: * @deprecated use one of
317: * {@link org.opengis.filter.FilterFactory#bbox(String, double, double, double, double, String)}
318: * {@link org.opengis.filter.FilterFactory#beyond(String, Geometry, double, String)}
319: * {@link org.opengis.filter.FilterFactory#contains(String, Geometry)}
320: * {@link org.opengis.filter.FilterFactory#crosses(String, Geometry)}
321: * {@link org.opengis.filter.FilterFactory#disjoint(String, Geometry)}
322: * {@link org.opengis.filter.FilterFactory#dwithin(String, Geometry, double, String)}
323: * {@link org.opengis.filter.FilterFactory#equals(String, Geometry)}
324: * {@link org.opengis.filter.FilterFactory#intersects(String, Geometry)}
325: * {@link org.opengis.filter.FilterFactory#overlaps(String, Geometry)}
326: * {@link org.opengis.filter.FilterFactory#touches(String, Geometry)}
327: * {@link org.opengis.filter.FilterFactory#within(String, Geometry)}
328: */
329: public GeometryFilter createGeometryFilter(short filterType)
330: throws IllegalFilterException;
331:
332: /**
333: * Creates a Geometry Distance Filter
334: *
335: * @param filterType the type to create, must be beyond or dwithin.
336: *
337: * @return The new Expression
338: *
339: * @throws IllegalFilterException if the filterType is not a geometry
340: * distance type.
341: *
342: * @deprecated use one of
343: * {@link org.opengis.filter.FilterFactory#beyond(String, Geometry, double, String)}
344: * {@link org.opengis.filter.FilterFactory#dwithin(String, Geometry, double, String)}
345: *
346: */
347: public GeometryDistanceFilter createGeometryDistanceFilter(
348: short filterType) throws IllegalFilterException;
349:
350: /**
351: * Creates a Fid Filter with an initial fid.
352: *
353: * @param fid the feature ID to create with.
354: *
355: * @return The new FidFilter.
356: */
357: public FidFilter createFidFilter(String fid);
358:
359: /**
360: * Creates a Like Filter.
361: *
362: * @return The new Like Filter.
363: */
364: public LikeFilter createLikeFilter();
365:
366: /**
367: * Creates a Function Expression.
368: *
369: * @param name the function name.
370: *
371: * @return The new Function Expression.
372: */
373: public FunctionExpression createFunctionExpression(String name);
374:
375: /**
376: * Creates an Environment Variable
377: *
378: * @param name the function name.
379: *
380: * @return The new Function Expression.
381: */
382: public EnvironmentVariable createEnvironmentVariable(String name);
383:
384: /**
385: * @deprecated use {@link org.opengis.filter.FilterFactory#or(org.opengis.filter.Filter, org.opengis.filter.Filter)}
386: */
387: public Filter or(Filter f1, Filter f2);
388:
389: /**
390: * @deprecated use {@link org.opengis.filter.FilterFactory#and(org.opengis.filter.Filter, org.opengis.filter.Filter)}
391: */
392: public Filter and(Filter f1, Filter f2);
393:
394: /**
395: * @deprecated use {@link org.opengis.filter.FilterFactory#not(org.opengis.filter.Filter)}
396: */
397: public Filter not(Filter f);
398:
399: ////////////////////////////////////////////////////////////////////////////////
400: //
401: // SPATIAL FILTERS
402: //
403: ////////////////////////////////////////////////////////////////////////////////
404:
405: /** Checks if the geometry expression overlaps the specified bounding box. */
406: BBOX bbox(Expression geometry, double minx, double miny,
407: double maxx, double maxy, String srs);
408:
409: /** Check if all of a geometry is more distant than the given distance from this object's geometry. */
410: Beyond beyond(Expression geometry1, Expression geometry2,
411: double distance, String units);
412:
413: /** Checks if the the first geometric operand contains the second. */
414: Contains contains(Expression geometry1, Expression geometry2);
415:
416: /** Checks if the first geometric operand crosses the second. */
417: Crosses crosses(Expression geometry1, Expression geometry2);
418:
419: /** Checks if the first operand is disjoint from the second. */
420: Disjoint disjoint(Expression geometry1, Expression geometry2);
421:
422: /** Checks if any part of the first geometry lies within the given distance of the second geometry. */
423: DWithin dwithin(Expression geometry1, Expression geometry2,
424: double distance, String units);
425:
426: /** Checks if the geometry of the two operands are equal.
427: * @todo should be equals, resolve conflict with PropertyIsEqualTo equals( Expression, Expression )
428: */
429: Equals equal(Expression geometry1, Expression geometry2);
430:
431: /** Checks if the two geometric operands intersect. */
432: Intersects intersects(Expression geometry1, Expression geometry2);
433:
434: /** Checks if the interior of the first geometry somewhere overlaps the interior of the second geometry. */
435: Overlaps overlaps(Expression geometry1, Expression geometry2);
436:
437: /** Checks if the feature's geometry touches, but does not overlap with the geometry held by this object. */
438: Touches touches(Expression propertyName1, Expression geometry2);
439:
440: /** Checks if the feature's geometry is completely contained by the specified constant geometry. */
441: Within within(Expression geometry1, Expression geometry2);
442: }
|