http://lucene.apache.org/lucene-parent/lucene-core: Apache Lucene Java Core (The Apache Software Foundation) 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.document;


import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;

import org.apache.lucene.search.PrefixQuery;
import org.apache.lucene.search.TermRangeQuery;


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 TermRangeQuery and PrefixQuery will require more memory and become slower. 
 Another approach is LongPoint, which indexes the values in sorted order. For indexing a Date or Calendar, just get the unix timestamp as long using Date.getTime or Calendar.getTimeInMillis and index this as a numeric value with LongPoint and use PointRangeQuery to query it. 
/**
 * 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.
 * 
 * <P>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
 * {@link TermRangeQuery} and {@link PrefixQuery} will require more memory and become slower.
 * 
 * <P>
 * Another approach is {@link LongPoint}, which indexes the
 * values in sorted order.
 * For indexing a {@link Date} or {@link Calendar}, just get the unix timestamp as
 * <code>long</code> using {@link Date#getTime} or {@link Calendar#getTimeInMillis} and
 * index this as a numeric value with {@link LongPoint}
 * and use {@link org.apache.lucene.search.PointRangeQuery} to query it.
 */
public class DateTools {
  
  final static TimeZone GMT = TimeZone.getTimeZone("GMT");

  private static final ThreadLocal<Calendar> TL_CAL = new ThreadLocal<Calendar>() {
    @Override
    protected Calendar initialValue() {
      return Calendar.getInstance(GMT, Locale.ROOT);
    }
  };

  //indexed by format length
  private static final ThreadLocal<SimpleDateFormat[]> TL_FORMATS = new ThreadLocal<SimpleDateFormat[]>() {
    @Override
    protected SimpleDateFormat[] initialValue() {
      SimpleDateFormat[] arr = new SimpleDateFormat[Resolution.MILLISECOND.formatLen+1];
      for (Resolution resolution : Resolution.values()) {
        arr[resolution.formatLen] = (SimpleDateFormat)resolution.format.clone();
      }
      return arr;
    }
  };

  // cannot create, the class has static methods only
  private DateTools() {}

  
Converts a Date to a string suitable for indexing.

Params:
Returns:a string in format yyyyMMddHHmmssSSS or shorter,
 depending on resolution; using GMT as timezone
/**
   * 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 <code>yyyyMMddHHmmssSSS</code> or shorter,
   *  depending on <code>resolution</code>; using GMT as timezone 
   */
  public static String dateToString(Date date, Resolution resolution) {
    return timeToString(date.getTime(), resolution);
  }

  
Converts a millisecond time to a string suitable for indexing.

Params:
  • time – the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
  • resolution – the desired resolution, see round(long, Resolution)
Returns:a string in format yyyyMMddHHmmssSSS or shorter,
 depending on resolution; using GMT as timezone
/**
   * 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 <code>yyyyMMddHHmmssSSS</code> or shorter,
   *  depending on <code>resolution</code>; using GMT as timezone
   */
  public static String timeToString(long time, Resolution resolution) {
    final Date date = new Date(round(time, resolution));
    return TL_FORMATS.get()[resolution.formatLen].format(date);
  }
  
  
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.

Params:
  • dateString – the date string to be converted
Throws:
Returns:the number of milliseconds since January 1, 1970, 00:00:00 GMT
/**
   * Converts a string produced by <code>timeToString</code> or
   * <code>dateToString</code> 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 <code>dateString</code> is not in the 
   *  expected format 
   */
  public static long stringToTime(String dateString) throws ParseException {
    return stringToDate(dateString).getTime();
  }

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

Params:
  • dateString – the date string to be converted
Throws:
Returns:the parsed time as a Date object
/**
   * Converts a string produced by <code>timeToString</code> or
   * <code>dateToString</code> 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 <code>dateString</code> is not in the 
   *  expected format 
   */
  public static Date stringToDate(String dateString) throws ParseException {
    try {
      return TL_FORMATS.get()[dateString.length()].parse(dateString);
    } catch (Exception e) {
      throw new ParseException("Input is not a valid date string: " + dateString, 0);
    }
  }
  
  
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. 

Params:
  • 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
/**
   * Limit a date's resolution. For example, the date <code>2004-09-21 13:50:11</code>
   * will be changed to <code>2004-09-01 00:00:00</code> when using
   * <code>Resolution.MONTH</code>. 
   * 
   * @param resolution The desired resolution of the date to be returned
   * @return the date with all values more precise than <code>resolution</code>
   *  set to 0 or 1
   */
  public static Date round(Date date, Resolution resolution) {
    return new Date(round(date.getTime(), 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.

Params:
  • 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
/**
   * Limit a date's resolution. For example, the date <code>1095767411000</code>
   * (which represents 2004-09-21 13:50:11) will be changed to 
   * <code>1093989600000</code> (2004-09-01 00:00:00) when using
   * <code>Resolution.MONTH</code>.
   * 
   * @param resolution The desired resolution of the date to be returned
   * @return the date with all values more precise than <code>resolution</code>
   *  set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT
   */
  @SuppressWarnings("fallthrough")
  public static long round(long time, Resolution resolution) {
    final Calendar calInstance = TL_CAL.get();
    calInstance.setTimeInMillis(time);
    
    switch (resolution) {
      //NOTE: switch statement fall-through is deliberate
      case YEAR:
        calInstance.set(Calendar.MONTH, 0);
      case MONTH:
        calInstance.set(Calendar.DAY_OF_MONTH, 1);
      case DAY:
        calInstance.set(Calendar.HOUR_OF_DAY, 0);
      case HOUR:
        calInstance.set(Calendar.MINUTE, 0);
      case MINUTE:
        calInstance.set(Calendar.SECOND, 0);
      case SECOND:
        calInstance.set(Calendar.MILLISECOND, 0);
      case MILLISECOND:
        // don't cut off anything
        break;
      default:
        throw new IllegalArgumentException("unknown resolution " + resolution);
    }
    return calInstance.getTimeInMillis();
  }

  
Specifies the time granularity. 
/** Specifies the time granularity. */
  public static enum Resolution {
    
    
Limit a date's resolution to year granularity. 
/** Limit a date's resolution to year granularity. */
    YEAR(4), 
    
Limit a date's resolution to month granularity. 
/** Limit a date's resolution to month granularity. */
    MONTH(6), 
    
Limit a date's resolution to day granularity. 
/** Limit a date's resolution to day granularity. */
    DAY(8), 
    
Limit a date's resolution to hour granularity. 
/** Limit a date's resolution to hour granularity. */
    HOUR(10), 
    
Limit a date's resolution to minute granularity. 
/** Limit a date's resolution to minute granularity. */
    MINUTE(12), 
    
Limit a date's resolution to second granularity. 
/** Limit a date's resolution to second granularity. */
    SECOND(14), 
    
Limit a date's resolution to millisecond granularity. 
/** Limit a date's resolution to millisecond granularity. */
    MILLISECOND(17);

    final int formatLen;
    final SimpleDateFormat format;//should be cloned before use, since it's not threadsafe

    Resolution(int formatLen) {
      this.formatLen = formatLen;
      // formatLen 10's place:                     11111111
      // formatLen  1's place:            12345678901234567
      this.format = new SimpleDateFormat("yyyyMMddHHmmssSSS".substring(0,formatLen),Locale.ROOT);
      this.format.setTimeZone(GMT);
    }

    
this method returns the name of the resolution
in lowercase (for backwards compatibility) 
/** this method returns the name of the resolution
     * in lowercase (for backwards compatibility) */
    @Override
    public String toString() {
      return super.toString().toLowerCase(Locale.ROOT);
    }

  }

}