// Spatial Index Library
//
// Copyright (C) 2002 Navel Ltd.
//
// 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.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// Contact information:
// Mailing address:
// Marios Hadjieleftheriou
// University of California, Riverside
// Department of Computer Science
// Surge Building, Room 310
// Riverside, CA 92521
//
// Email:
// marioh@cs.ucr.edu
package org.geotools.caching.spatialindex;
import java.util.Properties;
/**
* A generic contract for spatial indexes, such as quadtrees or r-trees.
* Provides methods to insert, delete and query the index.
* Note that implementations may be n-dimensional.
*
* @author Marios Hadjieleftheriou, marioh@cs.ucr.edu
* @copyright Copyright (C) 2002 Navel Ltd.
* Modified by Christophe Rousson
* Modified by Emily Gouge
*
* @source $URL$
*/
public interface SpatialIndex {
public static final String INDEX_TYPE_PROPERTY = "SpatialIndex.Type";
/**
* This constant is used to check if two doubles are nearly equal.
* Copied from original code by Marios Hadjieleftheriou.
*/
public static final double EPSILON = 1.192092896e-07;
/** Empty the index.
* @throws IllegalStateException
*/
public void clear() throws IllegalStateException;
/** Insert new data in the index.
*
* @param data to insert
* @param a n-dims shape
*/
public void insertData(final Object data, final Shape shape);
/** Traverse index to match data such as :
* <code>query.contains(Data.getShape())</code>
*
* @param query, a n-dims shape
* @param visitor implementing visit() callback method
*/
public void containmentQuery(final Shape query, final Visitor v);
/** Traverse index to match data such as :
* <code>query.intersects(Data.getShape())</code>
*
* @param query, a n-dims shape
* @param visitor implementing visit() callback method
*/
public void intersectionQuery(final Shape query, final Visitor v);
/** Traverse index to match data having query falling inside its shape, ie :
* <code>Data.getShape().contains(query)</code>
*
* @param query, a n-dims point
* @param visitor implementing visit() callback method
*/
public void pointLocationQuery(final Point query, final Visitor v);
/**
* @param k
* @param query
* @param v
* @param nnc
*/
public void nearestNeighborQuery(int k, final Shape query, final Visitor v,
NearestNeighborComparator nnc);
/**
* @param k
* @param query
* @param v
*/
public void nearestNeighborQuery(int k, final Shape query, final Visitor v);
/**
* @return
*/
public Properties getIndexProperties();
/** Implementations may always return true.
*
* @return true if index is valid.
*
* TODO: define what is a valid index.
*/
public boolean isIndexValid();
/**
* @return statistics about the index.
*/
public Statistics getStatistics();
/** Cause pending write operations to happen immediately.
* Use this method to persist the index before disposal.
*
*/
public void flush();
/**
* Initializes the spatial index from
* a storage instance.
* <p>This allows caches to be saved to storage
* and reused.</p>
*
* @param storage
*/
public void initializeFromStorage(Storage storage);
}