/*

 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos

 *

 * All rights reserved.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions are met:

 *

 *  * Redistributions of source code must retain the above copyright notice,

 *    this list of conditions and the following disclaimer.

 *

 *  * Redistributions in binary form must reproduce the above copyright notice,

 *    this list of conditions and the following disclaimer in the documentation

 *    and/or other materials provided with the distribution.

 *

 *  * Neither the name of JSR-310 nor the names of its contributors

 *    may be used to endorse or promote products derived from this software

 *    without specific prior written permission.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

package java.time.chrono;

import java.io.DataInput;

import java.io.DataOutput;

import java.io.IOException;

import java.io.InvalidObjectException;

import java.io.ObjectStreamException;

import java.time.Clock;

import java.time.DateTimeException;

import java.time.Instant;

import java.time.LocalDate;

import java.time.LocalTime;

import java.time.ZoneId;

import java.time.chrono.HijrahChronology;

import java.time.chrono.JapaneseChronology;

import java.time.chrono.MinguoChronology;

import java.time.chrono.ThaiBuddhistChronology;

import java.time.format.DateTimeFormatterBuilder;

import java.time.format.TextStyle;

import java.time.temporal.ChronoField;

import java.time.temporal.Queries;

import java.time.temporal.Temporal;

import java.time.temporal.TemporalAccessor;

import java.time.temporal.TemporalField;

import java.time.temporal.TemporalQuery;

import java.time.temporal.ValueRange;

import java.util.HashSet;

import java.util.List;

import java.util.Locale;

import java.util.Objects;

import java.util.ServiceLoader;

import java.util.Set;

import java.util.concurrent.ConcurrentHashMap;

/**

 * A calendar system, used to organize and identify dates.

 * <p>

 * The main date and time API is built on the ISO calendar system.

 * This class operates behind the scenes to represent the general concept of a calendar system.

 * For example, the Japanese, Minguo, Thai Buddhist and others.

 * <p>

 * Most other calendar systems also operate on the shared concepts of year, month and day,

 * linked to the cycles of the Earth around the Sun, and the Moon around the Earth.

 * These shared concepts are defined by {@link ChronoField} and are available

 * for use by any {@code Chronology} implementation:

 * <pre>

 *   LocalDate isoDate = ...

 *   ChronoLocalDate<ThaiBuddhistChronology> thaiDate = ...

 *   int isoYear = isoDate.get(ChronoField.YEAR);

 *   int thaiYear = thaiDate.get(ChronoField.YEAR);

 * </pre>

 * As shown, although the date objects are in different calendar systems, represented by different

 * {@code Chronology} instances, both can be queried using the same constant on {@code ChronoField}.

 * For a full discussion of the implications of this, see {@link ChronoLocalDate}.

 * In general, the advice is to use the known ISO-based {@code LocalDate}, rather than

 * {@code ChronoLocalDate}.

 * <p>

 * While a {@code Chronology} object typically uses {@code ChronoField} and is based on

 * an era, year-of-era, month-of-year, day-of-month model of a date, this is not required.

 * A {@code Chronology} instance may represent a totally different kind of calendar system,

 * such as the Mayan.

 * <p>

 * In practical terms, the {@code Chronology} instance also acts as a factory.

 * The {@link #of(String)} method allows an instance to be looked up by identifier,

 * while the {@link #ofLocale(Locale)} method allows lookup by locale.

 * <p>

 * The {@code Chronology} instance provides a set of methods to create {@code ChronoLocalDate} instances.

 * The date classes are used to manipulate specific dates.

 * <p><ul>

 * <li> {@link #dateNow() dateNow()}

 * <li> {@link #dateNow(Clock) dateNow(clock)}

 * <li> {@link #dateNow(ZoneId) dateNow(zone)}

 * <li> {@link #date(int, int, int) date(yearProleptic, month, day)}

 * <li> {@link #date(Era, int, int, int) date(era, yearOfEra, month, day)}

 * <li> {@link #dateYearDay(int, int) dateYearDay(yearProleptic, dayOfYear)}

 * <li> {@link #dateYearDay(Era, int, int) dateYearDay(era, yearOfEra, dayOfYear)}

 * <li> {@link #date(TemporalAccessor) date(TemporalAccessor)}

 * </ul><p>

 *

 * <h3 id="addcalendars">Adding New Calendars</h3>

 * The set of available chronologies can be extended by applications.

 * Adding a new calendar system requires the writing of an implementation of

 * {@code Chronology}, {@code ChronoLocalDate} and {@code Era}.

 * The majority of the logic specific to the calendar system will be in

 * {@code ChronoLocalDate}. The {@code Chronology} subclass acts as a factory.

 * <p>

 * To permit the discovery of additional chronologies, the {@link java.util.ServiceLoader ServiceLoader}

 * is used. A file must be added to the {@code META-INF/services} directory with the

 * name 'java.time.chrono.Chronology' listing the implementation classes.

 * See the ServiceLoader for more details on service loading.

 * For lookup by id or calendarType, the system provided calendars are found

 * first followed by application provided calendars.

 * <p>

 * Each chronology must define a chronology ID that is unique within the system.

 * If the chronology represents a calendar system defined by the

 * <em>Unicode Locale Data Markup Language (LDML)</em> specification then that

 * calendar type should also be specified.

 *

 * <h3>Specification for implementors</h3>

 * This class must be implemented with care to ensure other classes operate correctly.

 * All implementations that can be instantiated must be final, immutable and thread-safe.

 * Subclasses should be Serializable wherever possible.

 *

 * @since 1.8

 */

public abstract class Chronology implements Comparable<Chronology> {

    /**

     * Map of available calendars by ID.

     */

    private static final ConcurrentHashMap<String, Chronology> CHRONOS_BY_ID = new ConcurrentHashMap<>();

    /**

     * Map of available calendars by calendar type.

     */

    private static final ConcurrentHashMap<String, Chronology> CHRONOS_BY_TYPE = new ConcurrentHashMap<>();

    /**

     * Register a Chronology by ID and type for lookup by {@link #of(java.lang.String)}.

     * Chronos must not be registered until they are completely constructed.

     * Specifically, not in the constructor of Chronology.

     * @param chrono the chronology to register; not null

     */

    private static void registerChrono(Chronology chrono) {

        Chronology prev = CHRONOS_BY_ID.putIfAbsent(chrono.getId(), chrono);

        if (prev == null) {

            String type = chrono.getCalendarType();

            if (type != null) {

                CHRONOS_BY_TYPE.putIfAbsent(type, chrono);

            }

        }

    }

    /**

     * Initialization of the maps from id and type to Chronology.

     * The ServiceLoader is used to find and register any implementations

     * of {@link java.time.chrono.Chronology} found in the bootclass loader.

     * The built-in chronologies are registered explicitly.

     * Calendars configured via the Thread's context classloader are local

     * to that thread and are ignored.

     * <p>

     * The initialization is done only once using the registration

     * of the IsoChronology as the test and the final step.

     * Multiple threads may perform the initialization concurrently.

     * Only the first registration of each Chronology is retained by the

     * ConcurrentHashMap.

     * @return true if the cache was initialized

     */

    private static boolean initCache() {

        if (CHRONOS_BY_ID.get("ISO") == null) {

            // Initialization is incomplete

            @SuppressWarnings("rawtypes")

            ServiceLoader<Chronology> loader =  ServiceLoader.load(Chronology.class, null);

            for (Chronology chrono : loader) {

                registerChrono(chrono);

            }

            // Register these calendars; the ServiceLoader configuration is not used

            registerChrono(HijrahChronology.INSTANCE);

            registerChrono(JapaneseChronology.INSTANCE);

            registerChrono(MinguoChronology.INSTANCE);

            registerChrono(ThaiBuddhistChronology.INSTANCE);

            // finally, register IsoChronology to mark initialization is complete

            registerChrono(IsoChronology.INSTANCE);

            return true;

        }

        return false;

    }

    //-----------------------------------------------------------------------

    /**

     * Obtains an instance of {@code Chronology} from a temporal object.

     * <p>

     * This obtains a chronology based on the specified temporal.

     * A {@code TemporalAccessor} represents an arbitrary set of date and time information,

     * which this factory converts to an instance of {@code Chronology}.

     * <p>

     * The conversion will obtain the chronology using {@link Queries#chronology()}.

     * If the specified temporal object does not have a chronology, {@link IsoChronology} is returned.

     * <p>

     * This method matches the signature of the functional interface {@link TemporalQuery}

     * allowing it to be used in queries via method reference, {@code Chronology::from}.

     *

     * @param temporal  the temporal to convert, not null

     * @return the chronology, not null

     * @throws DateTimeException if unable to convert to an {@code Chronology}

     */

    public static Chronology from(TemporalAccessor temporal) {

        Objects.requireNonNull(temporal, "temporal");

        Chronology obj = temporal.query(Queries.chronology());

        return (obj != null ? obj : IsoChronology.INSTANCE);

    }

    //-----------------------------------------------------------------------

    /**

     * Obtains an instance of {@code Chronology} from a locale.

     * <p>

     * This returns a {@code Chronology} based on the specified locale,

     * typically returning {@code IsoChronology}. Other calendar systems

     * are only returned if they are explicitly selected within the locale.

     * <p>

     * The {@link Locale} class provide access to a range of information useful

     * for localizing an application. This includes the language and region,

     * such as "en-GB" for English as used in Great Britain.

     * <p>

     * The {@code Locale} class also supports an extension mechanism that

     * can be used to identify a calendar system. The mechanism is a form

     * of key-value pairs, where the calendar system has the key "ca".

     * For example, the locale "en-JP-u-ca-japanese" represents the English

     * language as used in Japan with the Japanese calendar system.

     * <p>

     * This method finds the desired calendar system by in a manner equivalent

     * to passing "ca" to {@link Locale#getUnicodeLocaleType(String)}.

     * If the "ca" key is not present, then {@code IsoChronology} is returned.

     * <p>

     * Note that the behavior of this method differs from the older

     * {@link java.util.Calendar#getInstance(Locale)} method.

     * If that method receives a locale of "th_TH" it will return {@code BuddhistCalendar}.

     * By contrast, this method will return {@code IsoChronology}.

     * Passing the locale "th-TH-u-ca-buddhist" into either method will

     * result in the Thai Buddhist calendar system and is therefore the

     * recommended approach going forward for Thai calendar system localization.

     * <p>

     * A similar, but simpler, situation occurs for the Japanese calendar system.

     * The locale "jp_JP_JP" has previously been used to access the calendar.

     * However, unlike the Thai locale, "ja_JP_JP" is automatically converted by

     * {@code Locale} to the modern and recommended form of "ja-JP-u-ca-japanese".

     * Thus, there is no difference in behavior between this method and

     * {@code Calendar#getInstance(Locale)}.

     *

     * @param locale  the locale to use to obtain the calendar system, not null

     * @return the calendar system associated with the locale, not null

     * @throws DateTimeException if the locale-specified calendar cannot be found

     */

    public static Chronology ofLocale(Locale locale) {

        Objects.requireNonNull(locale, "locale");

        String type = locale.getUnicodeLocaleType("ca");

        if (type == null || "iso".equals(type) || "iso8601".equals(type)) {

            return IsoChronology.INSTANCE;

        }

        // Not pre-defined; lookup by the type

        do {

            Chronology chrono = CHRONOS_BY_TYPE.get(type);

            if (chrono != null) {

                return chrono;

            }

            // If not found, do the initialization (once) and repeat the lookup

        } while (initCache());

        throw new DateTimeException("Unknown calendar system: " + type);

    }

    //-----------------------------------------------------------------------

    /**

     * Obtains an instance of {@code Chronology} from a chronology ID or

     * calendar system type.

     * <p>

     * This returns a chronology based on either the ID or the type.

     * The {@link #getId() chronology ID} uniquely identifies the chronology.

     * The {@link #getCalendarType() calendar system type} is defined by the LDML specification.

     * <p>

     * The chronology may be a system chronology or a chronology

     * provided by the application via ServiceLoader configuration.

     * <p>

     * Since some calendars can be customized, the ID or type typically refers

     * to the default customization. For example, the Gregorian calendar can have multiple

     * cutover dates from the Julian, but the lookup only provides the default cutover date.

     *

     * @param id  the chronology ID or calendar system type, not null

     * @return the chronology with the identifier requested, not null

     * @throws DateTimeException if the chronology cannot be found

     */

    public static Chronology of(String id) {

        Objects.requireNonNull(id, "id");

        do {

            Chronology chrono = of0(id);

            if (chrono != null) {

                return chrono;

            }

            // If not found, do the initialization (once) and repeat the lookup

        } while (initCache());

        // Look for a Chronology using ServiceLoader of the Thread's ContextClassLoader

        // Application provided Chronologies must not be cached

        @SuppressWarnings("rawtypes")

        ServiceLoader<Chronology> loader = ServiceLoader.load(Chronology.class);

        for (Chronology chrono : loader) {

            if (id.equals(chrono.getId()) || id.equals(chrono.getCalendarType())) {

                return chrono;

            }

        }

        throw new DateTimeException("Unknown chronology: " + id);

    }

    /**

     * Obtains an instance of {@code Chronology} from a chronology ID or

     * calendar system type.

     *

     * @param id  the chronology ID or calendar system type, not null

     * @return the chronology with the identifier requested, or {@code null} if not found

     */

    private static Chronology of0(String id) {

        Chronology chrono = CHRONOS_BY_ID.get(id);

        if (chrono == null) {

            chrono = CHRONOS_BY_TYPE.get(id);

        }

        return chrono;

    }

    /**

     * Returns the available chronologies.

     * <p>

     * Each returned {@code Chronology} is available for use in the system.

     * The set of chronologies includes the system chronologies and

     * any chronologies provided by the application via ServiceLoader

     * configuration.

     *

     * @return the independent, modifiable set of the available chronology IDs, not null

     */

    public static Set<Chronology> getAvailableChronologies() {

        initCache();       // force initialization

        HashSet<Chronology> chronos = new HashSet(CHRONOS_BY_ID.values());

        /// Add in Chronologies from the ServiceLoader configuration

        @SuppressWarnings("rawtypes")

        ServiceLoader<Chronology> loader = ServiceLoader.load(Chronology.class);

        for (Chronology chrono : loader) {

            chronos.add(chrono);

        }

        return chronos;

    }

    //-----------------------------------------------------------------------

    /**

     * Creates an instance.

     */

    protected Chronology() {

    }

    //-----------------------------------------------------------------------

    /**

     * Casts the {@code Temporal} to {@code ChronoLocalDate} with the same chronology.

     *

     * @param temporal  a date-time to cast, not null

     * @return the date-time checked and cast to {@code ChronoLocalDate}, not null

     * @throws ClassCastException if the date-time cannot be cast to ChronoLocalDate

     *  or the chronology is not equal this Chronology

     */

    ChronoLocalDate ensureChronoLocalDate(Temporal temporal) {

        @SuppressWarnings("unchecked")

        ChronoLocalDate other = (ChronoLocalDate) temporal;

        if (this.equals(other.getChronology()) == false) {

            throw new ClassCastException("Chronology mismatch, expected: " + getId() + ", actual: " + other.getChronology().getId());

        }

        return other;

    }

    /**

     * Casts the {@code Temporal} to {@code ChronoLocalDateTime} with the same chronology.

     *

     * @param temporal   a date-time to cast, not null

     * @return the date-time checked and cast to {@code ChronoLocalDateTime}, not null

     * @throws ClassCastException if the date-time cannot be cast to ChronoLocalDateTimeImpl

     *  or the chronology is not equal this Chronology

     */

    ChronoLocalDateTimeImpl<?> ensureChronoLocalDateTime(Temporal temporal) {

        @SuppressWarnings("unchecked")

        ChronoLocalDateTimeImpl<?> other = (ChronoLocalDateTimeImpl<?>) temporal;

        if (this.equals(other.toLocalDate().getChronology()) == false) {

            throw new ClassCastException("Chronology mismatch, required: " + getId()

                    + ", supplied: " + other.toLocalDate().getChronology().getId());

        }

        return other;

    }

    /**

     * Casts the {@code Temporal} to {@code ChronoZonedDateTimeImpl} with the same chronology.

     *

     * @param temporal  a date-time to cast, not null

     * @return the date-time checked and cast to {@code ChronoZonedDateTimeImpl}, not null

     * @throws ClassCastException if the date-time cannot be cast to ChronoZonedDateTimeImpl

     *  or the chronology is not equal this Chronology

     */

    ChronoZonedDateTimeImpl<?> ensureChronoZonedDateTime(Temporal temporal) {

        @SuppressWarnings("unchecked")

        ChronoZonedDateTimeImpl<?> other = (ChronoZonedDateTimeImpl<?>) temporal;

        if (this.equals(other.toLocalDate().getChronology()) == false) {

            throw new ClassCastException("Chronology mismatch, required: " + getId()

                    + ", supplied: " + other.toLocalDate().getChronology().getId());

        }

        return other;

    }

    //-----------------------------------------------------------------------

    /**

     * Gets the ID of the chronology.

     * <p>

     * The ID uniquely identifies the {@code Chronology}.

     * It can be used to lookup the {@code Chronology} using {@link #of(String)}.

     *

     * @return the chronology ID, not null

     * @see #getCalendarType()

     */

    public abstract String getId();

    /**

     * Gets the calendar type of the underlying calendar system.

     * <p>

     * The calendar type is an identifier defined by the

     * <em>Unicode Locale Data Markup Language (LDML)</em> specification.

     * It can be used to lookup the {@code Chronology} using {@link #of(String)}.

     * It can also be used as part of a locale, accessible via

     * {@link Locale#getUnicodeLocaleType(String)} with the key 'ca'.

     *

     * @return the calendar system type, null if the calendar is not defined by LDML

     * @see #getId()

     */

    public abstract String getCalendarType();

    //-----------------------------------------------------------------------

    /**

     * Obtains a local date in this chronology from the era, year-of-era,

     * month-of-year and day-of-month fields.

     *

     * @param era  the era of the correct type for the chronology, not null

     * @param yearOfEra  the chronology year-of-era

     * @param month  the chronology month-of-year

     * @param dayOfMonth  the chronology day-of-month

     * @return the local date in this chronology, not null

     * @throws DateTimeException if unable to create the date

     */

    public ChronoLocalDate date(Era era, int yearOfEra, int month, int dayOfMonth) {

        return date(prolepticYear(era, yearOfEra), month, dayOfMonth);

    }

    /**

     * Obtains a local date in this chronology from the proleptic-year,

     * month-of-year and day-of-month fields.

     *

     * @param prolepticYear  the chronology proleptic-year

     * @param month  the chronology month-of-year

     * @param dayOfMonth  the chronology day-of-month

     * @return the local date in this chronology, not null

     * @throws DateTimeException if unable to create the date

     */

    public abstract ChronoLocalDate date(int prolepticYear, int month, int dayOfMonth);

    /**

     * Obtains a local date in this chronology from the era, year-of-era and

     * day-of-year fields.

     *

     * @param era  the era of the correct type for the chronology, not null

     * @param yearOfEra  the chronology year-of-era

     * @param dayOfYear  the chronology day-of-year

     * @return the local date in this chronology, not null

     * @throws DateTimeException if unable to create the date

     */

    public ChronoLocalDate dateYearDay(Era era, int yearOfEra, int dayOfYear) {

        return dateYearDay(prolepticYear(era, yearOfEra), dayOfYear);

    }

    /**

     * Obtains a local date in this chronology from the proleptic-year and

     * day-of-year fields.

     *

     * @param prolepticYear  the chronology proleptic-year

     * @param dayOfYear  the chronology day-of-year

     * @return the local date in this chronology, not null

     * @throws DateTimeException if unable to create the date