org.apache.lucene.document

Class DateTools

java.lang.Object

org.apache.lucene.document.DateTools

public class DateTools
extends java.lang.Object

Provides support for converting dates to strings and vice-versa. The strings are structured so that lexicographic sorting orders them by date, which makes them suitable for use as field values and search terms.

This class also helps you to limit the resolution of your dates. Do not save dates with a finer resolution than you really need, as then RangeQuery and PrefixQuery will require more memory and become slower.

Compared to DateField the strings generated by the methods in this class take slightly more space, unless your selected resolution is set to Resolution.DAY or lower.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DateTools.Resolution Specifies the time granularity.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	dateToString(java.util.Date date, DateTools.Resolution resolution) Converts a Date to a string suitable for indexing.
static java.util.Date	round(java.util.Date date, DateTools.Resolution resolution) Limit a date's resolution.
static long	round(long time, DateTools.Resolution resolution) Limit a date's resolution.
static java.util.Date	stringToDate(java.lang.String dateString) Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.
static long	stringToTime(java.lang.String dateString) Converts a string produced by timeToString or dateToString back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
static java.lang.String	timeToString(long time, DateTools.Resolution resolution) Converts a millisecond time to a string suitable for indexing.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

dateToString

public static java.lang.String dateToString(java.util.Date date,
                                            DateTools.Resolution resolution)

Converts a Date to a string suitable for indexing.

Parameters:

date - the date to be converted

resolution - the desired resolution, see round(Date, DateTools.Resolution)

Returns:

a string in format yyyyMMddHHmmssSSS or shorter, depeding on resolution; using UTC as timezone

timeToString

public static java.lang.String timeToString(long time,
                                            DateTools.Resolution resolution)

Converts a millisecond time to a string suitable for indexing.

Parameters:

time - the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT

resolution - the desired resolution, see round(long, DateTools.Resolution)

Returns:

a string in format yyyyMMddHHmmssSSS or shorter, depeding on resolution; using UTC as timezone

stringToTime

public static long stringToTime(java.lang.String dateString)
                         throws java.text.ParseException

Converts a string produced by timeToString or dateToString back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

Parameters:

dateString - the date string to be converted

Returns:

the number of milliseconds since January 1, 1970, 00:00:00 GMT

Throws:

java.text.ParseException - if dateString is not in the expected format

stringToDate

public static java.util.Date stringToDate(java.lang.String dateString)
                                   throws java.text.ParseException

Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.

Parameters:

dateString - the date string to be converted

Returns:

the parsed time as a Date object

Throws:

java.text.ParseException - if dateString is not in the expected format

round

public static java.util.Date round(java.util.Date date,
                                   DateTools.Resolution resolution)

Limit a date's resolution. For example, the date 2004-09-21 13:50:11 will be changed to 2004-09-01 00:00:00 when using Resolution.MONTH.

Parameters:

resolution - The desired resolution of the date to be returned

Returns:

the date with all values more precise than resolution set to 0 or 1

round

public static long round(long time,
                         DateTools.Resolution resolution)

Limit a date's resolution. For example, the date 1095767411000 (which represents 2004-09-21 13:50:11) will be changed to 1093989600000 (2004-09-01 00:00:00) when using Resolution.MONTH.

Parameters:

resolution - The desired resolution of the date to be returned

Returns:

the date with all values more precise than resolution set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT