FileDocCategorySizeDatePackage
DateTools.javaAPI DocApache Lucene 1.98668Mon Feb 20 09:20:18 GMT 2006org.apache.lucene.document

DateTools

public class DateTools extends 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 {@link 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.

Fields Summary
private static final TimeZone
GMT
Constructors Summary
private DateTools()
Methods Summary
public static java.lang.StringdateToString(java.util.Date date, org.apache.lucene.document.DateTools$Resolution resolution)
Converts a Date to a string suitable for indexing.

param
date the date to be converted
param
resolution the desired resolution, see {@link #round(Date, DateTools.Resolution)}
return
a string in format yyyyMMddHHmmssSSS or shorter, depeding on resolution; using UTC as timezone

    return timeToString(date.getTime(), resolution);
public static java.util.Dateround(java.util.Date date, org.apache.lucene.document.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.

param
resolution The desired resolution of the date to be returned
return
the date with all values more precise than resolution set to 0 or 1

    return new Date(round(date.getTime(), resolution));
public static longround(long time, org.apache.lucene.document.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.

param
resolution The desired resolution of the date to be returned
return
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

    Calendar cal = Calendar.getInstance(GMT);

    // protected in JDK's prior to 1.4
    //cal.setTimeInMillis(time);
    
    cal.setTime(new Date(time));
    
    if (resolution == Resolution.YEAR) {
      cal.set(Calendar.MONTH, 0);
      cal.set(Calendar.DAY_OF_MONTH, 1);
      cal.set(Calendar.HOUR_OF_DAY, 0);
      cal.set(Calendar.MINUTE, 0);
      cal.set(Calendar.SECOND, 0);
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.MONTH) {
      cal.set(Calendar.DAY_OF_MONTH, 1);
      cal.set(Calendar.HOUR_OF_DAY, 0);
      cal.set(Calendar.MINUTE, 0);
      cal.set(Calendar.SECOND, 0);
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.DAY) {
      cal.set(Calendar.HOUR_OF_DAY, 0);
      cal.set(Calendar.MINUTE, 0);
      cal.set(Calendar.SECOND, 0);
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.HOUR) {
      cal.set(Calendar.MINUTE, 0);
      cal.set(Calendar.SECOND, 0);
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.MINUTE) {
      cal.set(Calendar.SECOND, 0);
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.SECOND) {
      cal.set(Calendar.MILLISECOND, 0);
    } else if (resolution == Resolution.MILLISECOND) {
      // don't cut off anything
    } else {
      throw new IllegalArgumentException("unknown resolution " + resolution);
    }
    return cal.getTime().getTime();
public static java.util.DatestringToDate(java.lang.String dateString)
Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.

param
dateString the date string to be converted
return
the parsed time as a Date object
throws
ParseException if dateString is not in the expected format

    String pattern = null;
    if (dateString.length() == 4 )
      pattern = "yyyy";
    else if (dateString.length() == 6 )
      pattern = "yyyyMM";
    else if (dateString.length() == 8 )
      pattern = "yyyyMMdd";
    else if (dateString.length() == 10 )
      pattern = "yyyyMMddHH";
    else if (dateString.length() == 12 )
      pattern = "yyyyMMddHHmm";
    else if (dateString.length() == 14 )
      pattern = "yyyyMMddHHmmss";
    else if (dateString.length() == 17 )
      pattern = "yyyyMMddHHmmssSSS";
    else
      throw new ParseException("Input is not valid date string: " + dateString, 0);
    SimpleDateFormat sdf = new SimpleDateFormat(pattern);
    sdf.setTimeZone(GMT);
    Date date = sdf.parse(dateString);
    return date;
public static longstringToTime(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.

param
dateString the date string to be converted
return
the number of milliseconds since January 1, 1970, 00:00:00 GMT
throws
ParseException if dateString is not in the expected format

    return stringToDate(dateString).getTime();
public static java.lang.StringtimeToString(long time, org.apache.lucene.document.DateTools$Resolution resolution)
Converts a millisecond time to a string suitable for indexing.

param
time the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
param
resolution the desired resolution, see {@link #round(long, DateTools.Resolution)}
return
a string in format yyyyMMddHHmmssSSS or shorter, depeding on resolution; using UTC as timezone

    Calendar cal = Calendar.getInstance(GMT);

    //protected in JDK's prior to 1.4
    //cal.setTimeInMillis(round(time, resolution));
    
    cal.setTime(new Date(round(time, resolution)));

    SimpleDateFormat sdf = new SimpleDateFormat();
    sdf.setTimeZone(GMT);
    String pattern = null;
    if (resolution == Resolution.YEAR) {
      pattern = "yyyy";
    } else if (resolution == Resolution.MONTH) {
      pattern = "yyyyMM";
    } else if (resolution == Resolution.DAY) {
      pattern = "yyyyMMdd";
    } else if (resolution == Resolution.HOUR) {
      pattern = "yyyyMMddHH";
    } else if (resolution == Resolution.MINUTE) {
      pattern = "yyyyMMddHHmm";
    } else if (resolution == Resolution.SECOND) {
      pattern = "yyyyMMddHHmmss";
    } else if (resolution == Resolution.MILLISECOND) {
      pattern = "yyyyMMddHHmmssSSS";
    } else {
      throw new IllegalArgumentException("unknown resolution " + resolution);
    }
    sdf.applyPattern(pattern);
    return sdf.format(cal.getTime());