/*
 * 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
 *
 *      https://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.commons.lang3.time;

import java.text.DateFormat;
import java.text.FieldPosition;
import java.text.Format;
import java.text.ParseException;
import java.text.ParsePosition;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Locale;
import java.util.TimeZone;

/**
 * FastDateFormat is a fast and thread-safe version of {@link java.text.SimpleDateFormat}.
 *
 * <p>
 * To obtain an instance of FastDateFormat, use one of the static factory methods: {@link #getInstance(String, TimeZone, Locale)},
 * {@link #getDateInstance(int, TimeZone, Locale)}, {@link #getTimeInstance(int, TimeZone, Locale)}, or {@link #getDateTimeInstance(int, int, TimeZone, Locale)}
 * </p>
 *
 * <p>
 * Since FastDateFormat is thread safe, you can use a static member instance:
 * </p>
 * {@code
 *   private static final FastDateFormat DATE_FORMATTER = FastDateFormat.getDateTimeInstance(FastDateFormat.LONG, FastDateFormat.SHORT);
 * }
 *
 * <p>
 * This class can be used as a direct replacement to {@link SimpleDateFormat} in most formatting and parsing situations. This class is especially useful in
 * multi-threaded server environments. {@link SimpleDateFormat} is not thread-safe in any JDK version, nor will it be as Sun have closed the bug/RFE.
 * </p>
 *
 * <p>
 * Note on memory retention: unlike {@code new SimpleDateFormat(pattern)}, instances obtained from the static factory methods are held in a static cache keyed
 * by (pattern, time zone, locale). The cache is bounded (it is flushed when it exceeds an internal limit) and can be flushed explicitly with
 * {@link #clear()}, but each distinct key retains its instance for the lifetime of the JVM until then. Prefer fixed, application-defined patterns; do not
 * pass unvalidated caller-supplied pattern, time zone, or locale values to the factory methods.
 * </p>
 *
 * <p>
 * All patterns are compatible with SimpleDateFormat (except time zones and some year patterns - see below).
 * </p>
 *
 * <p>
 * Since 3.2, FastDateFormat supports parsing as well as printing.
 * </p>
 *
 * <p>
 * Java 1.4 introduced a new pattern letter, {@code 'Z'}, to represent time zones in RFC822 format (for example, {@code +0800} or {@code -1100}). This pattern letter can
 * be used here (on all JDK versions).
 * </p>
 *
 * <p>
 * The pattern {@code 'ZZ'} represents ISO 8601 extended format time zones (for example, {@code +08:00} or {@code -11:00}), printing {@code Z} for
 * a zero offset. Three or more {@code 'Z'} letters also print colon-separated offsets, but print {@code +00:00} for a zero offset. These patterns differ
 * from {@link SimpleDateFormat}.
 * </p>
 *
 * <p>
 * When parsing, {@code 'ZZ'} accepts {@code Z} or a colon-separated numeric offset. Three or more {@code 'Z'} letters accept colon-separated numeric
 * offsets as well as the RFC822 offsets, GMT offsets, and localized time zone names accepted by a single {@code 'Z'}.
 * </p>
 *
 * <p>
 * Javadoc cites for the year pattern: <i>For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits; otherwise it is interpreted
 * as a number.</i> Starting with Java 1.7 a pattern of 'Y' or 'YYY' will be formatted as '2003', while it was '03' in former Java versions. FastDateFormat
 * implements the behavior of Java 7.
 * </p>
 *
 * @since 2.0
 */
public class FastDateFormat extends Format implements DateParser, DatePrinter {

    /**
     * Required for serialization support.
     *
     * @see java.io.Serializable
     */
    private static final long serialVersionUID = 2L;

    /**
     * FULL locale dependent date or time style.
     */
    public static final int FULL = DateFormat.FULL;

    /**
     * LONG locale dependent date or time style.
     */
    public static final int LONG = DateFormat.LONG;

    /**
     * MEDIUM locale dependent date or time style.
     */
    public static final int MEDIUM = DateFormat.MEDIUM;

    /**
     * SHORT locale dependent date or time style.
     */
    public static final int SHORT = DateFormat.SHORT;

    private static final AbstractFormatCache<FastDateFormat> CACHE = new AbstractFormatCache<FastDateFormat>() {

        @Override
        protected FastDateFormat createInstance(final String pattern, final TimeZone timeZone, final Locale locale) {
            return new FastDateFormat(pattern, timeZone, locale);
        }
    };

    /**
     * Clears the caches.
     * <p>
     * Clears the static caches used by {@link FastDateFormat}: the (pattern, time zone, locale) to instance cache and the time zone display-name cache.
     * Cached instances already obtained by callers remain valid; subsequent factory calls simply create and cache new instances. This can be used for
     * operational relief if many distinct patterns, time zones, or locales have been used.
     * </p>
     */
    static void clear() {
        AbstractFormatCache.clear();
        CACHE.clearInstance();
        FastDatePrinter.clear();
    }

//    /**
//     * Clears the static caches used by {@link FastDateFormat}: the (pattern, time zone, locale) to instance cache and the time zone display-name cache.
//     * Cached instances already obtained by callers remain valid; subsequent factory calls simply create and cache new instances. This can be used for
//     * operational relief if many distinct patterns, time zones, or locales have been used.
//     *
//     * @since 3.21.0
//     */
//    public static void clearCache() {
//        clear();
//        FastDatePrinter.clear();
//    }

    /**
     * Gets a date formatter instance using the specified style in the default time zone and locale.
     *
     * @param style date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @return A localized standard date formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateInstance(final int style) {
        return CACHE.getDateInstance(style, null, null);
    }

    /**
     * Gets a date formatter instance using the specified style and locale in the default time zone.
     *
     * @param style  date style: {@link #FULL}, LO{@link #FULL},{@link #MEDIUM}, or {@link #SHORT}.
     * @param locale optional locale, overrides system locale.
     * @return A localized standard date formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateInstance(final int style, final Locale locale) {
        return CACHE.getDateInstance(style, null, locale);
    }

    /**
     * Gets a date formatter instance using the specified style and time zone in the default locale.
     *
     * @param style    date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone optional time zone, overrides time zone of formatted date.
     * @return A localized standard date formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateInstance(final int style, final TimeZone timeZone) {
        return CACHE.getDateInstance(style, timeZone, null);
    }

    /**
     * Gets a date formatter instance using the specified style, time zone and locale.
     *
     * @param style    date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone optional time zone, overrides time zone of formatted date.
     * @param locale   optional locale, overrides system locale.
     * @return A localized standard date formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date pattern defined.
     */
    public static FastDateFormat getDateInstance(final int style, final TimeZone timeZone, final Locale locale) {
        return CACHE.getDateInstance(style, timeZone, locale);
    }

    /**
     * Gets a date/time formatter instance using the specified style in the default time zone and locale.
     *
     * @param dateStyle date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeStyle time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @return A localized standard date/time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date/time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle) {
        return CACHE.getDateTimeInstance(dateStyle, timeStyle, null, null);
    }

    /**
     * Gets a date/time formatter instance using the specified style and locale in the default time zone.
     *
     * @param dateStyle date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeStyle time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param locale    optional locale, overrides system locale.
     * @return A localized standard date/time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date/time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final Locale locale) {
        return CACHE.getDateTimeInstance(dateStyle, timeStyle, null, locale);
    }

    /**
     * Gets a date/time formatter instance using the specified style and time zone in the default locale.
     *
     * @param dateStyle date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeStyle time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone  optional time zone, overrides time zone of formatted date.
     * @return A localized standard date/time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date/time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final TimeZone timeZone) {
        return getDateTimeInstance(dateStyle, timeStyle, timeZone, null);
    }

    /**
     * Gets a date/time formatter instance using the specified style, time zone and locale.
     *
     * @param dateStyle date style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeStyle time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone  optional time zone, overrides time zone of formatted date.
     * @param locale    optional locale, overrides system locale.
     * @return A localized standard date/time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no date/time pattern defined.
     */
    public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final TimeZone timeZone, final Locale locale) {
        return CACHE.getDateTimeInstance(dateStyle, timeStyle, timeZone, locale);
    }

    /**
     * Gets a formatter instance using the default pattern in the default locale.
     *
     * @return A date/time formatter.
     */
    public static FastDateFormat getInstance() {
        return CACHE.getInstance();
    }

    /**
     * Gets a formatter instance using the specified pattern in the default locale and time zone.
     *
     * @param pattern {@link java.text.SimpleDateFormat} compatible pattern.
     * @return A pattern based date/time formatter.
     * @throws IllegalArgumentException Thrown if pattern is invalid.
     */
    public static FastDateFormat getInstance(final String pattern) {
        return CACHE.getInstance(pattern, null, null);
    }

    /**
     * Gets a formatter instance using the specified pattern and locale using the default time zone.
     *
     * @param pattern {@link java.text.SimpleDateFormat} compatible pattern.
     * @param locale  optional locale, overrides system locale.
     * @return A pattern based date/time formatter.
     * @throws IllegalArgumentException Thrown if pattern is invalid.
     */
    public static FastDateFormat getInstance(final String pattern, final Locale locale) {
        return CACHE.getInstance(pattern, null, locale);
    }

    /**
     * Gets a formatter instance using the specified pattern and time zone.
     *
     * @param pattern  {@link java.text.SimpleDateFormat} compatible pattern.
     * @param timeZone optional time zone, overrides time zone of formatted date.
     * @return A pattern based date/time formatter.
     * @throws IllegalArgumentException Thrown if pattern is invalid.
     */
    public static FastDateFormat getInstance(final String pattern, final TimeZone timeZone) {
        return CACHE.getInstance(pattern, timeZone, null);
    }

    /**
     * Gets a formatter instance using the specified pattern, time zone and locale.
     *
     * @param pattern  {@link java.text.SimpleDateFormat} compatible pattern.
     * @param timeZone optional time zone, overrides time zone of formatted date.
     * @param locale   optional locale, overrides system locale.
     * @return A pattern based date/time formatter.
     * @throws IllegalArgumentException Thrown if pattern is invalid or {@code null}.
     */
    public static FastDateFormat getInstance(final String pattern, final TimeZone timeZone, final Locale locale) {
        return CACHE.getInstance(pattern, timeZone, locale);
    }

    /**
     * Gets a time formatter instance using the specified style in the default time zone and locale.
     *
     * @param style time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @return A localized standard time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getTimeInstance(final int style) {
        return CACHE.getTimeInstance(style, null, null);
    }

    /**
     * Gets a time formatter instance using the specified style and locale in the default time zone.
     *
     * @param style  time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param locale optional locale, overrides system locale.
     * @return A localized standard time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getTimeInstance(final int style, final Locale locale) {
        return CACHE.getTimeInstance(style, null, locale);
    }

    /**
     * Gets a time formatter instance using the specified style and time zone in the default locale.
     *
     * @param style    time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone optional time zone, overrides time zone of formatted time.
     * @return A localized standard time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no time pattern defined.
     * @since 2.1
     */
    public static FastDateFormat getTimeInstance(final int style, final TimeZone timeZone) {
        return CACHE.getTimeInstance(style, timeZone, null);
    }

    /**
     * Gets a time formatter instance using the specified style, time zone and locale.
     *
     * @param style    time style: {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, or {@link #SHORT}.
     * @param timeZone optional time zone, overrides time zone of formatted time.
     * @param locale   optional locale, overrides system locale.
     * @return A localized standard time formatter.
     * @throws IllegalArgumentException Thrown if the Locale has no time pattern defined.
     */
    public static FastDateFormat getTimeInstance(final int style, final TimeZone timeZone, final Locale locale) {
        return CACHE.getTimeInstance(style, timeZone, locale);
    }

    /** Our fast printer. */
    private final FastDatePrinter printer;

    /** Our fast parser. */
    private final FastDateParser parser;

    /**
     * Constructs a new FastDateFormat.
     *
     * @param pattern  {@link java.text.SimpleDateFormat} compatible pattern.
     * @param timeZone non-null time zone to use.
     * @param locale   non-null locale to use.
     * @throws NullPointerException Thrown if pattern, timeZone, or locale is null.
     */
    protected FastDateFormat(final String pattern, final TimeZone timeZone, final Locale locale) {
        this(pattern, timeZone, locale, null);
    }

    /**
     * Constructs a new FastDateFormat.
     *
     * @param pattern      {@link java.text.SimpleDateFormat} compatible pattern.
     * @param timeZone     non-null time zone to use.
     * @param locale       non-null locale to use.
     * @param centuryStart The start of the 100-year period to use as the "default century" for 2 digit year parsing. If centuryStart is null, defaults to now -
     *                     80 years.
     * @throws NullPointerException Thrown if pattern, timeZone, or locale is null.
     */
    protected FastDateFormat(final String pattern, final TimeZone timeZone, final Locale locale, final Date centuryStart) {
        printer = new FastDatePrinter(pattern, timeZone, locale);
        parser = new FastDateParser(pattern, timeZone, locale, centuryStart);
    }

    /**
     * Performs the formatting by applying the rules to the specified calendar.
     *
     * @param calendar The calendar to format.
     * @param buf      The buffer to format into.
     * @return The specified string buffer.
     * @deprecated Use {@link #format(Calendar, Appendable)}
     */
    @Deprecated
    protected StringBuffer applyRules(final Calendar calendar, final StringBuffer buf) {
        return printer.format(calendar, buf);
    }

    /**
     * Compares two objects for equality.
     *
     * @param obj The object to compare to.
     * @return {@code true} if equal.
     */
    @Override
    public boolean equals(final Object obj) {
        if (!(obj instanceof FastDateFormat)) {
            return false;
        }
        final FastDateFormat other = (FastDateFormat) obj;
        // no need to check parser, as it has same invariants as printer
        return printer.equals(other.printer);
    }

    /**
     * Formats a {@link Calendar} object.
     *
     * @param calendar The calendar to format.
     * @return The formatted string.
     */
    @Override
    public String format(final Calendar calendar) {
        return printer.format(calendar);
    }

    /**
     * Formats a {@link Calendar} object into the supplied {@link StringBuffer}.
     *
     * @param calendar The calendar to format.
     * @param buf      The buffer to format into.
     * @return The specified string buffer.
     * @since 3.5
     */
    @Override
    public <B extends Appendable> B format(final Calendar calendar, final B buf) {
        return printer.format(calendar, buf);
    }

    /**
     * Formats a {@link Calendar} object into the supplied {@link StringBuffer}.
     *
     * @param calendar The calendar to format.
     * @param buf      The buffer to format into.
     * @return The specified string buffer.
     * @deprecated Use {{@link #format(Calendar, Appendable)}.
     */
    @Deprecated
    @Override
    public StringBuffer format(final Calendar calendar, final StringBuffer buf) {
        return printer.format(calendar, buf);
    }

    /**
     * Formats a {@link Date} object using a {@link GregorianCalendar}.
     *
     * @param date The date to format.
     * @return The formatted string.
     */
    @Override
    public String format(final Date date) {
        return printer.format(date);
    }

    /**
     * Formats a {@link Date} object into the supplied {@link StringBuffer} using a {@link GregorianCalendar}.
     *
     * @param date The date to format.
     * @param buf  The buffer to format into.
     * @return The specified string buffer.
     * @since 3.5
     */
    @Override
    public <B extends Appendable> B format(final Date date, final B buf) {
        return printer.format(date, buf);
    }

    /**
     * Formats a {@link Date} object into the supplied {@link StringBuffer} using a {@link GregorianCalendar}.
     *
     * @param date The date to format.
     * @param buf  The buffer to format into.
     * @return The specified string buffer.
     * @deprecated Use {{@link #format(Date, Appendable)}.
     */
    @Deprecated
    @Override
    public StringBuffer format(final Date date, final StringBuffer buf) {
        return printer.format(date, buf);
    }

    /**
     * Formats a millisecond {@code long} value.
     *
     * @param millis The millisecond value to format.
     * @return The formatted string.
     * @since 2.1
     */
    @Override
    public String format(final long millis) {
        return printer.format(millis);
    }

    /**
     * Formats a millisecond {@code long} value into the supplied {@link StringBuffer}.
     *
     * @param millis The millisecond value to format.
     * @param buf    The buffer to format into.
     * @return The specified string buffer.
     * @since 3.5
     */
    @Override
    public <B extends Appendable> B format(final long millis, final B buf) {
        return printer.format(millis, buf);
    }

    /**
     * Formats a millisecond {@code long} value into the supplied {@link StringBuffer}.
     *
     * @param millis The millisecond value to format.
     * @param buf    The buffer to format into.
     * @return The specified string buffer.
     * @since 2.1
     * @deprecated Use {{@link #format(long, Appendable)}.
     */
    @Deprecated
    @Override
    public StringBuffer format(final long millis, final StringBuffer buf) {
        return printer.format(millis, buf);
    }

    /**
     * Formats a {@link Date}, {@link Calendar} or {@link Long} (milliseconds) object. This method is an implementation of
     * {@link Format#format(Object, StringBuffer, FieldPosition)}
     *
     * @param obj        The object to format.
     * @param toAppendTo The buffer to append to.
     * @param pos        The position, ignored.
     * @return The given buffer.
     */
    @Override
    public StringBuffer format(final Object obj, final StringBuffer toAppendTo, final FieldPosition pos) {
        return toAppendTo.append(printer.format(obj));
    }

    /**
     * Gets the locale used by this formatter.
     *
     * @return The locale.
     */
    @Override
    public Locale getLocale() {
        return printer.getLocale();
    }

    /**
     * Gets an estimate for the maximum string length that the formatter will produce.
     *
     * <p>
     * The actual formatted length will almost always be less than or equal to this amount.
     * </p>
     *
     * @return The maximum formatted length.
     */
    public int getMaxLengthEstimate() {
        return printer.getMaxLengthEstimate();
    }

    /**
     * Gets the pattern used by this formatter.
     *
     * @return The pattern, {@link java.text.SimpleDateFormat} compatible.
     */
    @Override
    public String getPattern() {
        return printer.getPattern();
    }

    /**
     * Gets the time zone used by this formatter.
     *
     * <p>
     * This zone is always used for {@link Date} formatting.
     * </p>
     *
     * @return A copy of the time zone, changing it has no effect on this formatter.
     */
    @Override
    public TimeZone getTimeZone() {
        return printer.getTimeZone();
    }

    /**
     * Returns a hash code compatible with equals.
     *
     * @return A hash code compatible with equals.
     */
    @Override
    public int hashCode() {
        return printer.hashCode();
    }

    /*
     * (non-Javadoc)
     *
     * @see DateParser#parse(String)
     */
    @Override
    public Date parse(final String source) throws ParseException {
        return parser.parse(source);
    }

    /*
     * (non-Javadoc)
     *
     * @see DateParser#parse(String, java.text.ParsePosition)
     */
    @Override
    public Date parse(final String source, final ParsePosition pos) {
        return parser.parse(source, pos);
    }

    /*
     * (non-Javadoc)
     *
     * @see org.apache.commons.lang3.time.DateParser#parse(String, java.text.ParsePosition, java.util.Calendar)
     */
    @Override
    public boolean parse(final String source, final ParsePosition pos, final Calendar calendar) {
        return parser.parse(source, pos, calendar);
    }

    /*
     * (non-Javadoc)
     *
     * @see java.text.Format#parseObject(String, java.text.ParsePosition)
     */
    @Override
    public Object parseObject(final String source, final ParsePosition pos) {
        return parser.parseObject(source, pos);
    }

    /**
     * Gets a debugging string version of this formatter.
     *
     * @return A debug string.
     */
    @Override
    public String toString() {
        return "FastDateFormat[" + printer.getPattern() + "," + printer.getLocale() + "," + printer.getTimeZone().getID() + "]";
    }
}