org.apache.lucene.spatial

## Class SpatialStrategy

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

- Direct Known Subclasses:
    BBoxStrategy, CompositeSpatialStrategy, PointVectorStrategy, PrefixTreeStrategy, SerializedDVStrategy

      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 some 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 and search.

  Thread-safe.

  This API is marked as experimental, however it is quite stable.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.locationtech.spatial4j.context.SpatialContext` | `ctx`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SpatialStrategy(org.locationtech.spatial4j.context.SpatialContext ctx, String fieldName)` Constructs the spatial strategy with its mandatory arguments.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Field[]` | `createIndexableFields(org.locationtech.spatial4j.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.
    `org.locationtech.spatial4j.context.SpatialContext` | `getSpatialContext()`
    `DoubleValuesSource` | `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point queryPoint)` See `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point, double)` called with a multiplier of 1.0 (i.e.
    `abstract DoubleValuesSource` | `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point queryPoint, double multiplier)` Make a ValueSource returning the distance between the center of the indexed shape and `queryPoint`.
    `abstract Query` | `makeQuery(SpatialArgs args)` Make a Query based principally on `SpatialOperation` and `Shape` from the supplied `args`.
    `DoubleValuesSource` | `makeRecipDistanceValueSource(org.locationtech.spatial4j.shape.Shape queryShape)` Returns a ValueSource with values ranging from 1 to 0, depending inversely on the distance from `makeDistanceValueSource(org.locationtech.spatial4j.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 org.locationtech.spatial4j.context.SpatialContext ctx

  - ### Constructor Detail

    - #### SpatialStrategy

          public SpatialStrategy(org.locationtech.spatial4j.context.SpatialContext ctx,
                                 String fieldName)

      Constructs the spatial strategy with its mandatory arguments.

  - ### Method Detail

    - #### getSpatialContext

          public org.locationtech.spatial4j.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(org.locationtech.spatial4j.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 DoubleValuesSource makeDistanceValueSource(org.locationtech.spatial4j.shape.Point queryPoint)

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

    - #### makeDistanceValueSource

          public abstract DoubleValuesSource makeDistanceValueSource(org.locationtech.spatial4j.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 abstract Query makeQuery(SpatialArgs args)

      Make a Query based principally on `SpatialOperation` and `Shape` from the supplied `args`. It should be constant scoring of 1.
      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 DoubleValuesSource makeRecipDistanceValueSource(org.locationtech.spatial4j.shape.Shape queryShape)

      Returns a ValueSource with values ranging from 1 to 0, depending inversely on the distance from `makeDistanceValueSource(org.locationtech.spatial4j.shape.Point,double)`. The formula is `zScaling/(d + zScaling)` where 'd' is the distance and 'zScaling' 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`

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.