jdk-sandbox: comparison jdk/src/share/classes/java/time/ZoneId.java

equal deleted inserted replaced

-:3bbdae468b05
+:60207b2b4b42
 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.temporal.UnsupportedTemporalTypeException;
 import java.time.zone.ZoneRules;
 import java.time.zone.ZoneRulesException;
 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.Set;
 import java.util.TimeZone;
 /**
 * A time-zone ID, such as {@code Europe/Paris}.
 * <p>
 *  the same offset for all local date-times
 * <li>Geographical regions - an area where a specific set of rules for finding
 *  the offset from UTC/Greenwich apply
 * </ul><p>
 * Most fixed offsets are represented by {@link ZoneOffset}.
+* Calling {@link #normalized()} on any {@code ZoneId} will ensure that a
+* fixed offset ID will be represented as a {@code ZoneOffset}.
 * <p>
 * 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.
 * <p>
 * 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.
-* <p>
-* 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.
 *
 * <h3>Time-zone IDs</h3>
 * The ID is unique within the system.
-* The formats for offset and region IDs differ.
+* There are three types of ID.
 * <p>
-* An ID is parsed as an offset ID if it starts with 'UTC', 'GMT', 'UT' '+' or '-', or
+* The simplest type of ID is that from {@code ZoneOffset}.
-* is a single letter. For example, 'Z', '+02:00', '-05:00', 'UTC+05', 'GMT-6' and
+* This consists of 'Z' and IDs starting with '+' or '-'.
-* 'UT+01:00' are all valid offset IDs.
+* <p>
-* Note that some IDs, such as 'D' or '+ABC' meet the criteria to be parsed as offset IDs,
+* The next type of ID are offset-style IDs with some form of prefix,
-* but have an invalid offset.
+* such as 'GMT+2' or 'UTC+01:00'.
-* <p>
+* The recognised prefixes are 'UTC', 'GMT' and 'UT'.
-* All other IDs are considered to be region IDs.
+* The offset is the suffix and will be normalized during creation.
-* <p>
+* These IDs can be normalized to a {@code ZoneOffset} using {@code normalized()}.
-* Region IDs are defined by configuration, which can be thought of as a {@code Map}
+* <p>
-* from region ID to {@code ZoneRules}, see {@link ZoneRulesProvider}.
+* The third type of ID are region-based IDs. A region-based ID must be of
-* <p>
+* two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'.
-* Time-zones are defined by governments and change frequently. There are a number of
+* Region-based IDs are defined by configuration, see {@link ZoneRulesProvider}.
-* organizations, known here as groups, that monitor time-zone changes and collate them.
+* The configuration focuses on providing the lookup from the ID to the
+* underlying {@code ZoneRules}.
+* <p>
+* Time-zone rules 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.
 * <p>
 * Each group defines its own format for the region ID it provides.
 * The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'.
 * 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'.
 *
+* <h3>Serialization</h3>
+* This class can be serialized and stores the string zone ID in the external form.
+* The {@code ZoneOffset} subclass uses a dedicated format that only stores the
+* offset from UTC/Greenwich.
+* <p>
+* A {@code ZoneId} can be deserialized in a Java Runtime where the ID is unknown.
+* For example, if a server-side Java Runtime has been updated with a new zone ID, but
+* the client-side Java Runtime has not been updated. In this case, the {@code ZoneId}
+* object will exist, and can be queried using {@code getId}, {@code equals},
+* {@code hashCode}, {@code toString}, {@code getDisplayName} and {@code normalized}.
+* However, any call to {@code getRules} will fail with {@code ZoneRulesException}.
+* This approach is designed to allow a {@link ZonedDateTime} to be loaded and
+* queried, but not modified, on a Java Runtime with incomplete time-zone information.
+*
 * <h3>Specification for implementors</h3>
 * This abstract class has two implementations, both of which are immutable and thread-safe.
 * One implementation models region-based IDs, the other is {@code ZoneOffset} modelling
 * offset-based IDs. This difference is visible in serialization.
 *
 * @since 1.8
 */
 public abstract class ZoneId implements Serializable {
 /**
-* A map of zone overrides to enable the older US time-zone names to be used.
+* A map of zone overrides to enable the older short time-zone names to be used.
+* <p>
+* Use of short zone IDs has been deprecated in {@code java.util.TimeZone}.
+* This map allows the IDs to continue to be used via the
+* {@link #of(String, Map)} factory method.
+* <p>
+* This map contains an older mapping of the IDs, where 'EST', 'MST' and 'HST'
+* map to IDs which include daylight savings.
+* This is in line with versions of TZDB before 2005r.
 * <p>
 * This maps as follows:
 * <p><ul>
 * <li>EST - America/New_York</li>
 * <li>MST - America/Denver</li>
 * <li>SST - Pacific/Guadalcanal</li>
 * <li>VST - Asia/Ho_Chi_Minh</li>
 * </ul><p>
 * The map is unmodifiable.
 */
-public static final Map<String, String> OLD_IDS_PRE_2005;
+public static final Map<String, String> OLD_SHORT_IDS;
 /**
-* A map of zone overrides to enable the older US time-zone names to be used.
+* A map of zone overrides to enable the short time-zone names to be used.
+* <p>
+* Use of short zone IDs has been deprecated in {@code java.util.TimeZone}.
+* This map allows the IDs to continue to be used via the
+* {@link #of(String, Map)} factory method.
+* <p>
+* This map contains a newer mapping of the IDs, where 'EST', 'MST' and 'HST'
+* map to IDs which do not include daylight savings
+* This is in line with TZDB 2005r and later.
 * <p>
 * This maps as follows:
 * <p><ul>
 * <li>EST - -05:00</li>
 * <li>HST - -10:00</li>
 * <li>SST - Pacific/Guadalcanal</li>
 * <li>VST - Asia/Ho_Chi_Minh</li>
 * </ul><p>
 * The map is unmodifiable.
 */
-public static final Map<String, String> OLD_IDS_POST_2005;
+public static final Map<String, String> SHORT_IDS;
 static {
 Map<String, String> base = new HashMap<>();
 base.put("ACT", "Australia/Darwin");
 base.put("AET", "Australia/Sydney");
 base.put("AGT", "America/Argentina/Buenos_Aires");
 base.put("VST", "Asia/Ho_Chi_Minh");
 Map<String, String> pre = new HashMap<>(base);
 pre.put("EST", "America/New_York");
 pre.put("MST", "America/Denver");
 pre.put("HST", "Pacific/Honolulu");
-OLD_IDS_PRE_2005 = Collections.unmodifiableMap(pre);
+OLD_SHORT_IDS = Collections.unmodifiableMap(pre);
 Map<String, String> post = new HashMap<>(base);
 post.put("EST", "-05:00");
 post.put("MST", "-07:00");
 post.put("HST", "-10:00");
-OLD_IDS_POST_2005 = Collections.unmodifiableMap(post);
+SHORT_IDS = Collections.unmodifiableMap(post);
 }
 /**
 * Serialization version.
 */
 private static final long serialVersionUID = 8352817235686L;
 * @return the zone ID, not null
 * @throws DateTimeException if the converted zone ID has an invalid format
 * @throws ZoneRulesException if the converted zone region ID cannot be found
 */
 public static ZoneId systemDefault() {
-return ZoneId.of(TimeZone.getDefault().getID(), OLD_IDS_POST_2005);
+return ZoneId.of(TimeZone.getDefault().getID(), SHORT_IDS);
+}
+/**
+* Gets the set of available zone IDs.
+* <p>
+* This set includes the string form of all available region-based IDs.
+* Offset-based zone IDs are not included in the returned set.
+* The ID can be passed to {@link #of(String)} to create a {@code ZoneId}.
+* <p>
+* The set of zone IDs can increase over time, although in a typical application
+* the set of IDs is fixed. Each call to this method is thread-safe.
+*
+* @return a modifiable copy of the set of zone IDs, not null
+*/
+public static Set<String> getAvailableZoneIds() {
+return ZoneRulesProvider.getAvailableZoneIds();
 }
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code ZoneId} using its ID using a map
 /**
 * Obtains an instance of {@code ZoneId} from an ID ensuring that the
 * ID is valid and available for use.
 * <p>
-* This method parses the ID, applies any appropriate normalization, and validates it
+* This method parses the ID producing a {@code ZoneId} or {@code ZoneOffset}.
-* against the known set of IDs for which rules are available.
+* A {@code ZoneOffset} is returned if the ID is 'Z', or starts with '+' or '-'.
-* <p>
+* The result will always be a valid ID for which {@link ZoneRules} can be obtained.
-* An ID is parsed as though it is an offset ID if it starts with 'UTC', 'GMT', 'UT', '+'
+* <p>
-* or '-', or if it has less then two letters.
+* Parsing matches the zone ID step by step as follows.
-* The offset of {@linkplain ZoneOffset#UTC zero} may be represented in multiple ways,
+* <ul>
-* including 'Z', 'UTC', 'GMT', 'UT', 'UTC0', 'GMT0', 'UT0', '+00:00', '-00:00' and 'UTC+00:00'.
+* <li>If the zone ID equals 'Z', the result is {@code ZoneOffset.UTC}.
-* <p>
+* <li>If the zone ID consists of a single letter, the zone ID is invalid
-* Six forms of ID are recognized:
+*  and {@code DateTimeException} is thrown.
-* <p><ul>
+* <li>If the zone ID starts with '+' or '-', the ID is parsed as a
-* <li><code>Z</code> - an offset of zero, which is {@code ZoneOffset.UTC}
+*  {@code ZoneOffset} using {@link ZoneOffset#of(String)}.
-* <li><code>{offset}</code> - a {@code ZoneOffset} ID, such as '+02:00'
+* <li>If the zone ID equals 'GMT', 'UTC' or 'UT' then the result is a {@code ZoneId}
-* <li><code>{utcPrefix}</code> - a {@code ZoneOffset} ID equal to 'Z'
+*  with the same ID and rules equivalent to {@code ZoneOffset.UTC}.
-* <li><code>{utcPrefix}0</code> - a {@code ZoneOffset} ID equal to 'Z'
+* <li>If the zone ID starts with 'UTC+', 'UTC-', 'GMT+', 'GMT-', 'UT+' or 'UT-'
-* <li><code>{utcPrefix}{offset}</code> - a {@code ZoneOffset} ID equal to '{offset}'
+*  then the ID is a prefixed offset-based ID. The ID is split in two, with
-* <li><code>{regionID}</code> - full region ID, loaded from configuration
+*  a two or three letter prefix and a suffix starting with the sign.
-* </ul><p>
+*  The suffix is parsed as a {@link ZoneOffset#of(String) ZoneOffset}.
-* The {offset} is a valid format for {@link ZoneOffset#of(String)}, excluding 'Z'.
+*  The result will be a {@code ZoneId} with the specified UTC/GMT/UT prefix
-* The {utcPrefix} is 'UTC', 'GMT' or 'UT'.
+*  and the normalized offset ID as per {@link ZoneOffset#getId()}.
-* Region IDs must match the regular expression <code>[A-Za-z][A-Za-z0-9~/._+-]+</code>.
+*  The rules of the returned {@code ZoneId} will be equivalent to the
-* <p>
+*  parsed {@code ZoneOffset}.
-* The detailed format of the region ID depends on the group supplying the data.
+* <li>All other IDs are parsed as region-based zone IDs. Region IDs must
-* The default set of data is supplied by the IANA Time Zone Database (TZDB)
+*  match the regular expression <code>[A-Za-z][A-Za-z0-9~/._+-]+</code>
-* This has region IDs of the form '{area}/{city}', such as 'Europe/Paris' or 'America/New_York'.
+*  otherwise a {@code DateTimeException} is thrown. If the zone ID is not
-* This is compatible with most IDs from {@link java.util.TimeZone}.
+*  in the configured set of IDs, {@code ZoneRulesException} is thrown.
+*  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}.
+* </ul>
 *
 * @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 ZoneRulesException if the zone ID is a region ID that cannot be found
 */
 public static ZoneId of(String zoneId) {
+return of(zoneId, true);
+}
+/**
+* Parses the ID, taking a flag to indicate whether {@code ZoneRulesException}
+* should be thrown or not, used in deserialization.
+*
+* @param zoneId  the time-zone ID, not null
+* @param checkAvailable  whether to check if the zone ID is available
+* @return the zone ID, not null
+* @throws DateTimeException if the ID format is invalid
+* @throws ZoneRulesException if checking availability and the ID cannot be found
+*/
+static ZoneId of(String zoneId, boolean checkAvailable) {
 Objects.requireNonNull(zoneId, "zoneId");
 if (zoneId.length() <= 1 || zoneId.startsWith("+") || zoneId.startsWith("-")) {
 return ZoneOffset.of(zoneId);
 } else if (zoneId.startsWith("UTC") || zoneId.startsWith("GMT")) {
-return ofWithPrefix(zoneId, 3);
+return ofWithPrefix(zoneId, 3, checkAvailable);
 } else if (zoneId.startsWith("UT")) {
-return ofWithPrefix(zoneId, 2);
+return ofWithPrefix(zoneId, 2, checkAvailable);
 }
-return ZoneRegion.ofId(zoneId, true);
+return ZoneRegion.ofId(zoneId, checkAvailable);
 }
 /**
 * Parse once a prefix is established.
 *
 * @param zoneId  the time-zone ID, not null
 * @param prefixLength  the length of the prefix, 2 or 3
 * @return the zone ID, not null
-* @return the zone ID, not null
 * @throws DateTimeException if the zone ID has an invalid format
 */
-private static ZoneId ofWithPrefix(String zoneId, int prefixLength) {
+private static ZoneId ofWithPrefix(String zoneId, int prefixLength, boolean checkAvailable) {
-if (zoneId.length() == prefixLength ||
+String prefix = zoneId.substring(0, prefixLength);
-(zoneId.length() == prefixLength + 1 && zoneId.charAt(prefixLength) == '0')) {
+if (zoneId.length() == prefixLength) {
-return ZoneOffset.UTC;
+return ZoneRegion.ofPrefixedOffset(prefix, ZoneOffset.UTC);
 }
-if (zoneId.charAt(prefixLength) == '+' || zoneId.charAt(prefixLength) == '-') {
+if (zoneId.charAt(prefixLength) != '+' && zoneId.charAt(prefixLength) != '-') {
-try {
+return ZoneRegion.ofId(zoneId, checkAvailable);  // drop through to ZoneRulesProvider
-return ZoneOffset.of(zoneId.substring(prefixLength));
+}
-} catch (DateTimeException ex) {
+try {
-throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId, ex);
+ZoneOffset offset = ZoneOffset.of(zoneId.substring(prefixLength));
+if (offset == ZoneOffset.UTC) {
+return ZoneRegion.ofPrefixedOffset(prefix, offset);
 }
-}
+return ZoneRegion.ofPrefixedOffset(prefix + offset.toString(), offset);
-throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId);
+} catch (DateTimeException ex) {
+throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId, ex);
+}
 }
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code ZoneId} from a temporal object.
 * <p>
 * A {@code TemporalAccessor} represents some form of date and time information.
 * This factory converts the arbitrary temporal object to an instance of {@code ZoneId}.
 * <p>
 * The conversion will try to obtain the zone in a way that favours region-based
-* zones over offset-based zones using {@link Queries#zone()}.
+* zones over offset-based zones using {@link TemporalQuery#zone()}.
 * <p>
 * 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());
+ZoneId obj = temporal.query(TemporalQuery.zone());
 if (obj == null) {
 throw new DateTimeException("Unable to obtain ZoneId from TemporalAccessor: " + temporal.getClass());
 }
 return obj;
 }
 */
 public abstract String getId();
 //-----------------------------------------------------------------------
 /**
-* Gets the time-zone rules for this ID allowing calculations to be performed.
-* <p>
-* The rules provide the functionality associated with a time-zone,
-* such as finding the offset for a given instant or local date-time.
-* <p>
-* 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.
-* <p>
-* 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.
-* <p>
-* {@link ZoneOffset} will always return a set of rules where the offset never changes.
-*
-* @return the rules, not null
-* @throws ZoneRulesException 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'.
 * <p>
 * This returns the textual name used to identify the time-zone ID,
 * suitable for presentation to the user.
 * @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 getDisplayName(TextStyle style, Locale locale) {
-return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).format(new TemporalAccessor() {
+return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).format(toTemporal());
+}
+/**
+* Converts this zone to a {@code TemporalAccessor}.
+* <p>
+* A {@code ZoneId} can be fully represented as a {@code TemporalAccessor}.
+* However, the interface is not implemented by this class as most of the
+* methods on the interface have no meaning to {@code ZoneId}.
+* <p>
+* The returned temporal has no supported fields, with the query method
+* supporting the return of the zone using {@link TemporalQuery#zoneId()}.
+*
+* @return a temporal equivalent to this zone, not null
+*/
+private TemporalAccessor toTemporal() {
+return new TemporalAccessor() {
 @Override
 public boolean isSupported(TemporalField field) {
 return false;
 }
 @Override
 public long getLong(TemporalField field) {
-throw new DateTimeException("Unsupported field: " + field);
+throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
 }
 @SuppressWarnings("unchecked")
 @Override
 public <R> R query(TemporalQuery<R> query) {
-if (query == Queries.zoneId()) {
+if (query == TemporalQuery.zoneId()) {
 return (R) ZoneId.this;
 }
 return TemporalAccessor.super.query(query);
 }
-});
+};
+}
+//-----------------------------------------------------------------------
+/**
+* Gets the time-zone rules for this ID allowing calculations to be performed.
+* <p>
+* The rules provide the functionality associated with a time-zone,
+* such as finding the offset for a given instant or local date-time.
+* <p>
+* A time-zone can be invalid if it is deserialized in a Java Runtime which
+* does not have the same rules loaded as the Java Runtime that stored it.
+* In this case, calling this method will throw a {@code ZoneRulesException}.
+* <p>
+* The rules are supplied by {@link ZoneRulesProvider}. An advanced provider may
+* support dynamic updates to the rules without restarting the Java Runtime.
+* If so, then the result of this method may change over time.
+* Each individual call will be still remain thread-safe.
+* <p>
+* {@link ZoneOffset} will always return a set of rules where the offset never changes.
+*
+* @return the rules, not null
+* @throws ZoneRulesException if no rules are available for this ID
+*/
+public abstract ZoneRules getRules();
+/**
+* Normalizes the time-zone ID, returning a {@code ZoneOffset} where possible.
+* <p>
+* The returns a normalized {@code ZoneId} that can be used in place of this ID.
+* The result will have {@code ZoneRules} equivalent to those returned by this object,
+* however the ID returned by {@code getId()} may be different.
+* <p>
+* The normalization checks if the rules of this {@code ZoneId} have a fixed offset.
+* If they do, then the {@code ZoneOffset} equal to that offset is returned.
+* Otherwise {@code this} is returned.
+*
+* @return the time-zone unique ID, not null
+*/
+public ZoneId normalized() {
+try {
+ZoneRules rules = getRules();
+if (rules.isFixedOffset()) {
+return rules.getOffset(Instant.EPOCH);
+}
+} catch (ZoneRulesException ex) {
+// invalid ZoneRegion is not important to this method
+}
+return this;
 }
 //-----------------------------------------------------------------------
 /**
 * Checks if this time-zone ID is equal to another time-zone ID.
 * <a href="../../serialized-form.html#java.time.Ser">dedicated serialized form</a>.
 * <pre>
 *  out.writeByte(7);  // identifies this as a ZoneId (not ZoneOffset)
 *  out.writeUTF(zoneId);
 * </pre>
+* <p>
+* When read back in, the {@code ZoneId} will be created as though using
+* {@link #of(String)}, but without any exception in the case where the
+* ID has a valid format, but is not in the known set of region-based IDs.
 *
 * @return the instance of {@code Ser}, not null
 */
 // this is here for serialization Javadoc
 private Object writeReplace() {

changeset 16852	60207b2b4b42
parent 15658	55b829ca2334
child 17474	8c100beabcc0