org.apache.lucene.spatial
Class SpatialStrategy

java.lang.Object
  org.apache.lucene.spatial.SpatialStrategy

Direct Known Subclasses:

PointVectorStrategy, PrefixTreeStrategy

public abstract class SpatialStrategy
extends Object

The SpatialStrategy encapsulates an approach to indexing and searching based on shapes.

Different implementations will support different features. A strategy should document these common elements:

• Can it index more than one shape per field?
• What types of shapes can be indexed?
• What types of query shapes can be used?
• What types of query operations are supported? This might vary per shape.
• Does it use the FieldCache, or some other type of cache? When?

If a strategy only supports certain shapes at index or query time, then in general it will throw an exception if given an incompatible one. It will not be coerced into compatibility.

Note that a SpatialStrategy is not involved with the Lucene stored field values of shapes, which is immaterial to indexing & search.

Thread-safe.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary

protected com.spatial4j.core.context.SpatialContext

ctx

Constructor Summary

SpatialStrategy(com.spatial4j.core.context.SpatialContext ctx, String fieldName)
Constructs the spatial strategy with its mandatory arguments.

Method Summary

abstract Field[]	createIndexableFields(com.spatial4j.core.shape.Shape shape) Returns the IndexableField(s) from the shape that are to be added to the Document.
String	getFieldName() The name of the field or the prefix of them if there are multiple fields needed internally.
com.spatial4j.core.context.SpatialContext	getSpatialContext()
ValueSource	makeDistanceValueSource(com.spatial4j.core.shape.Point queryPoint) See makeDistanceValueSource(com.spatial4j.core.shape.Point, double) called with a multiplier of 1.0 (i.e.
abstract ValueSource	makeDistanceValueSource(com.spatial4j.core.shape.Point queryPoint, double multiplier) Make a ValueSource returning the distance between the center of the indexed shape and queryPoint.
abstract Filter	makeFilter(SpatialArgs args) Make a Filter based principally on SpatialOperation and Shape from the supplied args.
Query	makeQuery(SpatialArgs args) Make a Query based principally on SpatialOperation and Shape from the supplied args.
ValueSource	makeRecipDistanceValueSource(com.spatial4j.core.shape.Shape queryShape) Returns a ValueSource with values ranging from 1 to 0, depending inversely on the distance from makeDistanceValueSource(com.spatial4j.core.shape.Point,double).
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ctx

protected final com.spatial4j.core.context.SpatialContext ctx

Constructor Detail

SpatialStrategy

public SpatialStrategy(com.spatial4j.core.context.SpatialContext ctx,
                       String fieldName)

Constructs the spatial strategy with its mandatory arguments.

Method Detail

getSpatialContext

public com.spatial4j.core.context.SpatialContext getSpatialContext()

getFieldName

public String getFieldName()

The name of the field or the prefix of them if there are multiple fields needed internally.

Returns:

Not null.

createIndexableFields

public abstract Field[] createIndexableFields(com.spatial4j.core.shape.Shape shape)

Returns the IndexableField(s) from the shape that are to be added to the Document. These fields are expected to be marked as indexed and not stored.

Note: If you want to store the shape as a string for retrieval in search results, you could add it like this:

document.add(new StoredField(fieldName,ctx.toString(shape)));

The particular string representation used doesn't matter to the Strategy since it doesn't use it.

Returns:

Not null nor will it have null elements.

Throws:

UnsupportedOperationException - if given a shape incompatible with the strategy

makeDistanceValueSource

public ValueSource makeDistanceValueSource(com.spatial4j.core.shape.Point queryPoint)

See makeDistanceValueSource(com.spatial4j.core.shape.Point, double) called with a multiplier of 1.0 (i.e. units of degrees).

makeDistanceValueSource

public abstract ValueSource makeDistanceValueSource(com.spatial4j.core.shape.Point queryPoint,
                                                    double multiplier)

Make a ValueSource returning the distance between the center of the indexed shape and queryPoint. If there are multiple indexed shapes then the closest one is chosen. The result is multiplied by multiplier, which conveniently is used to get the desired units.

makeQuery

public Query makeQuery(SpatialArgs args)

Make a Query based principally on SpatialOperation and Shape from the supplied args. The default implementation is

return new ConstantScoreQuery(makeFilter(args));

Throws:

UnsupportedOperationException - If the strategy does not support the shape in args

UnsupportedSpatialOperation - If the strategy does not support the SpatialOperation in args.

makeFilter

public abstract Filter makeFilter(SpatialArgs args)

Make a Filter based principally on SpatialOperation and Shape from the supplied args.

If a subclasses implements makeQuery(org.apache.lucene.spatial.query.SpatialArgs) then this method could be simply:

return new QueryWrapperFilter(makeQuery(args).getQuery());

Throws:

UnsupportedOperationException - If the strategy does not support the shape in args

UnsupportedSpatialOperation - If the strategy does not support the SpatialOperation in args.

makeRecipDistanceValueSource

public final ValueSource makeRecipDistanceValueSource(com.spatial4j.core.shape.Shape queryShape)

Returns a ValueSource with values ranging from 1 to 0, depending inversely on the distance from makeDistanceValueSource(com.spatial4j.core.shape.Point,double). The formula is c/(d + c) where 'd' is the distance and 'c' is one tenth the distance to the farthest edge from the center. Thus the scores will be 1 for indexed points at the center of the query shape and as low as ~0.1 at its furthest edges.

toString

public String toString()

Overrides:

toString in class Object