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 org.opengis.filter.spatial.BinarySpatialOperator;
019: import org.geotools.feature.Feature;
020:
021: /**
022: * Implements a geometry filter.
023: *
024: * <p>
025: * This filter implements a relationship - of some sort - between two geometry
026: * expressions. Note that this comparison does not attempt to restict its
027: * expressions to be meaningful. This means that it considers itself a valid
028: * filter as long as it contains two <b>geometry</b> sub-expressions. It is
029: * also slightly less restrictive than the OGC Filter specification because
030: * it does not require that one sub-expression be an geometry attribute and
031: * the other be a geometry literal.
032: * </p>
033: *
034: * <p>
035: * In other words, you may use this filter to compare two geometries in the
036: * same feature, such as: attributeA inside attributeB? You may also compare
037: * two literal geometries, although this is fairly meaningless, since it could
038: * be reduced (ie. it is always either true or false). This approach is very
039: * similar to that taken in the FilterCompare class.
040: * </p>
041: *
042: * @author Rob Hranac, TOPP
043: * @author Chris Holmes, TOPP
044: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/filter/GeometryFilter.java $
045: * @version $Id: GeometryFilter.java 22294 2006-10-20 00:55:40Z desruisseaux $
046: *
047: * @todo REVISIT: make this class (and all filters) immutable, implement
048: * cloneable and return new filters when calling addLeftGeometry and
049: * addRightG Issues to think through: would be cleaner immutability to
050: * have constructor called with left and right Geometries, but this does
051: * not jive with SAX parsing, which is one of the biggest uses of
052: * filters. But the alternative is not incredibly efficient either, as
053: * there will be two filters that are just thrown away every time we
054: * make a full geometry filter. These issues extend to most filters, as
055: * just about all of them are mutable when creating them. Other issue
056: * is that lots of code will need to be changed for immutability.
057: * (comments by cholmes) - MUTABLE FACTORIES! Sax and immutability.
058: *
059: * @deprecated use {@link org.opengis.filter.spatial.BinarySpatialOperator}.
060: */
061: public interface GeometryFilter extends Filter, BinarySpatialOperator {
062: /**
063: * Adds the 'right' value to this filter.
064: *
065: * @param rightGeometry Expression for 'right' value.
066: *
067: * @throws IllegalFilterException Filter is not internally consistent.
068: *
069: * @deprecated use {@link BinarySpatialOperator#setExpression2(Expression)}
070: */
071: void addRightGeometry(Expression rightGeometry)
072: throws IllegalFilterException;
073:
074: /**
075: * Adds the 'left' value to this filter.
076: *
077: * @param leftGeometry Expression for 'left' value.
078: *
079: * @throws IllegalFilterException Filter is not internally consistent.
080: *
081: * @task REVISIT: make all filters immutable.
082: *
083: * @deprecated use {@link BinarySpatialOperator#setExpression1(Expression)}
084: */
085: void addLeftGeometry(Expression leftGeometry)
086: throws IllegalFilterException;
087:
088: /**
089: * Determines whether the given feature's geometry passes the geometric
090: * relationship of this filter.
091: *
092: * @param feature the feature to inspect.
093: *
094: * @return whether the feature meets the conditions of filtering imposed by
095: * this geometry filter.
096: */
097: boolean contains(Feature feature);
098:
099: /**
100: * Retrieves the expression on the right side of the spatial comparison.
101: *
102: * @return the geometry expression on the right.
103: *
104: * @deprecated use {@link BinarySpatialOperator#getExpression2()}.
105: */
106: Expression getRightGeometry();
107:
108: /**
109: * Retrieves the expression on the left side of the spatial comparison.
110: *
111: * @return the geometry expression on the left.
112: *
113: * @deprecated use {@link BinarySpatialOperator#getExpression1()}.
114: */
115: Expression getLeftGeometry();
116: }
|