content: package org.apache.lucene.document;
  
  /**
   * 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.
   */
  
  import org.apache.lucene.search.NumericRangeQuery; // for javadocs
  import org.apache.lucene.util.NumericUtils;        // for javadocs
  
  import java.text.ParseException;
  import java.text.SimpleDateFormat;
  import java.util.Calendar;
  import java.util.Date;
  import java.util.Locale;
  import java.util.TimeZone;
  
  /**
   * 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
   * RangeQuery and PrefixQuery will require more memory and become slower.
   * 
   * <P>Compared to {@link DateField} the strings generated by the methods
   * in this class take slightly more space, unless your selected resolution
   * is set to <code>Resolution.DAY</code> or lower.
   *
   * <P>
   * Another approach is {@link NumericUtils}, which provides
   * a sortable binary representation (prefix encoded) of numeric values, which
   * date/time are.
   * 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 NumericField}
   * and use {@link NumericRangeQuery} 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.US);
      }
    };
  
    //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.
     * 
     * @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.
     * 
     * @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 <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 <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 <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 <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. */
    public static enum Resolution {
      
      YEAR(4), MONTH(6), DAY(8), HOUR(10), MINUTE(12), SECOND(14), 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.US);
        this.format.setTimeZone(GMT);
      }
  
      /** this method returns the name of the resolution
       * in lowercase (for backwards compatibility) */
      @Override
      public String toString() {
        return super.toString().toLowerCase(Locale.ENGLISH);
      }
  
    }
  
  }
  