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 }