You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ds...@apache.org on 2012/09/23 07:25:46 UTC
svn commit: r1388956 - in /lucene/dev/branches/branch_4x: ./ lucene/
lucene/spatial/ 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/spat...
Author: dsmiley
Date: Sun Sep 23 05:25:45 2012
New Revision: 1388956
URL: http://svn.apache.org/viewvc?rev=1388956&view=rev
Log:
Enhance documentation for spatial. Still need to properly document the Strategy subclasses thoroughly.
Modified:
lucene/dev/branches/branch_4x/ (props changed)
lucene/dev/branches/branch_4x/lucene/ (props changed)
lucene/dev/branches/branch_4x/lucene/spatial/ (props changed)
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java
lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java
lucene/dev/branches/branch_4x/solr/ (props changed)
lucene/dev/branches/branch_4x/solr/core/ (props changed)
lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java
lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java
lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java
lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java
lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java
Modified: lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/PointPrefixTreeFieldCacheProvider.java Sun Sep 23 05:25:45 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/RecursivePrefixTreeFilter.java Sun Sep 23 05:25:45 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/TermQueryPrefixTreeStrategy.java Sun Sep 23 05:25:45 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.
+ * <p />
+ * 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/GeohashPrefixTree.java Sun Sep 23 05:25:45 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
+ * <a href="http://en.wikipedia.org/wiki/Geohash">Geohashes</a>.
+ * Uses {@link GeohashUtils} to do all the geohash work.
*
* @lucene.experimental
*/
Modified: lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/Node.java Sun Sep 23 05:25:45 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/prefix/tree/QuadPrefixTree.java Sun Sep 23 05:25:45 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
+ * <a href="http://en.wikipedia.org/wiki/Quadtree">quad tree</a> in which an
+ * indexed term will be generated for each node, 'A', 'B', 'C', 'D'.
*
* @lucene.experimental
*/
Modified: lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgs.java Sun Sep 23 05:25:45 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/SpatialArgsParser.java Sun Sep 23 05:25:45 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:
* <pre>
- * Intersects(-10,20,-8,22) distPec=0.025
+ * Intersects(-10,20,-8,22) distErrPct=0.025
* </pre>
* <p/>
* In the future it would be good to support something at least semi-standardized like a
Modified: lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/query/UnsupportedSpatialOperation.java Sun Sep 23 05:25:45 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ShapeFieldCache.java Sun Sep 23 05:25:45 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.
+ * <p>
+ * 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/util/ValueSourceFilter.java Sun Sep 23 05:25:45 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 <code>min</code> and <code>max</code> 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/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java (original)
+++ lucene/dev/branches/branch_4x/lucene/spatial/src/java/org/apache/lucene/spatial/vector/DistanceValueSource.java Sun Sep 23 05:25:45 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/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java (original)
+++ lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialFieldType.java Sun Sep 23 05:25:45 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<T extends SpatialStrategy> extends FieldType {
/** A local-param with one of "none" (default), "distance", or "recipDistance". */
Modified: lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java (original)
+++ lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/AbstractSpatialPrefixTreeFieldType.java Sun Sep 23 05:25:45 2012
@@ -25,6 +25,10 @@ import org.apache.solr.util.MapListener;
import java.util.Map;
+/**
+ * @see PrefixTreeStrategy
+ * @lucene.experimental
+ */
public abstract class AbstractSpatialPrefixTreeFieldType<T extends PrefixTreeStrategy> extends AbstractSpatialFieldType<T> {
/** @see org.apache.lucene.spatial.prefix.RecursivePrefixTreeStrategy#setDefaultFieldValuesArrayLen(int) */
Modified: lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java (original)
+++ lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialPointVectorFieldType.java Sun Sep 23 05:25:45 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<PointVectorStrategy> implements SchemaAware {
protected String numberFieldName = "tdouble";//in example schema defaults to non-zero precision step -- a good choice
Modified: lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java (original)
+++ lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialRecursivePrefixTreeFieldType.java Sun Sep 23 05:25:45 2012
@@ -21,6 +21,10 @@ import org.apache.lucene.spatial.prefix.
import java.util.Map;
+/**
+ * @see RecursivePrefixTreeStrategy
+ * @lucene.experimental
+ */
public class SpatialRecursivePrefixTreeFieldType extends AbstractSpatialPrefixTreeFieldType<RecursivePrefixTreeStrategy> {
/** @see RecursivePrefixTreeStrategy#setPrefixGridScanLevel(int) */
Modified: lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java?rev=1388956&r1=1388955&r2=1388956&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java (original)
+++ lucene/dev/branches/branch_4x/solr/core/src/java/org/apache/solr/schema/SpatialTermQueryPrefixTreeFieldType.java Sun Sep 23 05:25:45 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<TermQueryPrefixTreeStrategy> {
@Override