1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file:
  31  *
  32  * Copyright (c) 2009-2012, Stephen Colebourne & Michael Nascimento Santos
  33  *
  34  * All rights reserved.
  35  *
  36  * Redistribution and use in source and binary forms, with or without
  37  * modification, are permitted provided that the following conditions are met:
  38  *
  39  *  * Redistributions of source code must retain the above copyright notice,
  40  *    this list of conditions and the following disclaimer.
  41  *
  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  45  *
  46  *  * Neither the name of JSR-310 nor the names of its contributors
  47  *    may be used to endorse or promote products derived from this software
  48  *    without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  61  */
  62 package java.time.zone;
  63 
  64 import java.io.DataInput;
  65 import java.io.DataOutput;
  66 import java.io.IOException;
  67 import java.io.InvalidObjectException;
  68 import java.io.ObjectInputStream;
  69 import java.io.Serializable;
  70 import java.time.Duration;
  71 import java.time.Instant;
  72 import java.time.LocalDateTime;
  73 import java.time.ZoneOffset;
  74 import java.util.Arrays;
  75 import java.util.Collections;
  76 import java.util.List;
  77 import java.util.Objects;
  78 
  79 /**
  80  * A transition between two offsets caused by a discontinuity in the local time-line.
  81  * <p>
  82  * A transition between two offsets is normally the result of a daylight savings cutover.
  83  * The discontinuity is normally a gap in spring and an overlap in autumn.
  84  * {@code ZoneOffsetTransition} models the transition between the two offsets.
  85  * <p>
  86  * Gaps occur where there are local date-times that simply do not exist.
  87  * An example would be when the offset changes from {@code +03:00} to {@code +04:00}.
  88  * This might be described as 'the clocks will move forward one hour tonight at 1am'.
  89  * <p>
  90  * Overlaps occur where there are local date-times that exist twice.
  91  * An example would be when the offset changes from {@code +04:00} to {@code +03:00}.
  92  * This might be described as 'the clocks will move back one hour tonight at 2am'.
  93  *
  94  * @implSpec
  95  * This class is immutable and thread-safe.
  96  *
  97  * @since 1.8
  98  */
  99 public final class ZoneOffsetTransition
 100         implements Comparable<ZoneOffsetTransition>, Serializable {
 101 
 102     /**
 103      * Serialization version.
 104      */
 105     private static final long serialVersionUID = -6946044323557704546L;
 106     /**
 107      * The transition epoch-second.
 108      */
 109     private final long epochSecond;
 110     /**
 111      * The local transition date-time at the transition.
 112      */
 113     private final LocalDateTime transition;
 114     /**
 115      * The offset before transition.
 116      */
 117     private final ZoneOffset offsetBefore;
 118     /**
 119      * The offset after transition.
 120      */
 121     private final ZoneOffset offsetAfter;
 122 
 123     //-----------------------------------------------------------------------
 124     /**
 125      * Obtains an instance defining a transition between two offsets.
 126      * <p>
 127      * Applications should normally obtain an instance from {@link ZoneRules}.
 128      * This factory is only intended for use when creating {@link ZoneRules}.
 129      *
 130      * @param transition  the transition date-time at the transition, which never
 131      *  actually occurs, expressed local to the before offset, not null
 132      * @param offsetBefore  the offset before the transition, not null
 133      * @param offsetAfter  the offset at and after the transition, not null
 134      * @return the transition, not null
 135      * @throws IllegalArgumentException if {@code offsetBefore} and {@code offsetAfter}
 136      *         are equal, or {@code transition.getNano()} returns non-zero value
 137      */
 138     public static ZoneOffsetTransition of(LocalDateTime transition, ZoneOffset offsetBefore, ZoneOffset offsetAfter) {
 139         Objects.requireNonNull(transition, "transition");
 140         Objects.requireNonNull(offsetBefore, "offsetBefore");
 141         Objects.requireNonNull(offsetAfter, "offsetAfter");
 142         if (offsetBefore.equals(offsetAfter)) {
 143             throw new IllegalArgumentException("Offsets must not be equal");
 144         }
 145         if (transition.getNano() != 0) {
 146             throw new IllegalArgumentException("Nano-of-second must be zero");
 147         }
 148         return new ZoneOffsetTransition(transition, offsetBefore, offsetAfter);
 149     }
 150 
 151     /**
 152      * Creates an instance defining a transition between two offsets.
 153      *
 154      * @param transition  the transition date-time with the offset before the transition, not null
 155      * @param offsetBefore  the offset before the transition, not null
 156      * @param offsetAfter  the offset at and after the transition, not null
 157      */
 158     ZoneOffsetTransition(LocalDateTime transition, ZoneOffset offsetBefore, ZoneOffset offsetAfter) {
 159         this.epochSecond = transition.toEpochSecond(offsetBefore);
 160         this.transition = transition;
 161         this.offsetBefore = offsetBefore;
 162         this.offsetAfter = offsetAfter;
 163     }
 164 
 165     /**
 166      * Creates an instance from epoch-second and offsets.
 167      *
 168      * @param epochSecond  the transition epoch-second
 169      * @param offsetBefore  the offset before the transition, not null
 170      * @param offsetAfter  the offset at and after the transition, not null
 171      */
 172     ZoneOffsetTransition(long epochSecond, ZoneOffset offsetBefore, ZoneOffset offsetAfter) {
 173         this.epochSecond = epochSecond;
 174         this.transition = LocalDateTime.ofEpochSecond(epochSecond, 0, offsetBefore);
 175         this.offsetBefore = offsetBefore;
 176         this.offsetAfter = offsetAfter;
 177     }
 178 
 179     //-----------------------------------------------------------------------
 180     /**
 181      * Defend against malicious streams.
 182      *
 183      * @param s the stream to read
 184      * @throws InvalidObjectException always
 185      */
 186     private void readObject(ObjectInputStream s) throws InvalidObjectException {
 187         throw new InvalidObjectException("Deserialization via serialization delegate");
 188     }
 189 
 190     /**
 191      * Writes the object using a
 192      * <a href="../../../serialized-form.html#java.time.zone.Ser">dedicated serialized form</a>.
 193      * @serialData
 194      * Refer to the serialized form of
 195      * <a href="../../../serialized-form.html#java.time.zone.ZoneRules">ZoneRules.writeReplace</a>
 196      * for the encoding of epoch seconds and offsets.
 197      * <pre style="font-size:1.0em">{@code
 198      *
 199      *   out.writeByte(2);                // identifies a ZoneOffsetTransition
 200      *   out.writeEpochSec(toEpochSecond);
 201      *   out.writeOffset(offsetBefore);
 202      *   out.writeOffset(offsetAfter);
 203      * }
 204      * </pre>
 205      * @return the replacing object, not null
 206      */
 207     private Object writeReplace() {
 208         return new Ser(Ser.ZOT, this);
 209     }
 210 
 211     /**
 212      * Writes the state to the stream.
 213      *
 214      * @param out  the output stream, not null
 215      * @throws IOException if an error occurs
 216      */
 217     void writeExternal(DataOutput out) throws IOException {
 218         Ser.writeEpochSec(epochSecond, out);
 219         Ser.writeOffset(offsetBefore, out);
 220         Ser.writeOffset(offsetAfter, out);
 221     }
 222 
 223     /**
 224      * Reads the state from the stream.
 225      *
 226      * @param in  the input stream, not null
 227      * @return the created object, not null
 228      * @throws IOException if an error occurs
 229      */
 230     static ZoneOffsetTransition readExternal(DataInput in) throws IOException {
 231         long epochSecond = Ser.readEpochSec(in);
 232         ZoneOffset before = Ser.readOffset(in);
 233         ZoneOffset after = Ser.readOffset(in);
 234         if (before.equals(after)) {
 235             throw new IllegalArgumentException("Offsets must not be equal");
 236         }
 237         return new ZoneOffsetTransition(epochSecond, before, after);
 238     }
 239 
 240     //-----------------------------------------------------------------------
 241     /**
 242      * Gets the transition instant.
 243      * <p>
 244      * This is the instant of the discontinuity, which is defined as the first
 245      * instant that the 'after' offset applies.
 246      * <p>
 247      * The methods {@link #getInstant()}, {@link #getDateTimeBefore()} and {@link #getDateTimeAfter()}
 248      * all represent the same instant.
 249      *
 250      * @return the transition instant, not null
 251      */
 252     public Instant getInstant() {
 253         return transition.toInstant(offsetBefore);
 254     }
 255 
 256     /**
 257      * Gets the transition instant as an epoch second.
 258      *
 259      * @return the transition epoch second
 260      */
 261     public long toEpochSecond() {
 262         return epochSecond;
 263     }
 264 
 265     //-------------------------------------------------------------------------
 266     /**
 267      * Gets the local transition date-time, as would be expressed with the 'before' offset.
 268      * <p>
 269      * This is the date-time where the discontinuity begins expressed with the 'before' offset.
 270      * At this instant, the 'after' offset is actually used, therefore the combination of this
 271      * date-time and the 'before' offset will never occur.
 272      * <p>
 273      * The combination of the 'before' date-time and offset represents the same instant
 274      * as the 'after' date-time and offset.
 275      *
 276      * @return the transition date-time expressed with the before offset, not null
 277      */
 278     public LocalDateTime getDateTimeBefore() {
 279         return transition;
 280     }
 281 
 282     /**
 283      * Gets the local transition date-time, as would be expressed with the 'after' offset.
 284      * <p>
 285      * This is the first date-time after the discontinuity, when the new offset applies.
 286      * <p>
 287      * The combination of the 'before' date-time and offset represents the same instant
 288      * as the 'after' date-time and offset.
 289      *
 290      * @return the transition date-time expressed with the after offset, not null
 291      */
 292     public LocalDateTime getDateTimeAfter() {
 293         return transition.plusSeconds(getDurationSeconds());
 294     }
 295 
 296     /**
 297      * Gets the offset before the transition.
 298      * <p>
 299      * This is the offset in use before the instant of the transition.
 300      *
 301      * @return the offset before the transition, not null
 302      */
 303     public ZoneOffset getOffsetBefore() {
 304         return offsetBefore;
 305     }
 306 
 307     /**
 308      * Gets the offset after the transition.
 309      * <p>
 310      * This is the offset in use on and after the instant of the transition.
 311      *
 312      * @return the offset after the transition, not null
 313      */
 314     public ZoneOffset getOffsetAfter() {
 315         return offsetAfter;
 316     }
 317 
 318     /**
 319      * Gets the duration of the transition.
 320      * <p>
 321      * In most cases, the transition duration is one hour, however this is not always the case.
 322      * The duration will be positive for a gap and negative for an overlap.
 323      * Time-zones are second-based, so the nanosecond part of the duration will be zero.
 324      *
 325      * @return the duration of the transition, positive for gaps, negative for overlaps
 326      */
 327     public Duration getDuration() {
 328         return Duration.ofSeconds(getDurationSeconds());
 329     }
 330 
 331     /**
 332      * Gets the duration of the transition in seconds.
 333      *
 334      * @return the duration in seconds
 335      */
 336     private int getDurationSeconds() {
 337         return getOffsetAfter().getTotalSeconds() - getOffsetBefore().getTotalSeconds();
 338     }
 339 
 340     /**
 341      * Does this transition represent a gap in the local time-line.
 342      * <p>
 343      * Gaps occur where there are local date-times that simply do not exist.
 344      * An example would be when the offset changes from {@code +01:00} to {@code +02:00}.
 345      * This might be described as 'the clocks will move forward one hour tonight at 1am'.
 346      *
 347      * @return true if this transition is a gap, false if it is an overlap
 348      */
 349     public boolean isGap() {
 350         return getOffsetAfter().getTotalSeconds() > getOffsetBefore().getTotalSeconds();
 351     }
 352 
 353     /**
 354      * Does this transition represent an overlap in the local time-line.
 355      * <p>
 356      * Overlaps occur where there are local date-times that exist twice.
 357      * An example would be when the offset changes from {@code +02:00} to {@code +01:00}.
 358      * This might be described as 'the clocks will move back one hour tonight at 2am'.
 359      *
 360      * @return true if this transition is an overlap, false if it is a gap
 361      */
 362     public boolean isOverlap() {
 363         return getOffsetAfter().getTotalSeconds() < getOffsetBefore().getTotalSeconds();
 364     }
 365 
 366     /**
 367      * Checks if the specified offset is valid during this transition.
 368      * <p>
 369      * This checks to see if the given offset will be valid at some point in the transition.
 370      * A gap will always return false.
 371      * An overlap will return true if the offset is either the before or after offset.
 372      *
 373      * @param offset  the offset to check, null returns false
 374      * @return true if the offset is valid during the transition
 375      */
 376     public boolean isValidOffset(ZoneOffset offset) {
 377         return isGap() ? false : (getOffsetBefore().equals(offset) || getOffsetAfter().equals(offset));
 378     }
 379 
 380     /**
 381      * Gets the valid offsets during this transition.
 382      * <p>
 383      * A gap will return an empty list, while an overlap will return both offsets.
 384      *
 385      * @return the list of valid offsets
 386      */
 387     List<ZoneOffset> getValidOffsets() {
 388         if (isGap()) {
 389             return Collections.emptyList();
 390         }
 391         return Arrays.asList(getOffsetBefore(), getOffsetAfter());
 392     }
 393 
 394     //-----------------------------------------------------------------------
 395     /**
 396      * Compares this transition to another based on the transition instant.
 397      * <p>
 398      * This compares the instants of each transition.
 399      * The offsets are ignored, making this order inconsistent with equals.
 400      *
 401      * @param transition  the transition to compare to, not null
 402      * @return the comparator value, negative if less, positive if greater
 403      */
 404     @Override
 405     public int compareTo(ZoneOffsetTransition transition) {
 406         if (epochSecond < transition.epochSecond) {
 407             return -1;
 408         } else if (epochSecond > transition.epochSecond) {
 409             return 1;
 410         } else {
 411             return this.getInstant().compareTo(transition.getInstant());
 412         }
 413     }
 414 
 415     //-----------------------------------------------------------------------
 416     /**
 417      * Checks if this object equals another.
 418      * <p>
 419      * The entire state of the object is compared.
 420      *
 421      * @param other  the other object to compare to, null returns false
 422      * @return true if equal
 423      */
 424     @Override
 425     public boolean equals(Object other) {
 426         if (other == this) {
 427             return true;
 428         }
 429         if (other instanceof ZoneOffsetTransition) {
 430             ZoneOffsetTransition d = (ZoneOffsetTransition) other;
 431             return epochSecond == d.epochSecond &&
 432                 transition.equals(d.transition) &&
 433                 offsetBefore.equals(d.offsetBefore) && offsetAfter.equals(d.offsetAfter);
 434         }
 435         return false;
 436     }
 437 
 438     /**
 439      * Returns a suitable hash code.
 440      *
 441      * @return the hash code
 442      */
 443     @Override
 444     public int hashCode() {
 445         return transition.hashCode() ^ offsetBefore.hashCode() ^ Integer.rotateLeft(offsetAfter.hashCode(), 16);
 446     }
 447 
 448     //-----------------------------------------------------------------------
 449     /**
 450      * Returns a string describing this object.
 451      *
 452      * @return a string for debugging, not null
 453      */
 454     @Override
 455     public String toString() {
 456         StringBuilder buf = new StringBuilder();
 457         buf.append("Transition[")
 458             .append(isGap() ? "Gap" : "Overlap")
 459             .append(" at ")
 460             .append(transition)
 461             .append(offsetBefore)
 462             .append(" to ")
 463             .append(offsetAfter)
 464             .append(']');
 465         return buf.toString();
 466     }
 467 
 468 }
--- EOF ---