+ * 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;
+
+}