From 0963bc09b310fecbbd9c9aa1519520b9200de5af Mon Sep 17 00:00:00 2001 From: David Wayne Smiley Date: Tue, 3 Jul 2012 03:19:03 +0000 Subject: [PATCH] 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/query/SpatialArgs.java | 36 ++++++++-------- .../spatial/query/SpatialArgsParser.java | 42 ++++++++++++++----- .../spatial/query/SpatialOperation.java | 8 ++-- 3 files changed, 54 insertions(+), 32 deletions(-) diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java b/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java index e81a9f66d34..dd4c154ead8 100644 --- a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java +++ b/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( context.toString( shape ) ); - if( min != null ) { + str.append(operation.getName()).append('('); + str.append(context.toString(shape)); + 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( ')' ); + str.append(" distPrec=").append(String.format("%.2f%%", distPrecision / 100d)); + str.append(')'); return str.toString(); } @Override - public String toString() - { - return toString( SimpleSpatialContext.GEO_KM ); + public String toString() { + 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 - * error. The algorithm for computing the distance to the nearest edge is actually a little different. It normalizes - * the shape to a square given it's bounding box area: + * The fraction of the distance from the center of the query shape to its nearest edge + * that is considered acceptable error. The algorithm for computing the distance to the + * nearest edge is actually a little different. It normalizes the shape to a square + * given it's bounding box area: * 
sqrt(shape.bbox.area)/2
* And the error distance is beyond the shape such that the shape is a minimum shape. */ diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java b/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java index fee494934ab..a521eb3f0ca 100644 --- a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java +++ b/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: + * 
+ *   Intersects(-10,20,-8,22) distPec=0.025
+ *
+ *

+ * In the future it would be good to support something at least semi-standardized like a + * variant of + * [E]CQL. + * * @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 aa = parseMap(body); - args.setMin(readDouble(aa.remove("min")) ); + Map aa = parseMap(body); + 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 parseMap(String body) { - Map map = new HashMap(); + protected static Map parseMap(String body) { + Map map = new HashMap(); StringTokenizer st = new StringTokenizer(body, " \n\t"); while (st.hasMoreTokens()) { String a = st.nextToken(); diff --git a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java b/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java index 89af6d35ce6..9a3732143b4 100644 --- a/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialOperation.java +++ b/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 * ESRIs docs on spatial relations - * @see - * GeoServer ECQL Spatial Predicates * * @lucene.experimental */