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 DateRangePrefixTree	INSTANCE

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

Modifier	Constructor and Description
protected	DateRangePrefixTree()

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 new Calendar in UTC TimeZone, ROOT Locale, 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: Formats the calendar to ISO-8601 format, to include proper BC handling (1BC is "0000", 2BC is "-0001", etc.); and WITHOUT a trailing 'Z'.
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

INSTANCE

public static final DateRangePrefixTree INSTANCE

Constructor Detail

DateRangePrefixTree

protected DateRangePrefixTree()

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 new Calendar in UTC TimeZone, ROOT Locale, 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.

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.

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: Formats the calendar to ISO-8601 format, to include proper BC handling (1BC is "0000", 2BC is "-0001", etc.); and WITHOUT a trailing 'Z'. 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