com.eatthepath.jeospatial

Interface GeospatialPointDatabase<E extends GeospatialPoint>

All Superinterfaces:

Collection<E>, Iterable<E>

All Known Implementing Classes:

LockingVPTree, VPTree

public interface GeospatialPointDatabase<E extends GeospatialPoint>
extends Collection<E>

A GeospatialPointDatabase is a collection of geospatial points that can be queried to locate points that are spatially close to a given query point.

Author:

Jon Chambers

Method Summary

Methods

Modifier and Type	Method and Description
List<E>	getAllNeighborsWithinDistance(GeospatialPoint queryPoint, double maxDistance) Returns a list of all points within a given distance to a query point.
List<E>	getAllNeighborsWithinDistance(GeospatialPoint queryPoint, double maxDistance, SearchCriteria<E> searchCriteria) Returns a list of all points within a given distance to a query point that meet a set of search criteria.
List<E>	getAllPointsInBoundingBox(double west, double east, double north, double south) Returns a list of all points in the database within the given bounding "box." A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive).
List<E>	getAllPointsInBoundingBox(double west, double east, double north, double south, GeospatialPoint orderingPoint) Returns a list of all points in the database within the given bounding "box." A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive).
List<E>	getAllPointsInBoundingBox(double west, double east, double north, double south, SearchCriteria<E> otherCriteria) Returns a list of all points in the database within the given bounding "box" that also satisfy the given search criteria.
List<E>	getAllPointsInBoundingBox(double west, double east, double north, double south, SearchCriteria<E> otherCriteria, GeospatialPoint orderingPoint) Returns a list of all points in the database within the given bounding "box" that also satisfy the given search criteria.
E	getNearestNeighbor(GeospatialPoint queryPoint) Returns the nearest neighbor to the given query point.
E	getNearestNeighbor(GeospatialPoint queryPoint, double maxDistance) Returns the nearest neighbor to the given query point so long as the nearest neighbor is within the given maximum distance.
E	getNearestNeighbor(GeospatialPoint queryPoint, double maxDistance, SearchCriteria<E> searchCriteria) Returns the nearest neighbor to the query point that satisfies the given search criteria so long as that point falls within the given maximum distance from the query point.
E	getNearestNeighbor(GeospatialPoint queryPoint, SearchCriteria<E> searchCriteria) Returns the nearest neighbor to the given query point that satisfies the given search criteria.
List<E>	getNearestNeighbors(GeospatialPoint queryPoint, int maxResults) Returns a list of the nearest neighbors to a given query point.
List<E>	getNearestNeighbors(GeospatialPoint queryPoint, int maxResults, double maxDistance) Returns a list of the nearest neighbors to a given query point and within a given maximum distance.
List<E>	getNearestNeighbors(GeospatialPoint queryPoint, int maxResults, double maxDistance, SearchCriteria<E> searchCriteria) Returns a list of the nearest neighbors to a given query point and within a given maximum distance.
List<E>	getNearestNeighbors(GeospatialPoint queryPoint, int maxResults, SearchCriteria<E> searchCriteria) Returns a list of the nearest neighbors to a given query point that satisfy the given search criteria.

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

getNearestNeighbor

E getNearestNeighbor(GeospatialPoint queryPoint)

Returns the nearest neighbor to the given query point. The nearest neighbor is the point with the shortest distance to the query point; if multiple points have the same distance from the query point, which of the points is returned is undefined.

Parameters:

queryPoint - the point for which to find the nearest neighbor

Returns:

the nearest neighbor to the query point or null if the database contains no points

getNearestNeighbor

E getNearestNeighbor(GeospatialPoint queryPoint,
                   double maxDistance)

Returns the nearest neighbor to the given query point so long as the nearest neighbor is within the given maximum distance. The nearest neighbor is the point with the shortest distance to the query point; if multiple points have the same distance from the query point, which of the points is returned is undefined.

Parameters:

queryPoint - the point for which to find the nearest neighbor

maxDistance - the maximum allowable distance from the query point in meters

Returns:

the nearest neighbor to the query point or null if the database contains no points within maxDistance meters of the query point

getNearestNeighbor

E getNearestNeighbor(GeospatialPoint queryPoint,
                   SearchCriteria<E> searchCriteria)

Returns the nearest neighbor to the given query point that satisfies the given search criteria. The nearest neighbor is the point with the shortest distance to the query point; if multiple points have the same distance from the query point, which of the points is returned is undefined.

Parameters:

queryPoint - the point for which to find the nearest neighbor

searchCriteria - the criteria to apply to potential nearest neighbors

Returns:

the nearest neighbor to the query point or null if the database contains no points that satisfy the given search criteria

getNearestNeighbor

E getNearestNeighbor(GeospatialPoint queryPoint,
                   double maxDistance,
                   SearchCriteria<E> searchCriteria)

Returns the nearest neighbor to the query point that satisfies the given search criteria so long as that point falls within the given maximum distance from the query point. The nearest neighbor is the point with the shortest distance to the query point; if multiple points have the same distance from the query point, which of the points is returned is undefined.

Parameters:

queryPoint - the point for which to find the nearest neighbor

maxDistance - the maximum allowable distance from the query point in meters

searchCriteria - the criteria to apply to potential nearest neighbors

Returns:

the nearest neighbor to the query point or null if no points matching the given search criteria were found within maxDistance meters of the query point

getNearestNeighbors

List<E> getNearestNeighbors(GeospatialPoint queryPoint,
                          int maxResults)

Returns a list of the nearest neighbors to a given query point. The returned list is sorted by increasing distance from the query point.

This returned list will contain at most maxResults elements (and may contain fewer if maxResults is larger than the number of points in the database). If multiple points have the same distance from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple points have the same distance from the query point and those points would "straddle" the end of the returned list, which points are included in the list and which are cut off is not prescribed.

Parameters:

queryPoint - the point for which to find neighbors

maxResults - the maximum length of the returned list

Returns:

a list of the nearest neighbors to the given query point sorted by increasing distance from the query point

getNearestNeighbors

List<E> getNearestNeighbors(GeospatialPoint queryPoint,
                          int maxResults,
                          SearchCriteria<E> searchCriteria)

Returns a list of the nearest neighbors to a given query point that satisfy the given search criteria. The returned list is sorted by increasing distance from the query point.

This returned list will contain at most maxResults elements (and may contain fewer if maxResults is larger than the number of points in the database). If multiple points have the same distance from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple points have the same distance from the query point and those points would "straddle" the end of the returned list, which points are included in the list and which are cut off is not prescribed.

Parameters:

queryPoint - the point for which to find neighbors

maxResults - the maximum length of the returned list

searchCriteria - the search criteria to be met by all returned points

Returns:

a list, sorted in order of increasing distance from the query point, of the nearest neighbors to the given query point that meet the given search criteria

getNearestNeighbors

List<E> getNearestNeighbors(GeospatialPoint queryPoint,
                          int maxResults,
                          double maxDistance)

Returns a list of the nearest neighbors to a given query point and within a given maximum distance. The returned list is sorted by increasing distance from the query point.

This returned list will contain at most maxResults elements (and may contain fewer if maxResults is larger than the number of points in the database or if fewer than maxResults points were found within the given maximum distance). If multiple points have the same distance from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple points have the same distance from the query point and those points would "straddle" the end of the returned list, which points are included in the list and which are cut off is not prescribed.

Parameters:

queryPoint - the point for which to find neighbors

maxResults - the maximum length of the returned list

maxDistance - the maximum allowable distance, in meters, from the query point; points farther away than maxDistance will not be included in the returned list

Returns:

a list of the nearest neighbors within the given maximum distance to the given query point; the returned list is sorted in order of increasing distance from the query point

getNearestNeighbors

List<E> getNearestNeighbors(GeospatialPoint queryPoint,
                          int maxResults,
                          double maxDistance,
                          SearchCriteria<E> searchCriteria)

Returns a list of the nearest neighbors to a given query point and within a given maximum distance. The returned list is sorted by increasing distance from the query point.

This returned list will contain at most maxResults elements (and may contain fewer if maxResults is larger than the number of points in the database or if fewer than maxResults points were found within the given maximum distance). If multiple points have the same distance from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple points have the same distance from the query point and those points would "straddle" the end of the returned list, which points are included in the list and which are cut off is not prescribed.

Parameters:

queryPoint - the point for which to find neighbors

maxResults - the maximum length of the returned list

maxDistance - the maximum allowable distance, in meters, from the query point; points farther away than maxDistance will not be included in the returned list

searchCriteria - the search criteria to be met by all returned points

Returns:

a list of the nearest neighbors that meet the given search criteria within the given maximum distance to the given query point; the returned list is sorted in order of increasing distance from the query point

getAllNeighborsWithinDistance

List<E> getAllNeighborsWithinDistance(GeospatialPoint queryPoint,
                                    double maxDistance)

Returns a list of all points within a given distance to a query point.

Parameters:

queryPoint - the point for which to find neighbors

maxDistance - the maximum allowable distance, in meters, from the query point; points farther away than maxDistance will not be included in the returned list

Returns:

a list of all points within the given distance to the query point; the returned list is sorted in order of increasing distance from the query point

getAllNeighborsWithinDistance

List<E> getAllNeighborsWithinDistance(GeospatialPoint queryPoint,
                                    double maxDistance,
                                    SearchCriteria<E> searchCriteria)

Returns a list of all points within a given distance to a query point that meet a set of search criteria.

Parameters:

queryPoint - the point for which to find neighbors

maxDistance - the maximum allowable distance, in meters, from the query point; points farther away than maxDistance will not be included in the returned list

searchCriteria - the search criteria to be met by all points in the returned list

Returns:

a list of all points within the given distance to the query point that meet the given search criteria; the returned list is sorted in order of increasing distance from the query point

getAllPointsInBoundingBox

List<E> getAllPointsInBoundingBox(double west,
                                double east,
                                double north,
                                double south)

Returns a list of all points in the database within the given bounding "box." A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive). The order of the returned list is not prescribed.

Parameters:

west - the western limit of the bounding box in degrees

east - the eastern limit of the bounding box in degrees

north - the northern limit of the bounding box in degrees

south - the southern limit of the bounding box in degrees

Returns:

a list of points in the database within the given bounding box

Throws:

IllegalArgumentException - if the north or south limits fall outside of the range -90 to +90 (inclusive) or if the northern limit is south of the southern limit (or vice versa)

getAllPointsInBoundingBox

List<E> getAllPointsInBoundingBox(double west,
                                double east,
                                double north,
                                double south,
                                GeospatialPoint orderingPoint)

Returns a list of all points in the database within the given bounding "box." A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive). The list of returned points is sorted in order of increasing distance from the given point.

Parameters:

west - the western limit of the bounding box in degrees

east - the eastern limit of the bounding box in degrees

north - the northern limit of the bounding box in degrees

south - the southern limit of the bounding box in degrees

orderingPoint - a point to use for sorting the list of results by distance; may be null if no ordering is required

Returns:

a list of points in the database within the given bounding box sorted in order of increasing distance from the orderingPoint

Throws:

IllegalArgumentException - if the north or south limits fall outside of the range -90 to +90 (inclusive) or if the northern limit is south of the southern limit (or vice versa)

getAllPointsInBoundingBox

List<E> getAllPointsInBoundingBox(double west,
                                double east,
                                double north,
                                double south,
                                SearchCriteria<E> otherCriteria)

Returns a list of all points in the database within the given bounding "box" that also satisfy the given search criteria. A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive). The order of the returned list is not prescribed.

Parameters:

west - the western limit of the bounding box in degrees

east - the eastern limit of the bounding box in degrees

north - the northern limit of the bounding box in degrees

south - the southern limit of the bounding box in degrees

otherCriteria - a set of additional search criteria to apply to points that lie within the bounding box; may be null if no additional criteria are to be applied

Returns:

a list of points in the database within the given bounding box that satisfy the given search criteria

Throws:

IllegalArgumentException - if the north or south limits fall outside of the range -90 to +90 (inclusive) or if the northern limit is south of the southern limit (or vice versa)

getAllPointsInBoundingBox

List<E> getAllPointsInBoundingBox(double west,
                                double east,
                                double north,
                                double south,
                                SearchCriteria<E> otherCriteria,
                                GeospatialPoint orderingPoint)

Returns a list of all points in the database within the given bounding "box" that also satisfy the given search criteria. A point is considered to be inside the box if its latitude falls between the given north and south limits (inclusive) and its longitude falls between the east and west limits (inclusive). The list of returned points is sorted in order of increasing distance from the given point.

Parameters:

west - the western limit of the bounding box in degrees

east - the eastern limit of the bounding box in degrees

north - the northern limit of the bounding box in degrees

south - the southern limit of the bounding box in degrees

otherCriteria - a set of additional search criteria to apply to points that lie within the bounding box; may be null if no additional criteria are to be applied

orderingPoint - a point to use for sorting the list of results by distance; may be null if no ordering is required

Returns:

a list of points in the database within the given bounding box that satisfy the given search criteria sorted in order of increasing distance from the orderingPoint

Throws:

IllegalArgumentException - if the north or south limits fall outside of the range -90 to +90 (inclusive) or if the northern limit is south of the southern limit (or vice versa)