Package org.apache.lucene.document

Class DoubleRange

java.lang.Object

org.apache.lucene.document.Field

org.apache.lucene.document.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:

• newIntersectsQuery() matches ranges that intersect the defined search range.
• newWithinQuery() matches ranges that are within the defined search range.
• newContainsQuery() matches ranges that contain the defined search range.

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

Fields inherited from class org.apache.lucene.document.Field

fieldsData, name, tokenStream, type

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

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 org.apache.lucene.document.Field

binaryValue, fieldType, getCharSequenceValue, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue

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