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