/*
 *    GeoTools - OpenSource mapping toolkit
 *    http://geotools.org
 *    (C) 2002-2006, GeoTools Project Managment Committee (PMC)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.filter;

import org.opengis.filter.spatial.BinarySpatialOperator;
import org.geotools.feature.Feature;


/**
 * Implements a geometry filter.
 *
 * <p>
 * This filter implements a relationship - of some sort -  between two geometry
 * expressions. Note that this comparison does not attempt to restict its
 * expressions to be meaningful.  This means that it considers itself a valid
 * filter as long as it contains two <b>geometry</b> sub-expressions. It is
 * also slightly less  restrictive than the OGC Filter specification because
 * it does not require that one sub-expression be an geometry attribute and
 * the other be a geometry literal.
 * </p>
 *
 * <p>
 * In other words, you may use this filter to compare two geometries in the
 * same feature, such as: attributeA inside attributeB?  You may also compare
 * two literal geometries, although this is fairly meaningless, since it could
 * be reduced (ie. it is always either true or false).  This approach is very
 * similar to that taken in the FilterCompare class.
 * </p>
 *
 * @author Rob Hranac, TOPP
 * @author Chris Holmes, TOPP
 * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/filter/GeometryFilter.java $
 * @version $Id: GeometryFilter.java 22294 2006-10-20 00:55:40Z desruisseaux $
 *
 * @todo REVISIT: make this class (and all filters) immutable, implement
 *       cloneable and return new filters when calling addLeftGeometry and
 *       addRightG Issues to think through: would be cleaner immutability to
 *       have constructor called with left and right Geometries, but this does
 *       not jive with SAX parsing, which is one of the biggest uses of
 *       filters.  But the alternative is not incredibly efficient either, as
 *       there will be two filters that  are just thrown away every time we
 *       make a full geometry filter.  These issues extend to most filters, as
 *       just about all of them are mutable when creating them.  Other issue
 *       is that lots of code will need to  be changed for immutability.
 *       (comments by cholmes) - MUTABLE FACTORIES!  Sax and immutability.
 *
 *  @deprecated use {@link org.opengis.filter.spatial.BinarySpatialOperator}.
 */
public interface GeometryFilter extends Filter, BinarySpatialOperator {
    /**
     * Adds the 'right' value to this filter.
     *
     * @param rightGeometry Expression for 'right' value.
     *
     * @throws IllegalFilterException Filter is not internally consistent.
     *
     * @deprecated use {@link BinarySpatialOperator#setExpression2(Expression)}
     */
    void addRightGeometry(Expression rightGeometry) throws IllegalFilterException;

    /**
     * Adds the 'left' value to this filter.
     *
     * @param leftGeometry Expression for 'left' value.
     *
     * @throws IllegalFilterException Filter is not internally consistent.
     *
     * @task REVISIT: make all filters immutable.
     *
     * @deprecated use {@link BinarySpatialOperator#setExpression1(Expression)}
     */
    void addLeftGeometry(Expression leftGeometry) throws IllegalFilterException;

    /**
     * Determines whether the given feature's geometry passes the geometric
     * relationship of this filter.
     *
     * @param feature the feature to inspect.
     *
     * @return whether the feature meets the conditions of filtering imposed by
     *         this geometry filter.
     */
    boolean contains(Feature feature);

    /**
     * Retrieves the expression on the right side of the spatial comparison.
     *
     * @return the geometry expression on the right.
     *
     * @deprecated use {@link BinarySpatialOperator#getExpression2()}.
     */
    Expression getRightGeometry();

    /**
     * Retrieves the expression on the left side of the spatial comparison.
     *
     * @return the geometry expression on the left.
     *
     * @deprecated use {@link BinarySpatialOperator#getExpression1()}.
     */
    Expression getLeftGeometry();
}
