1 /*
2 * Copyright (c) 2000, 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 package sun.util.calendar;
27
28 import java.io.IOException;
29 import java.io.ObjectInputStream;
30 import java.util.Date;
31 import java.util.Map;
32 import java.util.SimpleTimeZone;
33 import java.util.TimeZone;
34
35 /**
36 * <code>ZoneInfo</code> is an implementation subclass of {@link
37 * java.util.TimeZone TimeZone} that represents GMT offsets and
38 * daylight saving time transitions of a time zone.
39 * <p>
40 * The daylight saving time transitions are described in the {@link
41 * #transitions transitions} table consisting of a chronological
42 * sequence of transitions of GMT offset and/or daylight saving time
43 * changes. Since all transitions are represented in UTC, in theory,
44 * <code>ZoneInfo</code> can be used with any calendar systems except
45 * for the {@link #getOffset(int,int,int,int,int,int) getOffset}
46 * method that takes Gregorian calendar date fields.
47 * <p>
48 * This table covers transitions from 1900 until 2037 (as of version
49 * 1.4), Before 1900, it assumes that there was no daylight saving
50 * time and the <code>getOffset</code> methods always return the
51 * {@link #getRawOffset} value. No Local Mean Time is supported. If a
52 * specified date is beyond the transition table and this time zone is
53 * supposed to observe daylight saving time in 2037, it delegates
54 * operations to a {@link java.util.SimpleTimeZone SimpleTimeZone}
55 * object created using the daylight saving time schedule as of 2037.
56 * <p>
57 * The date items, transitions, GMT offset(s), etc. are read from a database
58 * file. See {@link ZoneInfoFile} for details.
59 * @see java.util.SimpleTimeZone
60 * @since 1.4
61 */
62
63 public class ZoneInfo extends TimeZone {
64
65 private static final int UTC_TIME = 0;
66 private static final int STANDARD_TIME = 1;
67 private static final int WALL_TIME = 2;
68
69 private static final long OFFSET_MASK = 0x0fL;
70 private static final long DST_MASK = 0xf0L;
71 private static final int DST_NSHIFT = 4;
72 // this bit field is reserved for abbreviation support
73 private static final long ABBR_MASK = 0xf00L;
74 private static final int TRANSITION_NSHIFT = 12;
75
76 /**
77 * The raw GMT offset in milliseconds between this zone and GMT.
78 * Negative offsets are to the west of Greenwich. To obtain local
79 * <em>standard</em> time, add the offset to GMT time.
80 * @serial
81 */
82 private int rawOffset;
83
84 /**
85 * Difference in milliseconds from the original GMT offset in case
86 * the raw offset value has been modified by calling {@link
87 * #setRawOffset}. The initial value is 0.
88 * @serial
89 */
90 private int rawOffsetDiff = 0;
91
92 /**
93 * A CRC32 value of all pairs of transition time (in milliseconds
94 * in <code>long</code>) in local time and its GMT offset (in
95 * seconds in <code>int</code>) in the chronological order. Byte
96 * values of each <code>long</code> and <code>int</code> are taken
97 * in the big endian order (i.e., MSB to LSB).
98 * @serial
99 */
100 private int checksum;
101
102 /**
103 * The amount of time in milliseconds saved during daylight saving
104 * time. If <code>useDaylight</code> is false, this value is 0.
105 * @serial
106 */
107 private int dstSavings;
108
109 /**
110 * This array describes transitions of GMT offsets of this time
111 * zone, including both raw offset changes and daylight saving
112 * time changes.
113 * A long integer consists of four bit fields.
114 * <ul>
115 * <li>The most significant 52-bit field represents transition
116 * time in milliseconds from Gregorian January 1 1970, 00:00:00
117 * GMT.</li>
118 * <li>The next 4-bit field is reserved and must be 0.</li>
119 * <li>The next 4-bit field is an index value to {@link #offsets
120 * offsets[]} for the amount of daylight saving at the
121 * transition. If this value is zero, it means that no daylight
122 * saving, not the index value zero.</li>
123 * <li>The least significant 4-bit field is an index value to
124 * {@link #offsets offsets[]} for <em>total</em> GMT offset at the
125 * transition.</li>
126 * </ul>
127 * If this time zone doesn't observe daylight saving time and has
128 * never changed any GMT offsets in the past, this value is null.
129 * @serial
130 */
131 private long[] transitions;
132
133 /**
134 * This array holds all unique offset values in
135 * milliseconds. Index values to this array are stored in the
136 * transitions array elements.
137 * @serial
138 */
139 private int[] offsets;
140
141 /**
142 * SimpleTimeZone parameter values. It has to have either 8 for
143 * {@link java.util.SimpleTimeZone#SimpleTimeZone(int, String,
144 * int, int , int , int , int , int , int , int , int) the
145 * 11-argument SimpleTimeZone constructor} or 10 for {@link
146 * java.util.SimpleTimeZone#SimpleTimeZone(int, String, int, int,
147 * int , int , int , int , int , int , int, int, int) the
148 * 13-argument SimpleTimeZone constructor} parameters.
149 * @serial
150 */
151 private int[] simpleTimeZoneParams;
152
153 /**
154 * True if the raw GMT offset value would change after the time
155 * zone data has been generated; false, otherwise. The default
156 * value is false.
157 * @serial
158 */
159 private boolean willGMTOffsetChange = false;
160
161 /**
162 * True if the object has been modified after its instantiation.
163 */
164 private transient boolean dirty = false;
165
166 @java.io.Serial
167 private static final long serialVersionUID = 2653134537216586139L;
168
169 /**
170 * A constructor.
171 */
172 public ZoneInfo() {
173 }
174
175 /**
176 * A Constructor for CustomID.
177 */
178 public ZoneInfo(String ID, int rawOffset) {
179 this(ID, rawOffset, 0, 0, null, null, null, false);
180 }
181
182 /**
183 * Constructs a ZoneInfo instance.
184 *
185 * @param ID time zone name
186 * @param rawOffset GMT offset in milliseconds
187 * @param dstSavings daylight saving value in milliseconds or 0
188 * (zero) if this time zone doesn't observe Daylight Saving Time.
189 * @param checksum CRC32 value with all transitions table entry
190 * values
191 * @param transitions transition table
192 * @param offsets offset value table
193 * @param simpleTimeZoneParams parameter values for constructing
194 * SimpleTimeZone
195 * @param willGMTOffsetChange the value of willGMTOffsetChange
196 */
197 ZoneInfo(String ID,
198 int rawOffset,
199 int dstSavings,
200 int checksum,
201 long[] transitions,
202 int[] offsets,
203 int[] simpleTimeZoneParams,
204 boolean willGMTOffsetChange) {
205 setID(ID);
206 this.rawOffset = rawOffset;
207 this.dstSavings = dstSavings;
208 this.checksum = checksum;
209 this.transitions = transitions;
210 this.offsets = offsets;
211 this.simpleTimeZoneParams = simpleTimeZoneParams;
212 this.willGMTOffsetChange = willGMTOffsetChange;
213 }
214
215 /**
216 * Returns the difference in milliseconds between local time and UTC
217 * of given time, taking into account both the raw offset and the
218 * effect of daylight savings.
219 *
220 * @param date the milliseconds in UTC
221 * @return the milliseconds to add to UTC to get local wall time
222 */
223 public int getOffset(long date) {
224 return getOffsets(date, null, UTC_TIME);
225 }
226
227 public int getOffsets(long utc, int[] offsets) {
228 return getOffsets(utc, offsets, UTC_TIME);
229 }
230
231 public int getOffsetsByStandard(long standard, int[] offsets) {
232 return getOffsets(standard, offsets, STANDARD_TIME);
233 }
234
235 public int getOffsetsByWall(long wall, int[] offsets) {
236 return getOffsets(wall, offsets, WALL_TIME);
237 }
238
239 private int getOffsets(long date, int[] offsets, int type) {
240 // if dst is never observed, there is no transition.
241 if (transitions == null) {
242 int offset = getLastRawOffset();
243 if (offsets != null) {
244 offsets[0] = offset;
245 offsets[1] = 0;
246 }
247 return offset;
248 }
249
250 date -= rawOffsetDiff;
251 int index = getTransitionIndex(date, type);
252
253 // prior to the transition table, returns the raw offset.
254 // FIXME: should support LMT.
255 if (index < 0) {
256 int offset = getLastRawOffset();
257 if (offsets != null) {
258 offsets[0] = offset;
259 offsets[1] = 0;
260 }
261 return offset;
262 }
263
264 if (index < transitions.length) {
265 long val = transitions[index];
266 int offset = this.offsets[(int)(val & OFFSET_MASK)] + rawOffsetDiff;
267 if (offsets != null) {
268 int dst = (int)((val >>> DST_NSHIFT) & 0xfL);
269 int save = (dst == 0) ? 0 : this.offsets[dst];
270 offsets[0] = offset - save;
271 offsets[1] = save;
272 }
273 return offset;
274 }
275
276 // beyond the transitions, delegate to SimpleTimeZone if there
277 // is a rule; otherwise, return the offset of the last transition.
278 SimpleTimeZone tz = getLastRule();
279 if (tz != null) {
280 int rawoffset = tz.getRawOffset();
281 long msec = date;
282 if (type != UTC_TIME) {
283 msec -= rawOffset;
284 }
285 int dstoffset = tz.getOffset(msec) - rawOffset;
286
287 // Check if it's in a standard-to-daylight transition.
288 if (dstoffset > 0 && tz.getOffset(msec - dstoffset) == rawoffset) {
289 dstoffset = 0;
290 }
291
292 if (offsets != null) {
293 offsets[0] = rawoffset;
294 offsets[1] = dstoffset;
295 }
296 return rawoffset + dstoffset;
297 } else {
298 // use the last transition
299 long val = transitions[transitions.length - 1];
300 int offset = this.offsets[(int)(val & OFFSET_MASK)] + rawOffsetDiff;
301 if (offsets != null) {
302 int dst = (int)((val >>> DST_NSHIFT) & 0xfL);
303 int save = (dst == 0) ? 0 : this.offsets[dst];
304 offsets[0] = offset - save;
305 offsets[1] = save;
306 }
307 return offset;
308 }
309 }
310
311 private int getTransitionIndex(long date, int type) {
312 int low = 0;
313 int high = transitions.length - 1;
314
315 while (low <= high) {
316 int mid = (low + high) / 2;
317 long val = transitions[mid];
318 long midVal = val >> TRANSITION_NSHIFT; // sign extended
319 if (type != UTC_TIME) {
320 midVal += offsets[(int)(val & OFFSET_MASK)]; // wall time
321 }
322 if (type == STANDARD_TIME) {
323 int dstIndex = (int)((val >>> DST_NSHIFT) & 0xfL);
324 if (dstIndex != 0) {
325 midVal -= offsets[dstIndex]; // make it standard time
326 }
327 }
328
329 if (midVal < date) {
330 low = mid + 1;
331 } else if (midVal > date) {
332 high = mid - 1;
333 } else {
334 return mid;
335 }
336 }
337
338 // if beyond the transitions, returns that index.
339 if (low >= transitions.length) {
340 return low;
341 }
342 return low - 1;
343 }
344
345 /**
346 * Returns the difference in milliseconds between local time and
347 * UTC, taking into account both the raw offset and the effect of
348 * daylight savings, for the specified date and time. This method
349 * assumes that the start and end month are distinct. This method
350 * assumes a Gregorian calendar for calculations.
351 * <p>
352 * <em>Note: In general, clients should use
353 * {@link Calendar#ZONE_OFFSET Calendar.get(ZONE_OFFSET)} +
354 * {@link Calendar#DST_OFFSET Calendar.get(DST_OFFSET)}
355 * instead of calling this method.</em>
356 *
357 * @param era The era of the given date. The value must be either
358 * GregorianCalendar.AD or GregorianCalendar.BC.
359 * @param year The year in the given date.
360 * @param month The month in the given date. Month is 0-based. e.g.,
361 * 0 for January.
362 * @param day The day-in-month of the given date.
363 * @param dayOfWeek The day-of-week of the given date.
364 * @param milliseconds The milliseconds in day in <em>standard</em> local time.
365 * @return The milliseconds to add to UTC to get local time.
366 */
367 public int getOffset(int era, int year, int month, int day,
368 int dayOfWeek, int milliseconds) {
369 if (milliseconds < 0 || milliseconds >= AbstractCalendar.DAY_IN_MILLIS) {
370 throw new IllegalArgumentException();
371 }
372
373 if (era == java.util.GregorianCalendar.BC) { // BC
374 year = 1 - year;
375 } else if (era != java.util.GregorianCalendar.AD) {
376 throw new IllegalArgumentException();
377 }
378
379 Gregorian gcal = CalendarSystem.getGregorianCalendar();
380 CalendarDate date = gcal.newCalendarDate(null);
381 date.setDate(year, month + 1, day);
382 if (gcal.validate(date) == false) {
383 throw new IllegalArgumentException();
384 }
385
386 // bug-for-bug compatible argument checking
387 if (dayOfWeek < java.util.GregorianCalendar.SUNDAY
388 || dayOfWeek > java.util.GregorianCalendar.SATURDAY) {
389 throw new IllegalArgumentException();
390 }
391
392 if (transitions == null) {
393 return getLastRawOffset();
394 }
395
396 long dateInMillis = gcal.getTime(date) + milliseconds;
397 dateInMillis -= (long) rawOffset; // make it UTC
398 return getOffsets(dateInMillis, null, UTC_TIME);
399 }
400
401 /**
402 * Sets the base time zone offset from GMT. This operation
403 * modifies all the transitions of this ZoneInfo object, including
404 * historical ones, if applicable.
405 *
406 * @param offsetMillis the base time zone offset to GMT.
407 * @see getRawOffset
408 */
409 public synchronized void setRawOffset(int offsetMillis) {
410 if (offsetMillis == rawOffset + rawOffsetDiff) {
411 return;
412 }
413 rawOffsetDiff = offsetMillis - rawOffset;
414 if (lastRule != null) {
415 lastRule.setRawOffset(offsetMillis);
416 }
417 dirty = true;
418 }
419
420 /**
421 * Returns the GMT offset of the current date. This GMT offset
422 * value is not modified during Daylight Saving Time.
423 *
424 * @return the GMT offset value in milliseconds to add to UTC time
425 * to get local standard time
426 */
427 public int getRawOffset() {
428 if (!willGMTOffsetChange) {
429 return rawOffset + rawOffsetDiff;
430 }
431
432 int[] offsets = new int[2];
433 getOffsets(System.currentTimeMillis(), offsets, UTC_TIME);
434 return offsets[0];
435 }
436
437 public boolean isDirty() {
438 return dirty;
439 }
440
441 private int getLastRawOffset() {
442 return rawOffset + rawOffsetDiff;
443 }
444
445 /**
446 * Queries if this time zone uses Daylight Saving Time in the last known rule.
447 */
448 public boolean useDaylightTime() {
449 return (simpleTimeZoneParams != null);
450 }
451
452 @Override
453 public boolean observesDaylightTime() {
454 if (simpleTimeZoneParams != null) {
455 return true;
456 }
457 if (transitions == null) {
458 return false;
459 }
460
461 // Look up the transition table to see if it's in DST right
462 // now or if there's any standard-to-daylight transition at
463 // any future.
464 long utc = System.currentTimeMillis() - rawOffsetDiff;
465 int index = getTransitionIndex(utc, UTC_TIME);
466
467 // before transitions in the transition table
468 if (index < 0) {
469 return false;
470 }
471
472 // the time is in the table range.
473 for (int i = index; i < transitions.length; i++) {
474 if ((transitions[i] & DST_MASK) != 0) {
475 return true;
476 }
477 }
478 // No further DST is observed.
479 return false;
480 }
481
482 /**
483 * Queries if the specified date is in Daylight Saving Time.
484 */
485 public boolean inDaylightTime(Date date) {
486 if (date == null) {
487 throw new NullPointerException();
488 }
489
490 if (transitions == null) {
491 return false;
492 }
493
494 long utc = date.getTime() - rawOffsetDiff;
495 int index = getTransitionIndex(utc, UTC_TIME);
496
497 // before transitions in the transition table
498 if (index < 0) {
499 return false;
500 }
501
502 // the time is in the table range.
503 if (index < transitions.length) {
504 return (transitions[index] & DST_MASK) != 0;
505 }
506
507 // beyond the transition table
508 SimpleTimeZone tz = getLastRule();
509 if (tz != null) {
510 return tz.inDaylightTime(date);
511 } else {
512 // use the last transition
513 return (transitions[transitions.length - 1] & DST_MASK) != 0;
514 }
515 }
516
517 /**
518 * Returns the amount of time in milliseconds that the clock is advanced
519 * during daylight saving time is in effect in its last daylight saving time rule.
520 *
521 * @return the number of milliseconds the time is advanced with respect to
522 * standard time when daylight saving time is in effect.
523 */
524 public int getDSTSavings() {
525 return dstSavings;
526 }
527
528 // /**
529 // * @return the last year in the transition table or -1 if this
530 // * time zone doesn't observe any daylight saving time.
531 // */
532 // public int getMaxTransitionYear() {
533 // if (transitions == null) {
534 // return -1;
535 // }
536 // long val = transitions[transitions.length - 1];
537 // int offset = this.offsets[(int)(val & OFFSET_MASK)] + rawOffsetDiff;
538 // val = (val >> TRANSITION_NSHIFT) + offset;
539 // CalendarDate lastDate = Gregorian.getCalendarDate(val);
540 // return lastDate.getYear();
541 // }
542
543 /**
544 * Returns a string representation of this time zone.
545 * @return the string
546 */
547 public String toString() {
548 return getClass().getName() +
549 "[id=\"" + getID() + "\"" +
550 ",offset=" + getLastRawOffset() +
551 ",dstSavings=" + dstSavings +
552 ",useDaylight=" + useDaylightTime() +
553 ",transitions=" + ((transitions != null) ? transitions.length : 0) +
554 ",lastRule=" + (lastRule == null ? getLastRuleInstance() : lastRule) +
555 "]";
556 }
557
558 /**
559 * Gets all available IDs supported in the Java run-time.
560 *
561 * @return an array of time zone IDs.
562 */
563 public static String[] getAvailableIDs() {
564 return ZoneInfoFile.getZoneIds();
565 }
566
567 /**
568 * Gets all available IDs that have the same value as the
569 * specified raw GMT offset.
570 *
571 * @param rawOffset the GMT offset in milliseconds. This
572 * value should not include any daylight saving time.
573 *
574 * @return an array of time zone IDs.
575 */
576 public static String[] getAvailableIDs(int rawOffset) {
577 return ZoneInfoFile.getZoneIds(rawOffset);
578 }
579
580 /**
581 * Gets the ZoneInfo for the given ID.
582 *
583 * @param ID the ID for a ZoneInfo. See TimeZone for detail.
584 *
585 * @return the specified ZoneInfo object, or null if there is no
586 * time zone of the ID.
587 */
588 public static TimeZone getTimeZone(String ID) {
589 return ZoneInfoFile.getZoneInfo(ID);
590 }
591
592 private transient SimpleTimeZone lastRule;
593
594 /**
595 * Returns a SimpleTimeZone object representing the last GMT
596 * offset and DST schedule or null if this time zone doesn't
597 * observe DST.
598 */
599 private synchronized SimpleTimeZone getLastRule() {
600 if (lastRule == null) {
601 lastRule = getLastRuleInstance();
602 }
603 return lastRule;
604 }
605
606 /**
607 * Returns a SimpleTimeZone object that represents the last
608 * known daylight saving time rules.
609 *
610 * @return a SimpleTimeZone object or null if this time zone
611 * doesn't observe DST.
612 */
613 public SimpleTimeZone getLastRuleInstance() {
614 if (simpleTimeZoneParams == null) {
615 return null;
616 }
617 if (simpleTimeZoneParams.length == 10) {
618 return new SimpleTimeZone(getLastRawOffset(), getID(),
619 simpleTimeZoneParams[0],
620 simpleTimeZoneParams[1],
621 simpleTimeZoneParams[2],
622 simpleTimeZoneParams[3],
623 simpleTimeZoneParams[4],
624 simpleTimeZoneParams[5],
625 simpleTimeZoneParams[6],
626 simpleTimeZoneParams[7],
627 simpleTimeZoneParams[8],
628 simpleTimeZoneParams[9],
629 dstSavings);
630 }
631 return new SimpleTimeZone(getLastRawOffset(), getID(),
632 simpleTimeZoneParams[0],
633 simpleTimeZoneParams[1],
634 simpleTimeZoneParams[2],
635 simpleTimeZoneParams[3],
636 simpleTimeZoneParams[4],
637 simpleTimeZoneParams[5],
638 simpleTimeZoneParams[6],
639 simpleTimeZoneParams[7],
640 dstSavings);
641 }
642
643 /**
644 * Returns a copy of this <code>ZoneInfo</code>.
645 */
646 public Object clone() {
647 ZoneInfo zi = (ZoneInfo) super.clone();
648 zi.lastRule = null;
649 return zi;
650 }
651
652 /**
653 * Returns a hash code value calculated from the GMT offset and
654 * transitions.
655 * @return a hash code of this time zone
656 */
657 public int hashCode() {
658 return getLastRawOffset() ^ checksum;
659 }
660
661 /**
662 * Compares the equity of two ZoneInfo objects.
663 *
664 * @param obj the object to be compared with
665 * @return true if given object is same as this ZoneInfo object,
666 * false otherwise.
667 */
668 public boolean equals(Object obj) {
669 if (this == obj) {
670 return true;
671 }
672 if (!(obj instanceof ZoneInfo)) {
673 return false;
674 }
675 ZoneInfo that = (ZoneInfo) obj;
676 return (getID().equals(that.getID())
677 && (getLastRawOffset() == that.getLastRawOffset())
678 && (checksum == that.checksum));
679 }
680
681 /**
682 * Returns true if this zone has the same raw GMT offset value and
683 * transition table as another zone info. If the specified
684 * TimeZone object is not a ZoneInfo instance, this method returns
685 * true if the specified TimeZone object has the same raw GMT
686 * offset value with no daylight saving time.
687 *
688 * @param other the ZoneInfo object to be compared with
689 * @return true if the given <code>TimeZone</code> has the same
690 * GMT offset and transition information; false, otherwise.
691 */
692 public boolean hasSameRules(TimeZone other) {
693 if (this == other) {
694 return true;
695 }
696 if (other == null) {
697 return false;
698 }
699 if (!(other instanceof ZoneInfo)) {
700 if (getRawOffset() != other.getRawOffset()) {
701 return false;
702 }
703 // if both have the same raw offset and neither observes
704 // DST, they have the same rule.
705 if ((transitions == null)
706 && (useDaylightTime() == false)
707 && (other.useDaylightTime() == false)) {
708 return true;
709 }
710 return false;
711 }
712 if (getLastRawOffset() != ((ZoneInfo)other).getLastRawOffset()) {
713 return false;
714 }
715 return (checksum == ((ZoneInfo)other).checksum);
716 }
717
718 /**
719 * Returns a Map from alias time zone IDs to their standard
720 * time zone IDs.
721 *
722 * @return the Map that holds the mappings from alias time zone IDs
723 * to their standard time zone IDs, or null if
724 * <code>ZoneInfoMappings</code> file is not available.
725 */
726 public static Map<String, String> getAliasTable() {
727 return ZoneInfoFile.getAliasMap();
728 }
729
730 @java.io.Serial
731 private void readObject(ObjectInputStream stream)
732 throws IOException, ClassNotFoundException {
733 stream.defaultReadObject();
734 // We don't know how this object from 1.4.x or earlier has
735 // been mutated. So it should always be marked as `dirty'.
736 dirty = true;
737 }
738 }