lucene-solr:master: improve javadocs and argument validation for LatLonPoint.nearest

[mi...@apache.org]

Repository: lucene-solr
Updated Branches:
  refs/heads/master d5e0b36d5 -> ad86feca0


improve javadocs and argument validation for LatLonPoint.nearest


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/ad86feca
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/ad86feca
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/ad86feca

Branch: refs/heads/master
Commit: ad86feca097666226c7691c2e47da08e10bf2285
Parents: d5e0b36
Author: Mike McCandless <mi...@apache.org>
Authored: Fri Apr 15 16:55:38 2016 -0400
Committer: Mike McCandless <mi...@apache.org>
Committed: Fri Apr 15 16:55:38 2016 -0400

----------------------------------------------------------------------
 .../org/apache/lucene/document/LatLonPoint.java | 22 ++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ad86feca/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
----------------------------------------------------------------------
diff --git a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
index c5c9249..0f6afe9 100644
--- a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
+++ b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
@@ -22,6 +22,7 @@ import java.util.List;
 
 import org.apache.lucene.codecs.lucene60.Lucene60PointsFormat;
 import org.apache.lucene.codecs.lucene60.Lucene60PointsReader;
+import org.apache.lucene.geo.GeoUtils;
 import org.apache.lucene.geo.Polygon;
 import org.apache.lucene.index.DocValuesType;
 import org.apache.lucene.index.FieldInfo;
@@ -303,7 +304,9 @@ public class LatLonPoint extends Field {
    * <p>
    * 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
-   * 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>
    * 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.
@@ -313,13 +316,24 @@ public class LatLonPoint extends Field {
    * @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 n the number of nearest neighbors to retrieve.
-   * @return TopFieldDocs containing documents ordered by distance.
-   * @throws IllegalArgumentException if the underlying PointValues is not a {@code Lucene60PointsReader} (this is a current limitation).
+   * @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), 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.
    */
   // 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 {
+    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<Integer> docBases = new ArrayList<>();
     List<Bits> liveDocs = new ArrayList<>();