/*

 * Copyright (c) 2012, 2019, 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) 2007-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;

import static java.time.temporal.ChronoField.INSTANT_SECONDS;

import static java.time.temporal.ChronoField.NANO_OF_SECOND;

import static java.time.temporal.ChronoField.OFFSET_SECONDS;

import java.io.DataOutput;

import java.io.IOException;

import java.io.ObjectInput;

import java.io.InvalidObjectException;

import java.io.ObjectInputStream;

import java.io.Serializable;

import java.time.chrono.ChronoZonedDateTime;

import java.time.format.DateTimeFormatter;

import java.time.format.DateTimeParseException;

import java.time.temporal.ChronoField;

import java.time.temporal.ChronoUnit;

import java.time.temporal.Temporal;

import java.time.temporal.TemporalAccessor;

import java.time.temporal.TemporalAdjuster;

import java.time.temporal.TemporalAmount;

import java.time.temporal.TemporalField;

import java.time.temporal.TemporalQueries;

import java.time.temporal.TemporalQuery;

import java.time.temporal.TemporalUnit;

import java.time.temporal.UnsupportedTemporalTypeException;

import java.time.temporal.ValueRange;

import java.time.zone.ZoneOffsetTransition;

import java.time.zone.ZoneRules;

import java.util.List;

import java.util.Objects;

/**

 * A date-time with a time-zone in the ISO-8601 calendar system,

 * such as {@code 2007-12-03T10:15:30+01:00 Europe/Paris}.

 * <p>

 * {@code ZonedDateTime} is an immutable representation of a date-time with a time-zone.

 * This class stores all date and time fields, to a precision of nanoseconds,

 * and a time-zone, with a zone offset used to handle ambiguous local date-times.

 * For example, the value

 * "2nd October 2007 at 13:45.30.123456789 +02:00 in the Europe/Paris time-zone"

 * can be stored in a {@code ZonedDateTime}.

 * <p>

 * This class handles conversion from the local time-line of {@code LocalDateTime}

 * to the instant time-line of {@code Instant}.

 * The difference between the two time-lines is the offset from UTC/Greenwich,

 * represented by a {@code ZoneOffset}.

 * <p>

 * Converting between the two time-lines involves calculating the offset using the

 * {@link ZoneRules rules} accessed from the {@code ZoneId}.

 * Obtaining the offset for an instant is simple, as there is exactly one valid

 * offset for each instant. By contrast, obtaining the offset for a local date-time

 * is not straightforward. There are three cases:

 * <ul>

 * <li>Normal, with one valid offset. For the vast majority of the year, the normal

 *  case applies, where there is a single valid offset for the local date-time.</li>

 * <li>Gap, with zero valid offsets. This is when clocks jump forward typically

 *  due to the spring daylight savings change from "winter" to "summer".

 *  In a gap there are local date-time values with no valid offset.</li>

 * <li>Overlap, with two valid offsets. This is when clocks are set back typically

 *  due to the autumn daylight savings change from "summer" to "winter".

 *  In an overlap there are local date-time values with two valid offsets.</li>

 * </ul>

 * <p>

 * Any method that converts directly or implicitly from a local date-time to an

 * instant by obtaining the offset has the potential to be complicated.

 * <p>

 * For Gaps, the general strategy is that if the local date-time falls in the

 * middle of a Gap, then the resulting zoned date-time will have a local date-time

 * shifted forwards by the length of the Gap, resulting in a date-time in the later

 * offset, typically "summer" time.

 * <p>

 * For Overlaps, the general strategy is that if the local date-time falls in the

 * middle of an Overlap, then the previous offset will be retained. If there is no

 * previous offset, or the previous offset is invalid, then the earlier offset is

 * used, typically "summer" time.. Two additional methods,

 * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},

 * help manage the case of an overlap.

 * <p>

 * In terms of design, this class should be viewed primarily as the combination

 * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is

 * a vital, but secondary, piece of information, used to ensure that the class

 * represents an instant, especially during a daylight savings overlap.

 *

 * <p>

 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>

 * class; use of identity-sensitive operations (including reference equality

 * ({@code ==}), identity hash code, or synchronization) on instances of

 * {@code ZonedDateTime} may have unpredictable results and should be avoided.

 * The {@code equals} method should be used for comparisons.

 *

 * @implSpec

 * A {@code ZonedDateTime} holds state equivalent to three separate objects,

 * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.

 * The offset and local date-time are used to define an instant when necessary.

 * The zone ID is used to obtain the rules for how and when the offset changes.

 * The offset cannot be freely set, as the zone controls which offsets are valid.

 * <p>

 * This class is immutable and thread-safe.

 *

 * @since 1.8

 */

public final class ZonedDateTime

        implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {

    /**

     * Serialization version.

     */

    @java.io.Serial

    private static final long serialVersionUID = -6260982410461394882L;

    /**

     * The local date-time.

     */

    private final LocalDateTime dateTime;

    /**

     * The offset from UTC/Greenwich.

     */

    private final ZoneOffset offset;

    /**

     * The time-zone.

     */

    private final ZoneId zone;

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

    /**

     * Obtains the current date-time from the system clock in the default time-zone.

     * <p>

     * This will query the {@link Clock#systemDefaultZone() system clock} in the default

     * time-zone to obtain the current date-time.

     * The zone and offset will be set based on the time-zone in the clock.

     * <p>

     * Using this method will prevent the ability to use an alternate clock for testing

     * because the clock is hard-coded.

     *

     * @return the current date-time using the system clock, not null

     */

    public static ZonedDateTime now() {

        return now(Clock.systemDefaultZone());

    }

    /**

     * Obtains the current date-time from the system clock in the specified time-zone.

     * <p>

     * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date-time.

     * Specifying the time-zone avoids dependence on the default time-zone.

     * The offset will be calculated from the specified time-zone.

     * <p>

     * Using this method will prevent the ability to use an alternate clock for testing

     * because the clock is hard-coded.

     *

     * @param zone  the zone ID to use, not null

     * @return the current date-time using the system clock, not null

     */

    public static ZonedDateTime now(ZoneId zone) {

        return now(Clock.system(zone));

    }

    /**

     * Obtains the current date-time from the specified clock.

     * <p>

     * This will query the specified clock to obtain the current date-time.

     * The zone and offset will be set based on the time-zone in the clock.

     * <p>

     * Using this method allows the use of an alternate clock for testing.

     * The alternate clock may be introduced using {@link Clock dependency injection}.

     *

     * @param clock  the clock to use, not null

     * @return the current date-time, not null

     */

    public static ZonedDateTime now(Clock clock) {

        Objects.requireNonNull(clock, "clock");

        final Instant now = clock.instant();  // called once

        return ofInstant(now, clock.getZone());

    }

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

    /**

     * Obtains an instance of {@code ZonedDateTime} from a local date and time.

     * <p>

     * This creates a zoned date-time matching the input local date and time as closely as possible.

     * Time-zone rules, such as daylight savings, mean that not every local date-time

     * is valid for the specified zone, thus the local date-time may be adjusted.

     * <p>

     * The local date time and first combined to form a local date-time.

     * The local date-time is then resolved to a single instant on the time-line.

     * This is achieved by finding a valid offset from UTC/Greenwich for the local

     * date-time as defined by the {@link ZoneRules rules} of the zone ID.

     *<p>

     * In most cases, there is only one valid offset for a local date-time.

     * In the case of an overlap, when clocks are set back, there are two valid offsets.

     * This method uses the earlier offset typically corresponding to "summer".

     * <p>

     * In the case of a gap, when clocks jump forward, there is no valid offset.

     * Instead, the local date-time is adjusted to be later by the length of the gap.

     * For a typical one hour daylight savings change, the local date-time will be

     * moved one hour later into the offset typically corresponding to "summer".

     *

     * @param date  the local date, not null

     * @param time  the local time, not null

     * @param zone  the time-zone, not null

     * @return the offset date-time, not null

     */

    public static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone) {

        return of(LocalDateTime.of(date, time), zone);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} from a local date-time.

     * <p>

     * This creates a zoned date-time matching the input local date-time as closely as possible.

     * Time-zone rules, such as daylight savings, mean that not every local date-time

     * is valid for the specified zone, thus the local date-time may be adjusted.

     * <p>

     * The local date-time is resolved to a single instant on the time-line.

     * This is achieved by finding a valid offset from UTC/Greenwich for the local

     * date-time as defined by the {@link ZoneRules rules} of the zone ID.

     *<p>

     * In most cases, there is only one valid offset for a local date-time.

     * In the case of an overlap, when clocks are set back, there are two valid offsets.

     * This method uses the earlier offset typically corresponding to "summer".

     * <p>

     * In the case of a gap, when clocks jump forward, there is no valid offset.

     * Instead, the local date-time is adjusted to be later by the length of the gap.

     * For a typical one hour daylight savings change, the local date-time will be

     * moved one hour later into the offset typically corresponding to "summer".

     *

     * @param localDateTime  the local date-time, not null

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     */

    public static ZonedDateTime of(LocalDateTime localDateTime, ZoneId zone) {

        return ofLocal(localDateTime, zone, null);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} from a year, month, day,

     * hour, minute, second, nanosecond and time-zone.

     * <p>

     * This creates a zoned date-time matching the local date-time of the seven

     * specified fields as closely as possible.

     * Time-zone rules, such as daylight savings, mean that not every local date-time

     * is valid for the specified zone, thus the local date-time may be adjusted.

     * <p>

     * The local date-time is resolved to a single instant on the time-line.

     * This is achieved by finding a valid offset from UTC/Greenwich for the local

     * date-time as defined by the {@link ZoneRules rules} of the zone ID.

     *<p>

     * In most cases, there is only one valid offset for a local date-time.

     * In the case of an overlap, when clocks are set back, there are two valid offsets.

     * This method uses the earlier offset typically corresponding to "summer".

     * <p>

     * In the case of a gap, when clocks jump forward, there is no valid offset.

     * Instead, the local date-time is adjusted to be later by the length of the gap.

     * For a typical one hour daylight savings change, the local date-time will be

     * moved one hour later into the offset typically corresponding to "summer".

     * <p>

     * This method exists primarily for writing test cases.

     * Non test-code will typically use other methods to create an offset time.

     * {@code LocalDateTime} has five additional convenience variants of the

     * equivalent factory method taking fewer arguments.

     * They are not provided here to reduce the footprint of the API.

     *

     * @param year  the year to represent, from MIN_YEAR to MAX_YEAR

     * @param month  the month-of-year to represent, from 1 (January) to 12 (December)

     * @param dayOfMonth  the day-of-month to represent, from 1 to 31

     * @param hour  the hour-of-day to represent, from 0 to 23

     * @param minute  the minute-of-hour to represent, from 0 to 59

     * @param second  the second-of-minute to represent, from 0 to 59

     * @param nanoOfSecond  the nano-of-second to represent, from 0 to 999,999,999

     * @param zone  the time-zone, not null

     * @return the offset date-time, not null

     * @throws DateTimeException if the value of any field is out of range, or

     *  if the day-of-month is invalid for the month-year

     */

    public static ZonedDateTime of(

            int year, int month, int dayOfMonth,

            int hour, int minute, int second, int nanoOfSecond, ZoneId zone) {

        LocalDateTime dt = LocalDateTime.of(year, month, dayOfMonth, hour, minute, second, nanoOfSecond);

        return ofLocal(dt, zone, null);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} from a local date-time

     * using the preferred offset if possible.

     * <p>

     * The local date-time is resolved to a single instant on the time-line.

     * This is achieved by finding a valid offset from UTC/Greenwich for the local

     * date-time as defined by the {@link ZoneRules rules} of the zone ID.

     *<p>

     * In most cases, there is only one valid offset for a local date-time.

     * In the case of an overlap, where clocks are set back, there are two valid offsets.

     * If the preferred offset is one of the valid offsets then it is used.

     * Otherwise the earlier valid offset is used, typically corresponding to "summer".

     * <p>

     * In the case of a gap, where clocks jump forward, there is no valid offset.

     * Instead, the local date-time is adjusted to be later by the length of the gap.

     * For a typical one hour daylight savings change, the local date-time will be

     * moved one hour later into the offset typically corresponding to "summer".

     *

     * @param localDateTime  the local date-time, not null

     * @param zone  the time-zone, not null

     * @param preferredOffset  the zone offset, null if no preference

     * @return the zoned date-time, not null

     */

    public static ZonedDateTime ofLocal(LocalDateTime localDateTime, ZoneId zone, ZoneOffset preferredOffset) {

        Objects.requireNonNull(localDateTime, "localDateTime");

        Objects.requireNonNull(zone, "zone");

        if (zone instanceof ZoneOffset) {

            return new ZonedDateTime(localDateTime, (ZoneOffset) zone, zone);

        }

        ZoneRules rules = zone.getRules();

        List<ZoneOffset> validOffsets = rules.getValidOffsets(localDateTime);

        ZoneOffset offset;

        if (validOffsets.size() == 1) {

            offset = validOffsets.get(0);

        } else if (validOffsets.size() == 0) {

            ZoneOffsetTransition trans = rules.getTransition(localDateTime);

            localDateTime = localDateTime.plusSeconds(trans.getDuration().getSeconds());

            offset = trans.getOffsetAfter();

        } else {

            if (preferredOffset != null && validOffsets.contains(preferredOffset)) {

                offset = preferredOffset;

            } else {

                offset = Objects.requireNonNull(validOffsets.get(0), "offset");  // protect against bad ZoneRules

            }

        }

        return new ZonedDateTime(localDateTime, offset, zone);

    }

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

    /**

     * Obtains an instance of {@code ZonedDateTime} from an {@code Instant}.

     * <p>

     * This creates a zoned date-time with the same instant as that specified.

     * Calling {@link #toInstant()} will return an instant equal to the one used here.

     * <p>

     * Converting an instant to a zoned date-time is simple as there is only one valid

     * offset for each instant.

     *

     * @param instant  the instant to create the date-time from, not null

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     * @throws DateTimeException if the result exceeds the supported range

     */

    public static ZonedDateTime ofInstant(Instant instant, ZoneId zone) {

        Objects.requireNonNull(instant, "instant");

        Objects.requireNonNull(zone, "zone");

        return create(instant.getEpochSecond(), instant.getNano(), zone);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} from the instant formed by combining

     * the local date-time and offset.

     * <p>

     * This creates a zoned date-time by {@link LocalDateTime#toInstant(ZoneOffset) combining}

     * the {@code LocalDateTime} and {@code ZoneOffset}.

     * This combination uniquely specifies an instant without ambiguity.

     * <p>

     * Converting an instant to a zoned date-time is simple as there is only one valid

     * offset for each instant. If the valid offset is different to the offset specified,

     * then the date-time and offset of the zoned date-time will differ from those specified.

     * <p>

     * If the {@code ZoneId} to be used is a {@code ZoneOffset}, this method is equivalent

     * to {@link #of(LocalDateTime, ZoneId)}.

     *

     * @param localDateTime  the local date-time, not null

     * @param offset  the zone offset, not null

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     */

    public static ZonedDateTime ofInstant(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone) {

        Objects.requireNonNull(localDateTime, "localDateTime");

        Objects.requireNonNull(offset, "offset");

        Objects.requireNonNull(zone, "zone");

        if (zone.getRules().isValidOffset(localDateTime, offset)) {

            return new ZonedDateTime(localDateTime, offset, zone);

        }

        return create(localDateTime.toEpochSecond(offset), localDateTime.getNano(), zone);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} using seconds from the

     * epoch of 1970-01-01T00:00:00Z.

     *

     * @param epochSecond  the number of seconds from the epoch of 1970-01-01T00:00:00Z

     * @param nanoOfSecond  the nanosecond within the second, from 0 to 999,999,999

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     * @throws DateTimeException if the result exceeds the supported range

     */

    private static ZonedDateTime create(long epochSecond, int nanoOfSecond, ZoneId zone) {

        ZoneRules rules = zone.getRules();

        Instant instant = Instant.ofEpochSecond(epochSecond, nanoOfSecond);  // TODO: rules should be queryable by epochSeconds

        ZoneOffset offset = rules.getOffset(instant);

        LocalDateTime ldt = LocalDateTime.ofEpochSecond(epochSecond, nanoOfSecond, offset);

        return new ZonedDateTime(ldt, offset, zone);

    }

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

    /**

     * Obtains an instance of {@code ZonedDateTime} strictly validating the

     * combination of local date-time, offset and zone ID.

     * <p>

     * This creates a zoned date-time ensuring that the offset is valid for the

     * local date-time according to the rules of the specified zone.

     * If the offset is invalid, an exception is thrown.

     *

     * @param localDateTime  the local date-time, not null

     * @param offset  the zone offset, not null

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     * @throws DateTimeException if the combination of arguments is invalid

     */

    public static ZonedDateTime ofStrict(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone) {

        Objects.requireNonNull(localDateTime, "localDateTime");

        Objects.requireNonNull(offset, "offset");

        Objects.requireNonNull(zone, "zone");

        ZoneRules rules = zone.getRules();

        if (rules.isValidOffset(localDateTime, offset) == false) {

            ZoneOffsetTransition trans = rules.getTransition(localDateTime);

            if (trans != null && trans.isGap()) {

                // error message says daylight savings for simplicity

                // even though there are other kinds of gaps

                throw new DateTimeException("LocalDateTime '" + localDateTime +

                        "' does not exist in zone '" + zone +

                        "' due to a gap in the local time-line, typically caused by daylight savings");

            }

            throw new DateTimeException("ZoneOffset '" + offset + "' is not valid for LocalDateTime '" +

                    localDateTime + "' in zone '" + zone + "'");

        }

        return new ZonedDateTime(localDateTime, offset, zone);

    }

    /**

     * Obtains an instance of {@code ZonedDateTime} leniently, for advanced use cases,

     * allowing any combination of local date-time, offset and zone ID.

     * <p>

     * This creates a zoned date-time with no checks other than no nulls.

     * This means that the resulting zoned date-time may have an offset that is in conflict

     * with the zone ID.

     * <p>

     * This method is intended for advanced use cases.

     * For example, consider the case where a zoned date-time with valid fields is created

     * and then stored in a database or serialization-based store. At some later point,

     * the object is then re-loaded. However, between those points in time, the government

     * that defined the time-zone has changed the rules, such that the originally stored

     * local date-time now does not occur. This method can be used to create the object

     * in an "invalid" state, despite the change in rules.

     *

     * @param localDateTime  the local date-time, not null

     * @param offset  the zone offset, not null

     * @param zone  the time-zone, not null

     * @return the zoned date-time, not null

     */

    private static ZonedDateTime ofLenient(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone) {

        Objects.requireNonNull(localDateTime, "localDateTime");

        Objects.requireNonNull(offset, "offset");