/*
 * 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.
 *
 * <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 {

  static final 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.
   *
   * @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) {
      ParseException ex = new ParseException("Input is not a valid date string: " + dateString, 0);
      ex.initCause(e);
      throw ex;
    }
  }

  /**
   * 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 enum Resolution {

    /** Limit a date's resolution to year granularity. */
    YEAR(4),
    /** Limit a date's resolution to month granularity. */
    MONTH(6),
    /** Limit a date's resolution to day granularity. */
    DAY(8),
    /** Limit a date's resolution to hour granularity. */
    HOUR(10),
    /** Limit a date's resolution to minute granularity. */
    MINUTE(12),
    /** Limit a date's resolution to second granularity. */
    SECOND(14),
    /** 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) */
    @Override
    public String toString() {
      return super.toString().toLowerCase(Locale.ROOT);
    }
  }
}
