/* * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /* * This file is available under and governed by the GNU General Public * License version 2 only, as published by the Free Software Foundation. * However, the following notice accompanied the original version of this * file: * * Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos * * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * * Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * * Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * * Neither the name of JSR-310 nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ package java.time; import java.io.DataOutput; import java.io.IOException; import java.io.Serializable; import java.time.format.DateTimeFormatterBuilder; import java.time.format.TextStyle; import java.time.temporal.Queries; import java.time.temporal.TemporalAccessor; import java.time.temporal.TemporalField; import java.time.temporal.TemporalQuery; import java.time.zone.ZoneRules; import java.time.zone.ZoneRulesProvider; import java.util.Collections; import java.util.HashMap; import java.util.Locale; import java.util.Map; import java.util.Objects; import java.util.TimeZone; /** * A time-zone ID, such as {@code Europe/Paris}. *
* A {@code ZoneId} is used to identify the rules used to convert between * an {@link Instant} and a {@link LocalDateTime}. * There are two distinct types of ID: *
* Most fixed offsets are represented by {@link ZoneOffset}. *
* The actual rules, describing when and how the offset changes, are defined by {@link ZoneRules}. * This class is simply an ID used to obtain the underlying rules. * This approach is taken because rules are defined by governments and change * frequently, whereas the ID is stable. *
* The distinction has other effects. Serializing the {@code ZoneId} will only send * the ID, whereas serializing the rules sends the entire data set. * Similarly, a comparison of two IDs only examines the ID, whereas * a comparison of two rules examines the entire data set. *
* The code supports loading a {@code ZoneId} on a JVM which does not have available rules * for that ID. This allows the date-time object, such as {@link ZonedDateTime}, * to still be queried. * *
* An ID is parsed as an offset ID if it starts with 'UTC', 'GMT', '+' or '-', or * is a single letter. * For example, 'Z', '+02:00', '-05:00', 'UTC+05' and 'GMT-6' are all valid offset IDs. * Note that some IDs, such as 'D' or '+ABC' meet the criteria, but are invalid. *
* All other IDs are considered to be region IDs. *
* Region IDs are defined by configuration, which can be thought of as a {@code Map} * from region ID to {@code ZoneRules}, see {@link ZoneRulesProvider}. *
* Time-zones are defined by governments and change frequently. There are a number of * organizations, known here as groups, that monitor time-zone changes and collate them. * The default group is the IANA Time Zone Database (TZDB). * Other organizations include IATA (the airline industry body) and Microsoft. *
* Each group defines its own format for region ID. * The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'. * TZDB IDs take precedence over other groups. *
* It is strongly recommended that the group name is included in all Ids supplied by * groups other than TZDB to avoid conflicts. For example, IATA airline time-zone * region IDs are typically the same as the three letter airport code. * However, the airport of Utrecht has the code 'UTC', which is obviously a conflict. * The recommended format for region IDs from groups other than TZDB is 'group~region'. * Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'. * *
* This maps as follows: *
* The map is unmodifiable.
*/
public static final Map
* This maps as follows:
*
* The map is unmodifiable.
*/
public static final Map
* This queries {@link TimeZone#getDefault()} to find the default time-zone
* and converts it to a {@code ZoneId}. If the system default time-zone is changed,
* then the result of this method will also change.
*
* @return the zone ID, not null
* @throws DateTimeException if the converted zone ID has an invalid format
* @throws java.time.zone.ZoneRulesException if the converted zone region ID cannot be found
*/
public static ZoneId systemDefault() {
return ZoneId.of(TimeZone.getDefault().getID(), OLD_IDS_POST_2005);
}
//-----------------------------------------------------------------------
/**
* Obtains an instance of {@code ZoneId} using its ID using a map
* of aliases to supplement the standard zone IDs.
*
* Many users of time-zones use short abbreviations, such as PST for
* 'Pacific Standard Time' and PDT for 'Pacific Daylight Time'.
* These abbreviations are not unique, and so cannot be used as IDs.
* This method allows a map of string to time-zone to be setup and reused
* within an application.
*
* @param zoneId the time-zone ID, not null
* @param aliasMap a map of alias zone IDs (typically abbreviations) to real zone IDs, not null
* @return the zone ID, not null
* @throws DateTimeException if the zone ID has an invalid format
* @throws java.time.zone.ZoneRulesException if the zone region ID cannot be found
*/
public static ZoneId of(String zoneId, Map
* This method parses the ID, applies any appropriate normalization, and validates it
* against the known set of IDs for which rules are available.
*
* An ID is parsed as though it is an offset ID if it starts with 'UTC', 'GMT', '+'
* or '-', or if it has less then two letters.
* The offset of {@link ZoneOffset#UTC zero} may be represented in multiple ways,
* including 'Z', 'UTC', 'GMT', 'UTC0' 'GMT0', '+00:00', '-00:00' and 'UTC+00:00'.
*
* Eight forms of ID are recognized, where '{offset}' means to parse using {@link ZoneOffset#of(String)}:
*
* Region IDs must match the regular expression
* The detailed format of the region ID depends on the group supplying the data.
* The default set of data is supplied by the IANA Time Zone Database (TZDB)
* This has region IDs of the form '{area}/{city}', such as 'Europe/Paris' or 'America/New_York'.
* This is compatible with most IDs from {@link java.util.TimeZone}.
*
* @param zoneId the time-zone ID, not null
* @return the zone ID, not null
* @throws DateTimeException if the zone ID has an invalid format
* @throws java.time.zone.ZoneRulesException if the zone region ID cannot be found
*/
public static ZoneId of(String zoneId) {
Objects.requireNonNull(zoneId, "zoneId");
if (zoneId.length() <= 1 || zoneId.startsWith("+") || zoneId.startsWith("-")) {
return ZoneOffset.of(zoneId);
} else if (zoneId.startsWith("UTC") || zoneId.startsWith("GMT")) {
if (zoneId.length() == 3 || (zoneId.length() == 4 && zoneId.charAt(3) == '0')) {
return ZoneOffset.UTC;
}
return ZoneOffset.of(zoneId.substring(3));
}
return ZoneRegion.ofId(zoneId, true);
}
//-----------------------------------------------------------------------
/**
* Obtains an instance of {@code ZoneId} from a temporal object.
*
* A {@code TemporalAccessor} represents some form of date and time information.
* This factory converts the arbitrary temporal object to an instance of {@code ZoneId}.
*
* The conversion will try to obtain the zone in a way that favours region-based
* zones over offset-based zones using {@link Queries#zone()}.
*
* This method matches the signature of the functional interface {@link TemporalQuery}
* allowing it to be used in queries via method reference, {@code ZoneId::from}.
*
* @param temporal the temporal object to convert, not null
* @return the zone ID, not null
* @throws DateTimeException if unable to convert to a {@code ZoneId}
*/
public static ZoneId from(TemporalAccessor temporal) {
ZoneId obj = temporal.query(Queries.zone());
if (obj == null) {
throw new DateTimeException("Unable to obtain ZoneId from TemporalAccessor: " + temporal.getClass());
}
return obj;
}
//-----------------------------------------------------------------------
/**
* Constructor only accessible within the package.
*/
ZoneId() {
if (getClass() != ZoneOffset.class && getClass() != ZoneRegion.class) {
throw new AssertionError("Invalid subclass");
}
}
//-----------------------------------------------------------------------
/**
* Gets the unique time-zone ID.
*
* This ID uniquely defines this object.
* The format of an offset based ID is defined by {@link ZoneOffset#getId()}.
*
* @return the time-zone unique ID, not null
*/
public abstract String getId();
//-----------------------------------------------------------------------
/**
* Gets the time-zone rules for this ID allowing calculations to be performed.
*
* The rules provide the functionality associated with a time-zone,
* such as finding the offset for a given instant or local date-time.
*
* A time-zone can be invalid if it is deserialized in a JVM which does not
* have the same rules loaded as the JVM that stored it. In this case, calling
* this method will throw an exception.
*
* The rules are supplied by {@link ZoneRulesProvider}. An advanced provider may
* support dynamic updates to the rules without restarting the JVM.
* If so, then the result of this method may change over time.
* Each individual call will be still remain thread-safe.
*
* {@link ZoneOffset} will always return a set of rules where the offset never changes.
*
* @return the rules, not null
* @throws DateTimeException if no rules are available for this ID
*/
public abstract ZoneRules getRules();
//-----------------------------------------------------------------------
/**
* Gets the textual representation of the zone, such as 'British Time' or
* '+02:00'.
*
* This returns a textual description for the time-zone ID.
*
* If no textual mapping is found then the {@link #getId() full ID} is returned.
*
* @param style the length of the text required, not null
* @param locale the locale to use, not null
* @return the text value of the zone, not null
*/
public String getText(TextStyle style, Locale locale) {
return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).print(new TemporalAccessor() {
@Override
public boolean isSupported(TemporalField field) {
return false;
}
@Override
public long getLong(TemporalField field) {
throw new DateTimeException("Unsupported field: " + field);
}
@SuppressWarnings("unchecked")
@Override
public
* The comparison is based on the ID.
*
* @param obj the object to check, null returns false
* @return true if this is equal to the other time-zone ID
*/
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj instanceof ZoneId) {
ZoneId other = (ZoneId) obj;
return getId().equals(other.getId());
}
return false;
}
/**
* A hash code for this time-zone ID.
*
* @return a suitable hash code
*/
@Override
public int hashCode() {
return getId().hashCode();
}
//-----------------------------------------------------------------------
/**
* Outputs this zone as a {@code String}, using the ID.
*
* @return a string representation of this time-zone ID, not null
*/
@Override
public String toString() {
return getId();
}
//-----------------------------------------------------------------------
/**
* Writes the object using a
* dedicated serialized form.
*
*
*
{offset}
- a {@link ZoneOffset} ID, such as 'Z' or '+02:00'
* UTC
- alternate form of a {@code ZoneOffset} ID equal to 'Z'
* UTC0
- alternate form of a {@code ZoneOffset} ID equal to 'Z'
* UTC{offset}
- alternate form of a {@code ZoneOffset} ID equal to '{offset}'
* GMT
- alternate form of a {@code ZoneOffset} ID equal to 'Z'
* GMT0
- alternate form of a {@code ZoneOffset} ID equal to 'Z'
* GMT{offset}
- alternate form of a {@code ZoneOffset} ID equal to '{offset}'r
* {regionID}
- full region ID, loaded from configuration
* [A-Za-z][A-Za-z0-9~/._+-]+
.
*
* out.writeByte(7); // identifies this as a ZoneId (not ZoneOffset)
* out.writeUTF(zoneId);
*
*
* @return the instance of {@code Ser}, not null
*/
// this is here for serialization Javadoc
private Object writeReplace() {
return new Ser(Ser.ZONE_REGION_TYPE, this);
}
abstract void write(DataOutput out) throws IOException;
}