public class

DateTools

extends Object
java.lang.Object
   ↳ org.apache.lucene.document.DateTools

Class Overview

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.

Another approach is NumericUtils, which provides a sortable binary representation (prefix encoded) of numeric values, which date/time are. For indexing a Date or Calendar, just get the unix timestamp as long using getTime() or getTimeInMillis() and index this as a numeric value with NumericField and use NumericRangeQuery to query it.

Summary

Nested Classes
class DateTools.Resolution Specifies the time granularity. 
Public Methods
synchronized static String dateToString(Date date, DateTools.Resolution resolution)
Converts a Date to a string suitable for indexing.
synchronized static long round(long time, DateTools.Resolution resolution)
Limit a date's resolution.
synchronized static Date round(Date date, DateTools.Resolution resolution)
Limit a date's resolution.
synchronized static Date stringToDate(String dateString)
Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.
synchronized static long stringToTime(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.
synchronized static String timeToString(long time, DateTools.Resolution resolution)
Converts a millisecond time to a string suitable for indexing.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public static synchronized String dateToString (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, depending on resolution; using GMT as timezone

public static synchronized 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

public static synchronized Date round (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

public static synchronized Date stringToDate (String dateString)

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
ParseException if dateString is not in the expected format

public static synchronized long stringToTime (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.

Parameters
dateString the date string to be converted
Returns
  • the number of milliseconds since January 1, 1970, 00:00:00 GMT
Throws
ParseException if dateString is not in the expected format

public static synchronized 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, depending on resolution; using GMT as timezone