com.eatthepath.jeospatial.util

Class SearchResults<E extends GeospatialPoint>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.PriorityQueue<E>

com.eatthepath.jeospatial.util.SearchResults<E>

All Implemented Interfaces:

Serializable, Iterable<E>, Collection<E>, Queue<E>

public class SearchResults<E extends GeospatialPoint>
extends PriorityQueue<E>

The SearchResults class is a fixed-size PriorityQueue subclass that may or may not accept points that are offered to it based on several criteria. SearchResults instances are always created with a reference to a query point and a prescribed size; when points are offered via the add(E) or addAll(java.util.Collection<? extends E>) methods, the SearchResults instance will accept the point if and only if the following conditions are met:

1. The SearchResults instance contains fewer points than its maximum capacity or the offered point is closer to the query point than the most distant point already in the queue.
2. No maximum distance has been specified or the offered point falls within the maximum allowable distance from the query point.
3. No search criteria have been specified or the offered point meets the given search criteria.

SearchResults objects use an internal reverse geospatial distance comparator; this ensures that the point at the head of the queue is always the most distant point from the query point.

Author:

Jon Chambers

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
SearchResults(GeospatialPoint queryPoint, int maxSize) Constructs a new search result collector that collects up to maxSize points.
SearchResults(GeospatialPoint queryPoint, int maxSize, double maxDistance) Constructs a new search result collector that collects up to maxSize points that fall within the given distance to the query point.
SearchResults(GeospatialPoint queryPoint, int maxSize, double maxDistance, SearchCriteria<E> criteria) Constructs a new search result collector that collects up to maxSize points that fall within the given distance to the query point and meet the given search criteria.
SearchResults(GeospatialPoint queryPoint, int maxSize, SearchCriteria<E> criteria) Constructs a new search result collector that collects up to maxSize points that meet the given search criteria.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(E point) Offers a point to this result set.
boolean	addAll(Collection<? extends E> points) Offers all of the points in the given collection to this result set.
double	getLongestDistanceFromQueryPoint() Returns the distance from the query point provided at construction time to the most distant point in this result set.
List<E>	toSortedList() Returns a list of the points in this result set sorted in order of increasing distance from the query point provided at construction time.

Methods inherited from class java.util.PriorityQueue

clear, comparator, contains, iterator, offer, peek, poll, remove, size, toArray, toArray

Methods inherited from class java.util.AbstractQueue

element, remove

Methods inherited from class java.util.AbstractCollection

containsAll, isEmpty, removeAll, retainAll, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

containsAll, equals, hashCode, isEmpty, removeAll, retainAll

Constructor Detail

SearchResults

public SearchResults(GeospatialPoint queryPoint,
             int maxSize)

Constructs a new search result collector that collects up to maxSize points.

Parameters:

queryPoint - the point to use as the origin of all distance calculations

maxSize - the maximum number of points this result set may contain

SearchResults

public SearchResults(GeospatialPoint queryPoint,
             int maxSize,
             double maxDistance)

Constructs a new search result collector that collects up to maxSize points that fall within the given distance to the query point.

Parameters:

queryPoint - the point to use as the origin of all distance calculations

maxSize - the maximum number of points this result set may contain

maxDistance - the maximum allowable distance from the query point; points more distant than this threshold will always be rejected

SearchResults

public SearchResults(GeospatialPoint queryPoint,
             int maxSize,
             SearchCriteria<E> criteria)

Constructs a new search result collector that collects up to maxSize points that meet the given search criteria.

Parameters:

queryPoint - the point to use as the origin of all distance calculations

maxSize - the maximum number of points this result set may contain

criteria - the search criteria to be met by all points included in this result set; points that do not meet the search criteria will always be rejected

SearchResults

public SearchResults(GeospatialPoint queryPoint,
             int maxSize,
             double maxDistance,
             SearchCriteria<E> criteria)

Constructs a new search result collector that collects up to maxSize points that fall within the given distance to the query point and meet the given search criteria.

Parameters:

queryPoint - the point to use as the origin of all distance calculations

maxSize - the maximum number of points this result set may contain

maxDistance - the maximum allowable distance from the query point; points more distant than this threshold will always be rejected

criteria - the search criteria to be met by all points included in this result set; points that do not meet the search criteria will always be rejected

Method Detail

add

public boolean add(E point)

Offers a point to this result set. The point will be added only if it meets all criteria provided at construction time and if the search result set is not yet full or the offered point is closer to the query point than the most distant point currently in the result set.

Specified by:

add in interface Collection<E extends GeospatialPoint>

Specified by:

add in interface Queue<E extends GeospatialPoint>

Overrides:

add in class PriorityQueue<E extends GeospatialPoint>

Parameters:

point - the point to offer to this result set

Returns:

true if the point was added to this result set or false otherwise

addAll

public boolean addAll(Collection<? extends E> points)

Offers all of the points in the given collection to this result set.

Specified by:

addAll in interface Collection<E extends GeospatialPoint>

Overrides:

addAll in class AbstractQueue<E extends GeospatialPoint>

Parameters:

points - the collection of points to add to this queue

Returns:

true if any of the offered points were added to this result set or false otherwise

Throws:

IllegalArgumentException - if the specified collection is this result set

See Also:

add(GeospatialPoint)

getLongestDistanceFromQueryPoint

public double getLongestDistanceFromQueryPoint()

Returns the distance from the query point provided at construction time to the most distant point in this result set.

Returns:

the distance, in meters, from the query point to the most distant point in this result set, or Double.POSITIVE_INFINITY if this result set is empty

toSortedList

public List<E> toSortedList()

Returns a list of the points in this result set sorted in order of increasing distance from the query point provided at construction time. The result set itself is not modified by calls to this method.

Returns:

a sorted list of the points in this result set