Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

improve javadocs and argument validation for LatLonPoint.nearest

This commit is contained in:
Mike McCandless 2016-04-15 16:55:38 -04:00
parent d5e0b36d50
commit ad86feca09
1 changed files with 18 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
View File

@ -22,6 +22,7 @@ import java.util.List;
import org.apache.lucene.codecs.lucene60.Lucene60PointsFormat; import org.apache.lucene.codecs.lucene60.Lucene60PointsFormat;
import org.apache.lucene.codecs.lucene60.Lucene60PointsReader; import org.apache.lucene.codecs.lucene60.Lucene60PointsReader;
import org.apache.lucene.geo.GeoUtils;
import org.apache.lucene.geo.Polygon; import org.apache.lucene.geo.Polygon;
import org.apache.lucene.index.DocValuesType; import org.apache.lucene.index.DocValuesType;
import org.apache.lucene.index.FieldInfo; import org.apache.lucene.index.FieldInfo;
@ -303,7 +304,9 @@ public class LatLonPoint extends Field {
* <p> * <p>
* This is functionally equivalent to running {@link MatchAllDocsQuery} with a {@link #newDistanceSort}, * This is functionally equivalent to running {@link MatchAllDocsQuery} with a {@link #newDistanceSort},
* but is far more efficient since it takes advantage of properties the indexed BKD tree. Currently this * but is far more efficient since it takes advantage of properties the indexed BKD tree. Currently this
* only works with {@link Lucene60PointsFormat} (used by the default codec). * only works with {@link Lucene60PointsFormat} (used by the default codec). Multi-valued fields are
* currently not de-duplicated, so if a document had multiple instances of the specified field that
* make it into the top n, that document will appear more than once.
* <p> * <p>
* Documents are ordered by ascending distance from the location. The value returned in {@link FieldDoc} for * Documents are ordered by ascending distance from the location. The value returned in {@link FieldDoc} for
* the hits contains a Double instance with the distance in meters. * the hits contains a Double instance with the distance in meters.
@ -313,13 +316,24 @@ public class LatLonPoint extends Field {
* @param latitude latitude at the center: must be within standard +/-90 coordinate bounds. * @param latitude latitude at the center: must be within standard +/-90 coordinate bounds.
* @param longitude longitude at the center: must be within standard +/-180 coordinate bounds. * @param longitude longitude at the center: must be within standard +/-180 coordinate bounds.
* @param n the number of nearest neighbors to retrieve. * @param n the number of nearest neighbors to retrieve.
* @return TopFieldDocs containing documents ordered by distance. * @return TopFieldDocs containing documents ordered by distance, where the field value for each {@link FieldDoc} is the distance in meters
* @throws IllegalArgumentException if the underlying PointValues is not a {@code Lucene60PointsReader} (this is a current limitation). * @throws IllegalArgumentException if the underlying PointValues is not a {@code Lucene60PointsReader} (this is a current limitation), or
* if {@code field} or {@code searcher} is null, or if {@code latitude}, {@code longitude} or {@code n} are out-of-bounds
* @throws IOException if an IOException occurs while finding the points. * @throws IOException if an IOException occurs while finding the points.
*/ */
// TODO: what about multi-valued documents? what happens? // TODO: what about multi-valued documents? what happens?
// TODO: parameter checking, what if i pass a negative n, bogus latitude, null field,etc?
public static TopFieldDocs nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) throws IOException { public static TopFieldDocs nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) throws IOException {
GeoUtils.checkLatitude(latitude);
GeoUtils.checkLongitude(longitude);
if (n < 1) {
throw new IllegalArgumentException("n must be at least 1; got " + n);
}
if (field == null) {
throw new IllegalArgumentException("field must not be null");
}
if (searcher == null) {
throw new IllegalArgumentException("searcher must not be null");
}
List<BKDReader> readers = new ArrayList<>(); List<BKDReader> readers = new ArrayList<>();
List<Integer> docBases = new ArrayList<>(); List<Integer> docBases = new ArrayList<>();
List<Bits> liveDocs = new ArrayList<>(); List<Bits> liveDocs = new ArrayList<>();