Added some documentation to the spatial.query package. Some reformatting too.

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1356561 13f79535-47bb-0310-9956-ffa450edef68

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java

@@ -23,6 +23,8 @@ import com.spatial4j.core.exception.InvalidSpatialArgument;
 import com.spatial4j.core.shape.Shape;
 
 /**
+ * Principally holds the query {@link Shape} and the {@link SpatialOperation}.
+ *
  * @lucene.experimental
  */
 public class SpatialArgs {
@@ -46,34 +48,31 @@ public class SpatialArgs {
     this.shape = shape;
   }
 
-  /**
+  /** Check if the arguments make sense -- throw an exception if not */
-   * Check if the arguments make sense -- throw an exception if not
-   */
   public void validate() throws InvalidSpatialArgument {
     if (operation.isTargetNeedsArea() && !shape.hasArea()) {
       throw new InvalidSpatialArgument(operation + " only supports geometry with area");
     }
   }
 
-  public String toString( SpatialContext context ) {
+  public String toString(SpatialContext context) {
     StringBuilder str = new StringBuilder();
-    str.append( operation.getName() ).append( '(' );
+    str.append(operation.getName()).append('(');
-    str.append( context.toString( shape ) );
+    str.append(context.toString(shape));
-    if( min != null ) {
+    if (min != null) {
       str.append(" min=").append(min);
     }
-    if( max != null ) {
+    if (max != null) {
       str.append(" max=").append(max);
     }
-    str.append(" distPrec=").append(String.format("%.2f%%", distPrecision/100d));
+    str.append(" distPrec=").append(String.format("%.2f%%", distPrecision / 100d));
-    str.append( ')' );
+    str.append(')');
     return str.toString();
   }
 
   @Override
-  public String toString()
+  public String toString() {
-  {
+    return toString(SimpleSpatialContext.GEO_KM);
-    return toString( SimpleSpatialContext.GEO_KM );
   }
 
   //------------------------------------------------
@@ -88,9 +87,7 @@ public class SpatialArgs {
     this.operation = operation;
   }
 
-  /**
+  /** Considers {@link SpatialOperation#BBoxWithin} in returning the shape. */
-   * Considers {@link SpatialOperation#BBoxWithin} in returning the shape.
-   */
   public Shape getShape() {
     if (shape != null && (operation == SpatialOperation.BBoxWithin || operation == SpatialOperation.BBoxIntersects))
       return shape.getBoundingBox();
@@ -102,9 +99,10 @@ public class SpatialArgs {
   }
 
   /**
-   * The fraction of the distance from the center of the query shape to its nearest edge that is considered acceptable
+   * The fraction of the distance from the center of the query shape to its nearest edge
-   * error. The algorithm for computing the distance to the nearest edge is actually a little different. It normalizes
+   * that is considered acceptable error. The algorithm for computing the distance to the
-   * the shape to a square given it's bounding box area:
+   * nearest edge is actually a little different. It normalizes the shape to a square
+   * given it's bounding box area:
    * <pre>sqrt(shape.bbox.area)/2</pre>
    * And the error distance is beyond the shape such that the shape is a minimum shape.
    */

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java

@@ -27,10 +27,32 @@ import java.util.Map;
 import java.util.StringTokenizer;
 
 /**
+ * Parses a string that usually looks like "OPERATION(SHAPE)" into a {@link SpatialArgs}
+ * object. The set of operations supported are defined in {@link SpatialOperation}, such
+ * as "Intersects" being a common one. The shape portion is defined by {@link
+ * SpatialContext#readShape(String)}. There are some optional name-value pair parameters
+ * that follow the closing parenthesis.  Example:
+ * <pre>
+ *   Intersects(-10,20,-8,22) distPec=0.025
+ * </pre>
+ * <p/>
+ * In the future it would be good to support something at least semi-standardized like a
+ * variant of <a href="http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#spatial-predicate">
+ *   [E]CQL</a>.
+ *
  * @lucene.experimental
  */
-public class SpatialArgsParser
+public class SpatialArgsParser {
-{
+
+  /**
+   * Parses a string such as "Intersects(-10,20,-8,22) distPec=0.025".
+   *
+   * @param v   The string to parse. Mandatory.
+   * @param ctx The spatial context. Mandatory.
+   * @return Not null.
+   * @throws InvalidSpatialArgument If there is a problem parsing the string.
+   * @throws InvalidShapeException  Thrown from {@link SpatialContext#readShape(String)}
+   */
   public SpatialArgs parse(String v, SpatialContext ctx) throws InvalidSpatialArgument, InvalidShapeException {
     int idx = v.indexOf('(');
     int edx = v.lastIndexOf(')');
@@ -47,13 +69,13 @@ public class SpatialArgsParser
     }
 
     Shape shape = ctx.readShape(body);
-    SpatialArgs args = new SpatialArgs(op,shape);
+    SpatialArgs args = new SpatialArgs(op, shape);
 
     if (v.length() > (edx + 1)) {
-      body = v.substring( edx+1 ).trim();
+      body = v.substring(edx + 1).trim();
       if (body.length() > 0) {
-        Map<String,String> aa = parseMap(body);
+        Map<String, String> aa = parseMap(body);
-        args.setMin(readDouble(aa.remove("min")) );
+        args.setMin(readDouble(aa.remove("min")));
         args.setMax(readDouble(aa.remove("max")));
         args.setDistPrecision(readDouble(aa.remove("distPrec")));
         if (!aa.isEmpty()) {
@@ -65,15 +87,15 @@ public class SpatialArgsParser
   }
 
   protected static Double readDouble(String v) {
-      return v == null ? null : Double.valueOf(v);
+    return v == null ? null : Double.valueOf(v);
   }
 
   protected static boolean readBool(String v, boolean defaultValue) {
-      return v == null ? defaultValue : Boolean.parseBoolean(v);
+    return v == null ? defaultValue : Boolean.parseBoolean(v);
   }
 
-  protected static Map<String,String> parseMap(String body) {
+  protected static Map<String, String> parseMap(String body) {
-    Map<String,String> map = new HashMap<String,String>();
+    Map<String, String> map = new HashMap<String, String>();
     StringTokenizer st = new StringTokenizer(body, " \n\t");
     while (st.hasMoreTokens()) {
       String a = st.nextToken();

lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java

@@ -20,15 +20,17 @@ package org.apache.lucene.spatial.query;
 import com.spatial4j.core.exception.InvalidSpatialArgument;
 
 import java.io.Serializable;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
 
 /**
  * A clause that compares a stored geometry to a supplied geometry.
  *
  * @see <a href="http://edndoc.esri.com/arcsde/9.1/general_topics/understand_spatial_relations.htm">
  *   ESRIs docs on spatial relations</a>
- * @see <a href="http://docs.geoserver.org/latest/en/user/filter/ecql_reference.html#spatial-predicate">
- *   GeoServer ECQL Spatial Predicates</a>
  *
  * @lucene.experimental
  */