View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.lang3.time;
19  
20  import static org.junit.jupiter.api.Assertions.assertEquals;
21  
22  import java.text.SimpleDateFormat;
23  import java.time.Instant;
24  import java.util.Calendar;
25  import java.util.Date;
26  import java.util.Locale;
27  import java.util.TimeZone;
28  import java.util.stream.Stream;
29  
30  import org.apache.commons.lang3.AbstractLangTest;
31  import org.junit.jupiter.params.ParameterizedTest;
32  import org.junit.jupiter.params.provider.Arguments;
33  import org.junit.jupiter.params.provider.MethodSource;
34  
35  /**
36   * Tests date formatting in every available time zone using fixed dates and {@link Locale#US}.
37   *
38   * <p>
39   * The old test used the current time. It began failing on November 1, 2026 because newer JDKs and {@link FastDatePrinter} chose different names for some
40   * Canadian zones, even though the clock times and UTC offsets matched. {@link SimpleDateFormat} can use CLDR naming rules to choose a name such as {@code MDT},
41   * while the printer uses the calendar's DST flag and can choose {@code MST} for the same instant.
42   * </p>
43   *
44   * <p>
45   * We compare the complete output with {@link SimpleDateFormat} for fixed January and July dates. Around DST changes, we compare numeric offsets with
46   * {@link SimpleDateFormat} and names with {@link TimeZone}. The dates cover New York's skipped and repeated hours and the November 1 failure.
47   * </p>
48   *
49   * <p>
50   * Keep the dates and locale explicit, and set each calendar's time before formatting. Do not use the current time or remove transition cases to make the test
51   * pass. Comparing {@link SimpleDateFormat}'s zone names for every case would bring back the failure. These tests check the printer's existing naming behavior;
52   * they do not change it to match newer JDKs.
53   * </p>
54   */
55  class FastDatePrinterTimeZonesTest extends AbstractLangTest {
56  
57      private static final Locale LOCALE = Locale.US;
58  
59      /**
60       * Gets the time zones and fixed dates for offset and name checks, including both occurrences of New York's repeated hour.
61       *
62       * @return time-zone IDs paired with fixed instants.
63       */
64      static Stream<Arguments> getTimeZonesAndInstants() {
65          // @formatter:off
66          return Stream.concat(getTimeZonesAndSeasonalInstants(), timeZonesAndInstants(
67                  // Immediately before and after the spring gap in New York.
68                  "2026-03-08T06:59:59Z",
69                  "2026-03-08T07:00:00Z",
70                  // Both occurrences of 1:30 AM during the fall overlap in New York.
71                  "2026-11-01T05:30:00Z",
72                  "2026-11-01T06:30:00Z",
73                  // Exercises the Canadian zone-name differences after the 2026 transition.
74                  "2026-11-01T12:00:00Z"));
75          // @formatter:on
76      }
77  
78      /**
79       * Gets the January and July dates used for complete {@link SimpleDateFormat} comparisons. Keep these separate from the transition cases where the
80       * formatters can choose different zone names.
81       *
82       * @return time-zone IDs paired with the fixed seasonal instants.
83       */
84      static Stream<Arguments> getTimeZonesAndSeasonalInstants() {
85          return timeZonesAndInstants("2026-01-15T12:00:00Z", "2026-07-15T12:00:00Z");
86      }
87  
88      private static Stream<Arguments> timeZonesAndInstants(final String... instants) {
89          return Stream.of(TimeZones.SORTED_AVAILABLE_IDS).flatMap(id -> Stream.of(instants).map(instant -> Arguments.of(id, Instant.parse(instant))));
90      }
91  
92      /**
93       * Checks the clock time and the name chosen by {@link TimeZone}.
94       *
95       * <p>
96       * Keep the zone name out of the {@link SimpleDateFormat} pattern here. Its name can differ from the printer's even when the time is correct.
97       * </p>
98       *
99       * @param timeZoneId the time-zone ID to test.
100      * @param instant    the fixed instant to format.
101      */
102     @ParameterizedTest
103     @MethodSource("getTimeZonesAndInstants")
104     void testCalendarTimezoneDisplayName(final String timeZoneId, final Instant instant) {
105         final TimeZone timeZone = TimeZones.getTimeZone(timeZoneId);
106         final Calendar cal = Calendar.getInstance(timeZone, LOCALE);
107         cal.setTimeInMillis(instant.toEpochMilli());
108         final Date date = cal.getTime();
109         final SimpleDateFormat sdf = new SimpleDateFormat("h:mma", LOCALE);
110         sdf.setTimeZone(timeZone);
111         final String expectedValue = sdf.format(date) + " " + timeZone.getDisplayName(timeZone.inDaylightTime(date), TimeZone.SHORT, LOCALE);
112         final String actualValue = FastDateFormat.getInstance("h:mma z", timeZone, LOCALE).format(cal);
113         assertEquals(expectedValue, actualValue);
114     }
115 
116     /**
117      * Checks the clock time and numeric UTC offset against {@link SimpleDateFormat}.
118      *
119      * <p>
120      * Keep the uppercase {@code Z} pattern. Lowercase {@code z} compares names and would bring back the naming mismatch.
121      * </p>
122      *
123      * @param timeZoneId the time-zone ID to test.
124      * @param instant    the fixed instant to format.
125      */
126     @ParameterizedTest
127     @MethodSource("getTimeZonesAndInstants")
128     void testCalendarTimezoneOffset(final String timeZoneId, final Instant instant) {
129         final TimeZone timeZone = TimeZones.getTimeZone(timeZoneId);
130         final Calendar cal = Calendar.getInstance(timeZone, LOCALE);
131         cal.setTimeInMillis(instant.toEpochMilli());
132         final String pattern = "h:mma Z";
133         final SimpleDateFormat sdf = new SimpleDateFormat(pattern, LOCALE);
134         sdf.setTimeZone(timeZone);
135         assertEquals(sdf.format(cal.getTime()), FastDateFormat.getInstance(pattern, timeZone, LOCALE).format(cal));
136     }
137 
138     /**
139      * Keeps the original comparison of complete formatted output, including zone names, for the fixed January and July dates.
140      *
141      * @param timeZoneId the time-zone ID to test.
142      * @param instant    the fixed seasonal instant to format.
143      */
144     @ParameterizedTest
145     @MethodSource("getTimeZonesAndSeasonalInstants")
146     void testCalendarTimezoneRespected(final String timeZoneId, final Instant instant) {
147         final TimeZone timeZone = TimeZones.getTimeZone(timeZoneId);
148         final Calendar cal = Calendar.getInstance(timeZone, LOCALE);
149         cal.setTimeInMillis(instant.toEpochMilli());
150         final String pattern = "h:mma z";
151         final SimpleDateFormat sdf = new SimpleDateFormat(pattern, LOCALE);
152         sdf.setTimeZone(timeZone);
153         assertEquals(sdf.format(cal.getTime()), FastDateFormat.getInstance(pattern, timeZone, LOCALE).format(cal));
154     }
155 }