Return-Path: X-Original-To: apmail-lucene-commits-archive@www.apache.org Delivered-To: apmail-lucene-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 20B5AD084 for ; Sun, 23 Sep 2012 05:25:32 +0000 (UTC) Received: (qmail 7486 invoked by uid 500); 23 Sep 2012 05:25:25 -0000 Mailing-List: contact commits-help@lucene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@lucene.apache.org Delivered-To: mailing list commits@lucene.apache.org Received: (qmail 7460 invoked by uid 99); 23 Sep 2012 05:25:24 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 23 Sep 2012 05:25:24 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 23 Sep 2012 05:25:22 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 8C16123888FE; Sun, 23 Sep 2012 05:24:39 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1388955 - in /lucene/dev/trunk: lucene/spatial/src/java/org/apache/lucene/spatial/prefix/ lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/ lucene/spatial/src/java/org/apache/lucene/spatial/query/ lucene/spatial/src/java/org/a... Date: Sun, 23 Sep 2012 05:24:38 -0000 To: commits@lucene.apache.org From: dsmiley@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120923052439.8C16123888FE@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: dsmiley Date: Sun Sep 23 05:24:37 2012 New Revision: 1388955 URL: http://svn.apache.org/viewvc?rev=1388955&view=rev Log: Enhance documentation for spatial. Still need to properly document the Strategy subclasses thoroughly. Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java Sun Sep 23 05:24:37 2012 @@ -40,8 +40,7 @@ public class PointPrefixTreeFieldCachePr this.grid = grid; } - //A kluge that this is a field - private Node scanCell = null; + private Node scanCell = null;//re-used in readShape to save GC @Override protected Point readShape(BytesRef term) { Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java Sun Sep 23 05:24:37 2012 @@ -34,11 +34,13 @@ import java.io.IOException; import java.util.LinkedList; /** - * Performs a spatial intersection filter against a field indexed with {@link SpatialPrefixTree}, a Trie. + * Performs a spatial intersection filter between a query shape and a field indexed with {@link SpatialPrefixTree}, a Trie. * SPT yields terms (grids) at length 1 and at greater lengths corresponding to greater precisions. * This filter recursively traverses each grid length and uses methods on {@link Shape} to efficiently know * that all points at a prefix fit in the shape or not to either short-circuit unnecessary traversals or to efficiently - * load all enclosed points. + * load all enclosed points. If no indexed data lies in a portion of the shape + * then that portion of the query shape is quickly passed over without + * decomposing the shape unnecessarily. * * @lucene.internal */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java Sun Sep 23 05:24:37 2012 @@ -30,9 +30,14 @@ import org.apache.lucene.spatial.query.U import java.util.List; /** - * A basic implementation using a large {@link TermsFilter} of all the nodes from + * A basic implementation of {@link PrefixTreeStrategy} using a large + * {@link TermsFilter} of all the nodes from * {@link SpatialPrefixTree#getNodes(com.spatial4j.core.shape.Shape, int, boolean)}. - * + * It only supports the search of indexed Point shapes. + *

+ * The precision of query shapes is an important factor in using this Strategy. + * If the precision is too precise then it will result in many terms which will + * amount to a slower query. * @lucene.experimental */ public class TermQueryPrefixTreeStrategy extends PrefixTreeStrategy { Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java Sun Sep 23 05:24:37 2012 @@ -29,7 +29,9 @@ import java.util.List; /** - * A SpatialPrefixGrid based on Geohashes. Uses {@link GeohashUtils} to do all the geohash work. + * A {@link SpatialPrefixTree} based on + * Geohashes. + * Uses {@link GeohashUtils} to do all the geohash work. * * @lucene.experimental */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java Sun Sep 23 05:24:37 2012 @@ -27,7 +27,7 @@ import java.util.Collections; import java.util.List; /** - * Represents a grid cell. These are not necessarily threadsafe, although new Cell("") (world cell) must be. + * Represents a grid cell. These are not necessarily thread-safe, although new Cell("") (world cell) must be. * * @lucene.experimental */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java Sun Sep 23 05:24:37 2012 @@ -31,8 +31,9 @@ import java.util.List; import java.util.Locale; /** - * Implementation of {@link SpatialPrefixTree} which uses a quad tree - * (http://en.wikipedia.org/wiki/Quadtree) + * A {@link SpatialPrefixTree} which uses a + * quad tree in which an + * indexed term will be generated for each node, 'A', 'B', 'C', 'D'. * * @lucene.experimental */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java Sun Sep 23 05:24:37 2012 @@ -24,6 +24,7 @@ import com.spatial4j.core.shape.Shape; /** * Principally holds the query {@link Shape} and the {@link SpatialOperation}. + * It's used as an argument to some methods on {@link org.apache.lucene.spatial.SpatialStrategy}. * * @lucene.experimental */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java Sun Sep 23 05:24:37 2012 @@ -34,7 +34,7 @@ import java.util.StringTokenizer; * ShapeReadWriter#readShape(String)}. There are some optional name-value pair parameters * that follow the closing parenthesis. Example: * 

- *   Intersects(-10,20,-8,22) distPec=0.025
+ *   Intersects(-10,20,-8,22) distErrPct=0.025
  *
*

* In the future it would be good to support something at least semi-standardized like a Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java Sun Sep 23 05:24:37 2012 @@ -18,7 +18,7 @@ package org.apache.lucene.spatial.query; */ /** - * Exception thrown when the strategy cannot implement the requested operation. + * Exception thrown when the {@link org.apache.lucene.spatial.SpatialStrategy} cannot implement the requested operation. * @lucene.experimental */ public class UnsupportedSpatialOperation extends UnsupportedOperationException { Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java Sun Sep 23 05:24:37 2012 @@ -24,7 +24,10 @@ import java.util.List; /** * Bounded Cache of Shapes associated with docIds. Note, multiple Shapes can be - * associated with a given docId + * associated with a given docId. + *

+ * WARNING: This class holds the data in an extremely inefficient manner as all Points are in memory as objects and they + * are stored in many ArrayLists (one per document). So it works but doesn't scale. It will be replaced in the future. * * @lucene.internal */ Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java Sun Sep 23 05:24:37 2012 @@ -28,11 +28,12 @@ import org.apache.lucene.util.Bits; import java.io.IOException; /** - * Filter that matches all documents where a valuesource is + * Filter that matches all documents where a ValueSource is * in between a range of min and max inclusive. * @lucene.internal */ public class ValueSourceFilter extends Filter { + //TODO see https://issues.apache.org/jira/browse/LUCENE-4251 (move out of spatial & improve) final Filter startingFilter; final ValueSource source; Modified: lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java (original) +++ lucene/dev/trunk/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java Sun Sep 23 05:24:37 2012 @@ -30,7 +30,8 @@ import java.io.IOException; import java.util.Map; /** - * An implementation of the Lucene ValueSource model that returns the distance. + * An implementation of the Lucene ValueSource model that returns the distance + * for a {@link PointVectorStrategy}. * * @lucene.internal */ Modified: lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java (original) +++ lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java Sun Sep 23 05:24:37 2012 @@ -47,6 +47,11 @@ import java.io.IOException; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; +/** + * Abstract base class for Solr FieldTypes based on a Lucene 4 {@link SpatialStrategy}. + * + * @lucene.experimental + */ public abstract class AbstractSpatialFieldType extends FieldType { /** A local-param with one of "none" (default), "distance", or "recipDistance". */ Modified: lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java (original) +++ lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java Sun Sep 23 05:24:37 2012 @@ -25,6 +25,10 @@ import org.apache.solr.util.MapListener; import java.util.Map; +/** + * @see PrefixTreeStrategy + * @lucene.experimental + */ public abstract class AbstractSpatialPrefixTreeFieldType extends AbstractSpatialFieldType { /** @see org.apache.lucene.spatial.prefix.RecursivePrefixTreeStrategy#setDefaultFieldValuesArrayLen(int) */ Modified: lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java (original) +++ lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java Sun Sep 23 05:24:37 2012 @@ -23,7 +23,10 @@ import java.util.ArrayList; import java.util.List; import java.util.Map; - +/** + * @see PointVectorStrategy + * @lucene.experimental + */ public class SpatialPointVectorFieldType extends AbstractSpatialFieldType implements SchemaAware { protected String numberFieldName = "tdouble";//in example schema defaults to non-zero precision step -- a good choice Modified: lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java (original) +++ lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java Sun Sep 23 05:24:37 2012 @@ -21,6 +21,10 @@ import org.apache.lucene.spatial.prefix. import java.util.Map; +/** + * @see RecursivePrefixTreeStrategy + * @lucene.experimental + */ public class SpatialRecursivePrefixTreeFieldType extends AbstractSpatialPrefixTreeFieldType { /** @see RecursivePrefixTreeStrategy#setPrefixGridScanLevel(int) */ Modified: lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java URL: http://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java?rev=1388955&r1=1388954&r2=1388955&view=diff ============================================================================== --- lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java (original) +++ lucene/dev/trunk/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java Sun Sep 23 05:24:37 2012 @@ -19,6 +19,10 @@ package org.apache.solr.schema; import org.apache.lucene.spatial.prefix.TermQueryPrefixTreeStrategy; +/** + * @see TermQueryPrefixTreeStrategy + * @lucene.experimental + */ public class SpatialTermQueryPrefixTreeFieldType extends AbstractSpatialPrefixTreeFieldType { @Override