* Time-zone information is categorized as a set of rules defining when and * how the offset from UTC/Greenwich changes. These rules are accessed using * identifiers based on geographical regions, such as countries or states. * The most common region classification is the Time Zone Database (TZDB), * which defines regions such as 'Europe/Paris' and 'Asia/Tokyo'. *
* The region identifier, modeled by this class, is distinct from the * underlying rules, modeled by {@link ZoneRules}. * The rules are defined by governments and change frequently. * By contrast, the region identifier is well-defined and long-lived. * This separation also allows rules to be shared between regions if appropriate. * *
* This method parses the ID and applies any appropriate normalization. * It does not validate the ID against the known set of IDs for which rules are available. *
* This method is intended for advanced use cases. * For example, consider a system that always retrieves time-zone rules from a remote server. * Using this factory would allow a {@code ZoneRegion}, and thus a {@code ZonedDateTime}, * to be created without loading the rules from the remote server. * * @param zoneId the time-zone ID, not null * @return the zone ID, not null * @throws DateTimeException if the ID format is invalid */ private static ZoneRegion ofLenient(String zoneId) { return ofId(zoneId, false); } /** * Obtains an instance of {@code ZoneId} from an identifier. * * @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 ZoneRegion ofId(String zoneId, boolean checkAvailable) { Objects.requireNonNull(zoneId, "zoneId"); if (zoneId.length() < 2 || zoneId.startsWith("UT") || // includes UTC zoneId.startsWith("GMT") || (PATTERN.matcher(zoneId).matches() == false)) { throw new DateTimeException("Invalid ID for region-based ZoneId, invalid format: " + zoneId); } ZoneRules rules = null; try { // always attempt load for better behavior after deserialization rules = ZoneRulesProvider.getRules(zoneId, true); } catch (ZoneRulesException ex) { if (checkAvailable) { throw ex; } } return new ZoneRegion(zoneId, rules); } //------------------------------------------------------------------------- /** * Constructor. * * @param id the time-zone ID, not null * @param rules the rules, null for lazy lookup */ ZoneRegion(String id, ZoneRules rules) { this.id = id; this.rules = rules; } //----------------------------------------------------------------------- @Override public String getId() { return id; } @Override public ZoneRules getRules() { // additional query for group provider when null allows for possibility // that the provider was updated after the ZoneId was created return (rules != null ? rules : ZoneRulesProvider.getRules(id, false)); } //----------------------------------------------------------------------- /** * Writes the object using a * dedicated serialized form. *
* out.writeByte(7); // identifies this as a ZoneId (not ZoneOffset)
* out.writeUTF(zoneId);
*
*
* @return the instance of {@code Ser}, not null
*/
private Object writeReplace() {
return new Ser(Ser.ZONE_REGION_TYPE, this);
}
/**
* Defend against malicious streams.
* @return never
* @throws InvalidObjectException always
*/
private Object readResolve() throws ObjectStreamException {
throw new InvalidObjectException("Deserialization via serialization delegate");
}
@Override
void write(DataOutput out) throws IOException {
out.writeByte(Ser.ZONE_REGION_TYPE);
writeExternal(out);
}
void writeExternal(DataOutput out) throws IOException {
out.writeUTF(id);
}
static ZoneId readExternal(DataInput in) throws IOException {
String id = in.readUTF();
return ofLenient(id);
}
}