org.apache.lucene.spatial.prefix.tree

Class DateRangePrefixTree

java.lang.Object

org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

org.apache.lucene.spatial.prefix.tree.DateRangePrefixTree

public class DateRangePrefixTree
extends NumberRangePrefixTree

A PrefixTree for date ranges in which the levels of the tree occur at natural periods of time (e.g. years, months, ...). You pass in Calendar objects with the desired fields set and the unspecified fields unset, which conveys the precision. The implementation makes some optimization assumptions about a GregorianCalendar; others could probably be supported easily.

Warning: If you construct a Calendar and then get something from the object like a field (e.g. year) or milliseconds, then every field is fully set by side-effect. So after setting the fields, pass it to this API first.

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

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

NumberRangePrefixTree.NRCell, NumberRangePrefixTree.NRShape, NumberRangePrefixTree.SpanUnitsNRShape, NumberRangePrefixTree.UnitNRShape

Field Summary

Fields

Modifier and Type	Field and Description
static Calendar	DEFAULT_CAL The Java platform default Calendar with UTC & ROOT Locale.
static DateRangePrefixTree	INSTANCE Deprecated.
static Calendar	JAVA_UTIL_TIME_COMPAT_CAL A Calendar instance compatible with ZonedDateTime as seen from GregorianCalendar.from(ZonedDateTime).

Fields inherited from class org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

levelByTermLen, maxSubCellsByLevel, maxTermLen, termLenByLevel

Fields inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

ctx, maxLevels

Constructor Summary

Constructors

Constructor and Description
DateRangePrefixTree(Calendar templateCal) Constructs with the specified calendar used as a template to be cloned whenever a new Calendar needs to be created.

Method Summary

Modifier and Type	Method and Description
void	clearFieldsAfter(Calendar cal, int field) Calendar utility method: Calls Calendar.clear(int) for every field after field.
int	getCalPrecisionField(Calendar cal) Calendar utility method: Gets the Calendar field code of the last field that is set prior to an unset field.
int	getNumSubCells(NumberRangePrefixTree.UnitNRShape lv) Returns the number of sub-cells beneath the given UnitNRShape.
int	getTreeLevelForCalendarField(int calField) Calendar utility method: Returns the spatial prefix tree level for the corresponding Calendar field, such as Calendar.YEAR.
Calendar	newCal() Calendar utility method: Returns a clone of the Calendar passed to the constructor with all fields cleared.
Calendar	parseCalendar(String str) Calendar utility method: The reverse of toString(java.util.Calendar).
protected NumberRangePrefixTree.UnitNRShape	parseUnitShape(String str) Parse a String to a UnitNRShape.
Calendar	toCalendar(NumberRangePrefixTree.UnitNRShape lv) Converts the NumberRangePrefixTree.UnitNRShape shape to a corresponding Calendar that is cleared below its level.
Object	toObject(NumberRangePrefixTree.UnitNRShape shape) Calls toCalendar(org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree.UnitNRShape).
NumberRangePrefixTree.UnitNRShape	toShape(Calendar cal) Converts the Calendar into a Shape.
String	toString(Calendar cal) Calendar utility method consistent with DateTimeFormatter.ISO_INSTANT except has no trailing 'Z', and will be truncated to the units given according to Calendar.isSet(int).
protected String	toString(NumberRangePrefixTree.UnitNRShape lv) A string representation of the UnitNRShape that is parse-able by NumberRangePrefixTree.parseUnitShape(String).
NumberRangePrefixTree.UnitNRShape	toUnitShape(Object value) Converts value from a Calendar or Date to a Shape.

Methods inherited from class org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

comparePrefix, getDistanceForLevel, getLevelForDistance, getWorldCell, newCellStack, parseShape, readCell, toRangeShape, toShape, toString, toStringUnitRaw

Methods inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

getMaxLevels, getSpatialContext, getTreeCellIterator

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CAL

public static final Calendar DEFAULT_CAL

The Java platform default Calendar with UTC & ROOT Locale. Generally a GregorianCalendar. Do not modify this!

JAVA_UTIL_TIME_COMPAT_CAL

public static final Calendar JAVA_UTIL_TIME_COMPAT_CAL

A Calendar instance compatible with ZonedDateTime as seen from GregorianCalendar.from(ZonedDateTime). Do not modify this!

INSTANCE

@Deprecated
public static final DateRangePrefixTree INSTANCE

Deprecated.

An instanced based on Calendar.getInstance(TimeZone, Locale) with UTC and Locale.Root. This will (always?) be a GregorianCalendar with a so-called "Gregorian Change Date" of 1582.

Constructor Detail

DateRangePrefixTree

public DateRangePrefixTree(Calendar templateCal)

Constructs with the specified calendar used as a template to be cloned whenever a new Calendar needs to be created. See DEFAULT_CAL and JAVA_UTIL_TIME_COMPAT_CAL.

Method Detail

getNumSubCells

public int getNumSubCells(NumberRangePrefixTree.UnitNRShape lv)

Description copied from class: NumberRangePrefixTree

Returns the number of sub-cells beneath the given UnitNRShape.

Overrides:

getNumSubCells in class NumberRangePrefixTree

newCal

public Calendar newCal()

Calendar utility method: Returns a clone of the Calendar passed to the constructor with all fields cleared.

getTreeLevelForCalendarField

public int getTreeLevelForCalendarField(int calField)

Calendar utility method: Returns the spatial prefix tree level for the corresponding Calendar field, such as Calendar.YEAR. If there's no match, the next greatest level is returned as a negative value.

getCalPrecisionField

public int getCalPrecisionField(Calendar cal)

Calendar utility method: Gets the Calendar field code of the last field that is set prior to an unset field. It only examines fields relevant to the prefix tree. If no fields are set, it returns -1.

clearFieldsAfter

public void clearFieldsAfter(Calendar cal,
                             int field)

Calendar utility method: Calls Calendar.clear(int) for every field after field. Beware of Calendar underflow.

toUnitShape

public NumberRangePrefixTree.UnitNRShape toUnitShape(Object value)

Converts value from a Calendar or Date to a Shape. Other arguments result in a IllegalArgumentException. If a Calendar is passed in, there might be problems if it is not created via newCal().

Specified by:

toUnitShape in class NumberRangePrefixTree

toShape

public NumberRangePrefixTree.UnitNRShape toShape(Calendar cal)

Converts the Calendar into a Shape. The isSet() state of the Calendar is re-instated when done. If a Calendar is passed in, there might be problems if it is not created via newCal().

toObject

public Object toObject(NumberRangePrefixTree.UnitNRShape shape)

Calls toCalendar(org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree.UnitNRShape).

Specified by:

toObject in class NumberRangePrefixTree

toCalendar

public Calendar toCalendar(NumberRangePrefixTree.UnitNRShape lv)

Converts the NumberRangePrefixTree.UnitNRShape shape to a corresponding Calendar that is cleared below its level.

toString

protected String toString(NumberRangePrefixTree.UnitNRShape lv)

Description copied from class: NumberRangePrefixTree

A string representation of the UnitNRShape that is parse-able by NumberRangePrefixTree.parseUnitShape(String).

Specified by:

toString in class NumberRangePrefixTree

toString

public String toString(Calendar cal)

Calendar utility method consistent with DateTimeFormatter.ISO_INSTANT except has no trailing 'Z', and will be truncated to the units given according to Calendar.isSet(int). A fully cleared calendar will yield the string "*". The isSet() state of the Calendar is re-instated when done.

parseUnitShape

protected NumberRangePrefixTree.UnitNRShape parseUnitShape(String str)
                                                    throws ParseException

Description copied from class: NumberRangePrefixTree

Parse a String to a UnitNRShape. "*" should be the full-range (level 0 shape).

Specified by:

parseUnitShape in class NumberRangePrefixTree

Throws:

ParseException

parseCalendar

public Calendar parseCalendar(String str)
                       throws ParseException

Calendar utility method: The reverse of toString(java.util.Calendar). It will only set the fields found, leaving the remainder in an un-set state. A leading '-' or '+' is optional (positive assumed), and a trailing 'Z' is also optional.

Parameters:

str - not null and not empty

Returns:

not null

Throws:

ParseException