FileDocCategorySizeDatePackage
DateTools.javaAPI DocApache Lucene 2.1.010600Wed Feb 14 10:46:42 GMT 2007org.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
private static final SimpleDateFormat
YEAR_FORMAT
private static final SimpleDateFormat
MONTH_FORMAT
private static final SimpleDateFormat
DAY_FORMAT
private static final SimpleDateFormat
HOUR_FORMAT
private static final SimpleDateFormat
MINUTE_FORMAT
private static final SimpleDateFormat
SECOND_FORMAT
private static final SimpleDateFormat
MILLISECOND_FORMAT
Constructors Summary
private DateTools()

   
    // times need to be normalized so the value doesn't depend on the 
    // location the index is created/used:
    YEAR_FORMAT.setTimeZone(GMT);
    MONTH_FORMAT.setTimeZone(GMT);
    DAY_FORMAT.setTimeZone(GMT);
    HOUR_FORMAT.setTimeZone(GMT);
    MINUTE_FORMAT.setTimeZone(GMT);
    SECOND_FORMAT.setTimeZone(GMT);
    MILLISECOND_FORMAT.setTimeZone(GMT);
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

    Date date;
    if (dateString.length() == 4) {
      synchronized (YEAR_FORMAT) {
        date = YEAR_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 6) {
      synchronized (MONTH_FORMAT) {
        date = MONTH_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 8) {
      synchronized (DAY_FORMAT) {
        date = DAY_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 10) {
      synchronized (HOUR_FORMAT) {
        date = HOUR_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 12) {
      synchronized (MINUTE_FORMAT) {
        date = MINUTE_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 14) {
      synchronized (SECOND_FORMAT) {
        date = SECOND_FORMAT.parse(dateString);
      }
    } else if (dateString.length() == 17) {
      synchronized (MILLISECOND_FORMAT) {
        date = MILLISECOND_FORMAT.parse(dateString);
      }
    } else {
      throw new ParseException("Input is not valid date string: " + dateString, 0);
    }
    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)));

    String result;
    if (resolution == Resolution.YEAR) {
      synchronized (YEAR_FORMAT) {
        result = YEAR_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.MONTH) {
      synchronized (MONTH_FORMAT) {
        result = MONTH_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.DAY) {
      synchronized (DAY_FORMAT) {
        result = DAY_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.HOUR) {
      synchronized (HOUR_FORMAT) {
        result = HOUR_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.MINUTE) {
      synchronized (MINUTE_FORMAT) {
        result = MINUTE_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.SECOND) {
      synchronized (SECOND_FORMAT) {
        result = SECOND_FORMAT.format(cal.getTime());
      }
    } else if (resolution == Resolution.MILLISECOND) {
      synchronized (MILLISECOND_FORMAT) {
        result = MILLISECOND_FORMAT.format(cal.getTime());
      }
    } else {
      throw new IllegalArgumentException("unknown resolution " + resolution);
    }
    return result;