Class DoubleRange

  • All Implemented Interfaces:
    IndexableField

    public class DoubleRange
    extends Field
    An indexed Double Range field.

    This field indexes dimensional ranges defined as min/max pairs. It supports up to a maximum of 4 dimensions (indexed as 8 numeric values). With 1 dimension representing a single double range, 2 dimensions representing a bounding box, 3 dimensions a bounding cube, and 4 dimensions a tesseract.

    Multiple values for the same field in one document is supported, and open ended ranges can be defined using Double.NEGATIVE_INFINITY and Double.POSITIVE_INFINITY.

    This field defines the following static factory methods for common search operations over double ranges:

    • Nested Class Summary

      • Nested classes/interfaces inherited from class org.apache.lucene.document.Field

        Field.Store
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int BYTES
      stores double values so number of bytes is 8
    • Constructor Summary

      Constructors 
      Constructor Description
      DoubleRange​(java.lang.String name, double[] min, double[] max)
      Create a new DoubleRange type, from min/max parallel arrays
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static void checkArgs​(double[] min, double[] max)
      validate the arguments
      (package private) static double decodeMax​(byte[] b, int dimension)
      decodes the max value (for the defined dimension) from the encoded input byte array
      (package private) static double decodeMin​(byte[] b, int dimension)
      decodes the min value (for the defined dimension) from the encoded input byte array
      (package private) static byte[] encode​(double[] min, double[] max)
      Encodes the min, max ranges into a byte array
      private static void encode​(double val, byte[] bytes, int offset)
      encode the given value into the byte array at the defined offset
      double getMax​(int dimension)
      Get the max value for the given dimension
      double getMin​(int dimension)
      Get the min value for the given dimension
      private static FieldType getType​(int dimensions)
      set the field type
      static Query newContainsQuery​(java.lang.String field, double[] min, double[] max)
      Create a query for matching indexed ranges that contain the defined range.
      static Query newCrossesQuery​(java.lang.String field, double[] min, double[] max)
      Create a query for matching indexed ranges that cross the defined range.
      static Query newIntersectsQuery​(java.lang.String field, double[] min, double[] max)
      Create a query for matching indexed ranges that intersect the defined range.
      private static Query newRelationQuery​(java.lang.String field, double[] min, double[] max, RangeFieldQuery.QueryType relation)
      helper method for creating the desired relational query
      static Query newWithinQuery​(java.lang.String field, double[] min, double[] max)
      Create a query for matching indexed ranges that are within the defined range.
      void setRangeValues​(double[] min, double[] max)
      Changes the values of the field.
      java.lang.String toString()
      Prints a Field for human consumption.
      private static java.lang.String toString​(byte[] ranges, int dimension)
      Returns the String representation for the range at the given dimension
      (package private) static void verifyAndEncode​(double[] min, double[] max, byte[] bytes)
      encode the ranges into a sortable byte array (Double.NaN not allowed)
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • BYTES

        public static final int BYTES
        stores double values so number of bytes is 8
        See Also:
        Constant Field Values
    • Constructor Detail

      • DoubleRange

        public DoubleRange​(java.lang.String name,
                           double[] min,
                           double[] max)
        Create a new DoubleRange type, from min/max parallel arrays
        Parameters:
        name - field name. must not be null.
        min - range min values; each entry is the min value for the dimension
        max - range max values; each entry is the max value for the dimension
    • Method Detail

      • getType

        private static FieldType getType​(int dimensions)
        set the field type
      • setRangeValues

        public void setRangeValues​(double[] min,
                                   double[] max)
        Changes the values of the field.
        Parameters:
        min - array of min values. (accepts Double.NEGATIVE_INFINITY)
        max - array of max values. (accepts Double.POSITIVE_INFINITY)
        Throws:
        java.lang.IllegalArgumentException - if min or max is invalid
      • checkArgs

        private static void checkArgs​(double[] min,
                                      double[] max)
        validate the arguments
      • encode

        static byte[] encode​(double[] min,
                             double[] max)
        Encodes the min, max ranges into a byte array
      • verifyAndEncode

        static void verifyAndEncode​(double[] min,
                                    double[] max,
                                    byte[] bytes)
        encode the ranges into a sortable byte array (Double.NaN not allowed)

        example for 4 dimensions (8 bytes per dimension value): minD1 ... minD4 | maxD1 ... maxD4

      • encode

        private static void encode​(double val,
                                   byte[] bytes,
                                   int offset)
        encode the given value into the byte array at the defined offset
      • getMin

        public double getMin​(int dimension)
        Get the min value for the given dimension
        Parameters:
        dimension - the dimension, always positive
        Returns:
        the decoded min value
      • getMax

        public double getMax​(int dimension)
        Get the max value for the given dimension
        Parameters:
        dimension - the dimension, always positive
        Returns:
        the decoded max value
      • decodeMin

        static double decodeMin​(byte[] b,
                                int dimension)
        decodes the min value (for the defined dimension) from the encoded input byte array
      • decodeMax

        static double decodeMax​(byte[] b,
                                int dimension)
        decodes the max value (for the defined dimension) from the encoded input byte array
      • newIntersectsQuery

        public static Query newIntersectsQuery​(java.lang.String field,
                                               double[] min,
                                               double[] max)
        Create a query for matching indexed ranges that intersect the defined range.
        Parameters:
        field - field name. must not be null.
        min - array of min values. (accepts Double.NEGATIVE_INFINITY)
        max - array of max values. (accepts Double.POSITIVE_INFINITY)
        Returns:
        query for matching intersecting ranges (overlap, within, or contains)
        Throws:
        java.lang.IllegalArgumentException - if field is null, min or max is invalid
      • newContainsQuery

        public static Query newContainsQuery​(java.lang.String field,
                                             double[] min,
                                             double[] max)
        Create a query for matching indexed ranges that contain the defined range.
        Parameters:
        field - field name. must not be null.
        min - array of min values. (accepts Double.MIN_VALUE)
        max - array of max values. (accepts Double.MAX_VALUE)
        Returns:
        query for matching ranges that contain the defined range
        Throws:
        java.lang.IllegalArgumentException - if field is null, min or max is invalid
      • newWithinQuery

        public static Query newWithinQuery​(java.lang.String field,
                                           double[] min,
                                           double[] max)
        Create a query for matching indexed ranges that are within the defined range.
        Parameters:
        field - field name. must not be null.
        min - array of min values. (accepts Double.MIN_VALUE)
        max - array of max values. (accepts Double.MAX_VALUE)
        Returns:
        query for matching ranges within the defined range
        Throws:
        java.lang.IllegalArgumentException - if field is null, min or max is invalid
      • newCrossesQuery

        public static Query newCrossesQuery​(java.lang.String field,
                                            double[] min,
                                            double[] max)
        Create a query for matching indexed ranges that cross the defined range. A CROSSES is defined as any set of ranges that are not disjoint and not wholly contained by the query. Effectively, its the complement of union(WITHIN, DISJOINT).
        Parameters:
        field - field name. must not be null.
        min - array of min values. (accepts Double.MIN_VALUE)
        max - array of max values. (accepts Double.MAX_VALUE)
        Returns:
        query for matching ranges within the defined range
        Throws:
        java.lang.IllegalArgumentException - if field is null, min or max is invalid
      • newRelationQuery

        private static Query newRelationQuery​(java.lang.String field,
                                              double[] min,
                                              double[] max,
                                              RangeFieldQuery.QueryType relation)
        helper method for creating the desired relational query
      • toString

        public java.lang.String toString()
        Description copied from class: Field
        Prints a Field for human consumption.
        Overrides:
        toString in class Field
      • toString

        private static java.lang.String toString​(byte[] ranges,
                                                 int dimension)
        Returns the String representation for the range at the given dimension
        Parameters:
        ranges - the encoded ranges, never null
        dimension - the dimension of interest
        Returns:
        The string representation for the range at the provided dimension