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 java.time.ZoneId;
21 import java.util.TimeZone;
22
23 import org.apache.commons.lang3.ArraySorter;
24 import org.apache.commons.lang3.JavaVersion;
25 import org.apache.commons.lang3.ObjectUtils;
26 import org.apache.commons.lang3.SystemProperties;
27 import org.apache.commons.lang3.SystemUtils;
28
29 /**
30 * Helps dealing with {@link java.util.TimeZone}s.
31 *
32 * @since 3.7
33 */
34 public class TimeZones {
35
36 /**
37 * A public version of {@link java.util.TimeZone}'s package private {@code GMT_ID} field.
38 */
39 public static final String GMT_ID = "GMT";
40
41 /**
42 * The GMT time zone.
43 *
44 * @since 3.13.0
45 */
46 public static final TimeZone GMT = TimeZones.getTimeZone(GMT_ID);
47
48 private static final boolean JAVA_25 = SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_25);
49
50 /**
51 * The sorted available IDs.
52 * <p>
53 * Make a defensive copy, just in case.
54 * </p>
55 * @see TimeZone#getAvailableIDs()
56 */
57 static final String[] SORTED_AVAILABLE_IDS = ArraySorter.sort(TimeZone.getAvailableIDs().clone());
58
59 /**
60 * Delegates to {@link TimeZone#getTimeZone(String)}, on Java 25 and up, maps an ID if it's a key in {@link ZoneId#SHORT_IDS}.
61 * <p>
62 * On Java 25, calling {@link TimeZone#getTimeZone(String)} with an ID in {@link ZoneId#SHORT_IDS} writes a message to {@link System#err} in the form:
63 * </p>
64 *
65 * <pre>
66 * WARNING: Use of the three-letter time zone ID "the-short-id" is deprecated and it will be removed in a future release
67 * </pre>
68 * <p>
69 * You can disable mapping from {@link ZoneId#SHORT_IDS} by setting the system property {@code "TimeZones.mapShortIDs=false"}.
70 * </p>
71 *
72 * @param id Same as {@link TimeZone#getTimeZone(String)}.
73 * @return Same as {@link TimeZone#getTimeZone(String)}.
74 * @since 3.20.0
75 */
76 public static TimeZone getTimeZone(final String id) {
77 return TimeZone.getTimeZone(JAVA_25 && mapShortIDs() ? ZoneId.SHORT_IDS.getOrDefault(id, id) : id);
78 }
79
80 private static boolean mapShortIDs() {
81 return SystemProperties.getBoolean(TimeZones.class, "mapShortIDs", () -> true);
82 }
83
84 /**
85 * Returns the given TimeZone if non-{@code null}, otherwise {@link TimeZone#getDefault()}.
86 *
87 * @param timeZone a locale or {@code null}.
88 * @return the given locale if non-{@code null}, otherwise {@link TimeZone#getDefault()}.
89 * @since 3.13.0
90 */
91 public static TimeZone toTimeZone(final TimeZone timeZone) {
92 return ObjectUtils.getIfNull(timeZone, TimeZone::getDefault);
93 }
94
95 /** Do not instantiate. */
96 private TimeZones() {
97 }
98 }