1/* GENERATED SOURCE. DO NOT MODIFY. */ 2/* 3 ******************************************************************************* 4 * Copyright (C) 2011-2016, International Business Machines Corporation and 5 * others. All Rights Reserved. 6 ******************************************************************************* 7 */ 8package android.icu.text; 9 10import java.io.Serializable; 11import java.util.Collection; 12import java.util.Collections; 13import java.util.EnumSet; 14import java.util.Locale; 15import java.util.Set; 16 17import android.icu.impl.ICUConfig; 18import android.icu.impl.SoftCache; 19import android.icu.impl.TZDBTimeZoneNames; 20import android.icu.impl.TimeZoneNamesImpl; 21import android.icu.util.TimeZone; 22import android.icu.util.ULocale; 23 24/** 25 * <code>TimeZoneNames</code> is an abstract class representing the time zone display name data model defined 26 * by <a href="http://www.unicode.org/reports/tr35/">UTS#35 Unicode Locale Data Markup Language (LDML)</a>. 27 * The model defines meta zone, which is used for storing a set of display names. A meta zone can be shared 28 * by multiple time zones. Also a time zone may have multiple meta zone historic mappings. 29 * <p> 30 * For example, people in the United States refer the zone used by the east part of North America as "Eastern Time". 31 * The tz database contains multiple time zones "America/New_York", "America/Detroit", "America/Montreal" and some 32 * others that belong to "Eastern Time". However, assigning different display names to these time zones does not make 33 * much sense for most of people. 34 * <p> 35 * In <a href="http://cldr.unicode.org/">CLDR</a> (which uses LDML for representing locale data), the display name 36 * "Eastern Time" is stored as long generic display name of a meta zone identified by the ID "America_Eastern". 37 * Then, there is another table maintaining the historic mapping to meta zones for each time zone. The time zones in 38 * the above example ("America/New_York", "America/Detroit"...) are mapped to the meta zone "America_Eastern". 39 * <p> 40 * Sometimes, a time zone is mapped to a different time zone in the past. For example, "America/Indiana/Knox" 41 * had been moving "Eastern Time" and "Central Time" back and forth. Therefore, it is necessary that time zone 42 * to meta zones mapping data are stored by date range. 43 * 44 * <p><b>Note:</b> 45 * <p> 46 * {@link TimeZoneFormat} assumes an instance of <code>TimeZoneNames</code> is immutable. If you want to provide 47 * your own <code>TimeZoneNames</code> implementation and use it with {@link TimeZoneFormat}, you must follow 48 * the contract. 49 * <p> 50 * The methods in this class assume that time zone IDs are already canonicalized. For example, you may not get proper 51 * result returned by a method with time zone ID "America/Indiana/Indianapolis", because it's not a canonical time zone 52 * ID (the canonical time zone ID for the time zone is "America/Indianapolis". See 53 * {@link TimeZone#getCanonicalID(String)} about ICU canonical time zone IDs. 54 * 55 * <p> 56 * In CLDR, most of time zone display names except location names are provided through meta zones. But a time zone may 57 * have a specific name that is not shared with other time zones. 58 * 59 * For example, time zone "Europe/London" has English long name for standard time "Greenwich Mean Time", which is also 60 * shared with other time zones. However, the long name for daylight saving time is "British Summer Time", which is only 61 * used for "Europe/London". 62 * 63 * <p> 64 * {@link #getTimeZoneDisplayName(String, NameType)} is designed for accessing a name only used by a single time zone. 65 * But is not necessarily mean that a subclass implementation use the same model with CLDR. A subclass implementation 66 * may provide time zone names only through {@link #getTimeZoneDisplayName(String, NameType)}, or only through 67 * {@link #getMetaZoneDisplayName(String, NameType)}, or both. 68 * 69 * <p> 70 * The default <code>TimeZoneNames</code> implementation returned by {@link #getInstance(ULocale)} uses the locale data 71 * imported from CLDR. In CLDR, set of meta zone IDs and mappings between zone IDs and meta zone IDs are shared by all 72 * locales. Therefore, the behavior of {@link #getAvailableMetaZoneIDs()}, {@link #getAvailableMetaZoneIDs(String)}, 73 * {@link #getMetaZoneID(String, long)}, and {@link #getReferenceZoneID(String, String)} won't be changed no matter 74 * what locale is used for getting an instance of <code>TimeZoneNames</code>. 75 */ 76public abstract class TimeZoneNames implements Serializable { 77 78 private static final long serialVersionUID = -9180227029248969153L; 79 80 /** 81 * Time zone display name types 82 */ 83 public enum NameType { 84 /** 85 * Long display name, such as "Eastern Time". 86 */ 87 LONG_GENERIC, 88 /** 89 * Long display name for standard time, such as "Eastern Standard Time". 90 */ 91 LONG_STANDARD, 92 /** 93 * Long display name for daylight saving time, such as "Eastern Daylight Time". 94 */ 95 LONG_DAYLIGHT, 96 /** 97 * Short display name, such as "ET". 98 */ 99 SHORT_GENERIC, 100 /** 101 * Short display name for standard time, such as "EST". 102 */ 103 SHORT_STANDARD, 104 /** 105 * Short display name for daylight saving time, such as "EDT". 106 */ 107 SHORT_DAYLIGHT, 108 /** 109 * Exemplar location name, such as "Los Angeles". 110 */ 111 EXEMPLAR_LOCATION, 112 } 113 114 private static Cache TZNAMES_CACHE = new Cache(); 115 116 private static final Factory TZNAMES_FACTORY; 117 private static final String FACTORY_NAME_PROP = "android.icu.text.TimeZoneNames.Factory.impl"; 118 private static final String DEFAULT_FACTORY_CLASS = "android.icu.impl.TimeZoneNamesFactoryImpl"; 119 120 static { 121 Factory factory = null; 122 String classname = ICUConfig.get(FACTORY_NAME_PROP, DEFAULT_FACTORY_CLASS); 123 while (true) { 124 try { 125 factory = (Factory) Class.forName(classname).newInstance(); 126 break; 127 } catch (ClassNotFoundException cnfe) { 128 // fall through 129 } catch (IllegalAccessException iae) { 130 // fall through 131 } catch (InstantiationException ie) { 132 // fall through 133 } 134 if (classname.equals(DEFAULT_FACTORY_CLASS)) { 135 break; 136 } 137 classname = DEFAULT_FACTORY_CLASS; 138 } 139 140 if (factory == null) { 141 factory = new DefaultTimeZoneNames.FactoryImpl(); 142 } 143 TZNAMES_FACTORY = factory; 144 } 145 146 /** 147 * Returns an instance of <code>TimeZoneNames</code> for the specified locale. 148 * 149 * @param locale 150 * The locale. 151 * @return An instance of <code>TimeZoneNames</code> 152 */ 153 public static TimeZoneNames getInstance(ULocale locale) { 154 String key = locale.getBaseName(); 155 return TZNAMES_CACHE.getInstance(key, locale); 156 } 157 158 /** 159 * Returns an instance of <code>TimeZoneNames</code> for the specified 160 * {@link java.util.Locale}. 161 * 162 * @param locale 163 * The {@link java.util.Locale}. 164 * @return An instance of <code>TimeZoneDisplayNames</code> 165 */ 166 public static TimeZoneNames getInstance(Locale locale) { 167 return getInstance(ULocale.forLocale(locale)); 168 } 169 170 /** 171 * Returns an instance of <code>TimeZoneNames</code> containing only short specific 172 * zone names ({@link NameType#SHORT_STANDARD} and {@link NameType#SHORT_DAYLIGHT}), 173 * compatible with the IANA tz database's zone abbreviations (not localized). 174 * <br> 175 * Note: The input locale is used for resolving ambiguous names (e.g. "IST" is parsed 176 * as Israel Standard Time for Israel, while it is parsed as India Standard Time for 177 * all other regions). The zone names returned by this instance are not localized. 178 */ 179 public static TimeZoneNames getTZDBInstance(ULocale locale) { 180 return new TZDBTimeZoneNames(locale); 181 } 182 183 /** 184 * Returns an immutable set of all available meta zone IDs. 185 * @return An immutable set of all available meta zone IDs. 186 */ 187 public abstract Set<String> getAvailableMetaZoneIDs(); 188 189 /** 190 * Returns an immutable set of all available meta zone IDs used by the given time zone. 191 * 192 * @param tzID 193 * The canonical time zone ID. 194 * @return An immutable set of all available meta zone IDs used by the given time zone. 195 */ 196 public abstract Set<String> getAvailableMetaZoneIDs(String tzID); 197 198 /** 199 * Returns the meta zone ID for the given canonical time zone ID at the given date. 200 * 201 * @param tzID 202 * The canonical time zone ID. 203 * @param date 204 * The date. 205 * @return The meta zone ID for the given time zone ID at the given date. If the time zone does not have a 206 * corresponding meta zone at the given date or the implementation does not support meta zones, null is 207 * returned. 208 */ 209 public abstract String getMetaZoneID(String tzID, long date); 210 211 /** 212 * Returns the reference zone ID for the given meta zone ID for the region. 213 * 214 * Note: Each meta zone must have a reference zone associated with a special region "001" (world). 215 * Some meta zones may have region specific reference zone IDs other than the special region 216 * "001". When a meta zone does not have any region specific reference zone IDs, this method 217 * return the reference zone ID for the special region "001" (world). 218 * 219 * @param mzID 220 * The meta zone ID. 221 * @param region 222 * The region. 223 * @return The reference zone ID ("golden zone" in the LDML specification) for the given time zone ID for the 224 * region. If the meta zone is unknown or the implementation does not support meta zones, null is returned. 225 */ 226 public abstract String getReferenceZoneID(String mzID, String region); 227 228 /** 229 * Returns the display name of the meta zone. 230 * 231 * @param mzID 232 * The meta zone ID. 233 * @param type 234 * The display name type. See {@link TimeZoneNames.NameType}. 235 * @return The display name of the meta zone. When this object does not have a localized display name for the given 236 * meta zone with the specified type or the implementation does not provide any display names associated 237 * with meta zones, null is returned. 238 */ 239 public abstract String getMetaZoneDisplayName(String mzID, NameType type); 240 241 /** 242 * Returns the display name of the time zone at the given date. 243 * 244 * <p> 245 * <b>Note:</b> This method calls the subclass's {@link #getTimeZoneDisplayName(String, NameType)} first. When the 246 * result is null, this method calls {@link #getMetaZoneID(String, long)} to get the meta zone ID mapped from the 247 * time zone, then calls {@link #getMetaZoneDisplayName(String, NameType)}. 248 * 249 * @param tzID 250 * The canonical time zone ID. 251 * @param type 252 * The display name type. See {@link TimeZoneNames.NameType}. 253 * @param date 254 * The date 255 * @return The display name for the time zone at the given date. When this object does not have a localized display 256 * name for the time zone with the specified type and date, null is returned. 257 */ 258 public final String getDisplayName(String tzID, NameType type, long date) { 259 String name = getTimeZoneDisplayName(tzID, type); 260 if (name == null) { 261 String mzID = getMetaZoneID(tzID, date); 262 name = getMetaZoneDisplayName(mzID, type); 263 } 264 return name; 265 } 266 267 /** 268 * Returns the display name of the time zone. Unlike {@link #getDisplayName(String, NameType, long)}, 269 * this method does not get a name from a meta zone used by the time zone. 270 * 271 * @param tzID 272 * The canonical time zone ID. 273 * @param type 274 * The display name type. See {@link TimeZoneNames.NameType}. 275 * @return The display name for the time zone. When this object does not have a localized display name for the given 276 * time zone with the specified type, null is returned. 277 */ 278 public abstract String getTimeZoneDisplayName(String tzID, NameType type); 279 280 /** 281 * Returns the exemplar location name for the given time zone. When this object does not have a localized location 282 * name, the default implementation may still returns a programmatically generated name with the logic described 283 * below. 284 * <ol> 285 * <li>Check if the ID contains "/". If not, return null. 286 * <li>Check if the ID does not start with "Etc/" or "SystemV/". If it does, return null. 287 * <li>Extract a substring after the last occurrence of "/". 288 * <li>Replace "_" with " ". 289 * </ol> 290 * For example, "New York" is returned for the time zone ID "America/New_York" when this object does not have the 291 * localized location name. 292 * 293 * @param tzID 294 * The canonical time zone ID 295 * @return The exemplar location name for the given time zone, or null when a localized location name is not 296 * available and the fallback logic described above cannot extract location from the ID. 297 */ 298 public String getExemplarLocationName(String tzID) { 299 return TimeZoneNamesImpl.getDefaultExemplarLocationName(tzID); 300 } 301 302 /** 303 * Finds time zone name prefix matches for the input text at the 304 * given offset and returns a collection of the matches. 305 * 306 * @param text the text. 307 * @param start the starting offset within the text. 308 * @param types the set of name types, or <code>null</code> for all name types. 309 * @return A collection of matches. 310 * @see NameType 311 * @see MatchInfo 312 * @hide draft / provisional / internal are hidden on Android 313 */ 314 public Collection<MatchInfo> find(CharSequence text, int start, EnumSet<NameType> types) { 315 throw new UnsupportedOperationException("The method is not implemented in TimeZoneNames base class."); 316 } 317 318 /** 319 * A <code>MatchInfo</code> represents a time zone name match used by 320 * {@link TimeZoneNames#find(CharSequence, int, EnumSet)}. 321 * @hide draft / provisional / internal are hidden on Android 322 */ 323 public static class MatchInfo { 324 private NameType _nameType; 325 private String _tzID; 326 private String _mzID; 327 private int _matchLength; 328 329 /** 330 * Constructing a <code>MatchInfo</code>. 331 * 332 * @param nameType the name type enum. 333 * @param tzID the time zone ID, or null 334 * @param mzID the meta zone ID, or null 335 * @param matchLength the match length. 336 * @throws IllegalArgumentException when 1) <code>nameType</code> is <code>null</code>, 337 * or 2) both <code>tzID</code> and <code>mzID</code> are <code>null</code>, 338 * or 3) <code>matchLength</code> is 0 or smaller. 339 * @see NameType 340 * @hide draft / provisional / internal are hidden on Android 341 */ 342 public MatchInfo(NameType nameType, String tzID, String mzID, int matchLength) { 343 if (nameType == null) { 344 throw new IllegalArgumentException("nameType is null"); 345 } 346 if (tzID == null && mzID == null) { 347 throw new IllegalArgumentException("Either tzID or mzID must be available"); 348 } 349 if (matchLength <= 0) { 350 throw new IllegalArgumentException("matchLength must be positive value"); 351 } 352 _nameType = nameType; 353 _tzID = tzID; 354 _mzID = mzID; 355 _matchLength = matchLength; 356 } 357 358 /** 359 * Returns the time zone ID, or <code>null</code> if not available. 360 * 361 * <p><b>Note</b>: A <code>MatchInfo</code> must have either a time zone ID 362 * or a meta zone ID. 363 * 364 * @return the time zone ID, or <code>null</code>. 365 * @see #mzID() 366 * @hide draft / provisional / internal are hidden on Android 367 */ 368 public String tzID() { 369 return _tzID; 370 } 371 372 /** 373 * Returns the meta zone ID, or <code>null</code> if not available. 374 * 375 * <p><b>Note</b>: A <code>MatchInfo</code> must have either a time zone ID 376 * or a meta zone ID. 377 * 378 * @return the meta zone ID, or <code>null</code>. 379 * @see #tzID() 380 * @hide draft / provisional / internal are hidden on Android 381 */ 382 public String mzID() { 383 return _mzID; 384 } 385 386 /** 387 * Returns the time zone name type. 388 * @return the time zone name type enum. 389 * @see NameType 390 * @hide draft / provisional / internal are hidden on Android 391 */ 392 public NameType nameType() { 393 return _nameType; 394 } 395 396 /** 397 * Returns the match length. 398 * @return the match length. 399 * @hide draft / provisional / internal are hidden on Android 400 */ 401 public int matchLength() { 402 return _matchLength; 403 } 404 } 405 406 /** 407 * @deprecated This API is ICU internal only. 408 * @hide original deprecated declaration 409 * @hide draft / provisional / internal are hidden on Android 410 */ 411 @Deprecated 412 public void loadAllDisplayNames() {} 413 414 /** 415 * @deprecated This API is ICU internal only. 416 * @hide original deprecated declaration 417 * @hide draft / provisional / internal are hidden on Android 418 */ 419 @Deprecated 420 public void getDisplayNames(String tzID, NameType[] types, long date, 421 String[] dest, int destOffset) { 422 if (tzID == null || tzID.length() == 0) { 423 return; 424 } 425 String mzID = null; 426 for (int i = 0; i < types.length; ++i) { 427 NameType type = types[i]; 428 String name = getTimeZoneDisplayName(tzID, type); 429 if (name == null) { 430 if (mzID == null) { 431 mzID = getMetaZoneID(tzID, date); 432 } 433 name = getMetaZoneDisplayName(mzID, type); 434 } 435 dest[destOffset + i] = name; 436 } 437 } 438 439 /** 440 * Sole constructor for invocation by subclass constructors. 441 * 442 * @hide draft / provisional / internal are hidden on Android 443 */ 444 protected TimeZoneNames() { 445 } 446 447 /** 448 * The super class of <code>TimeZoneNames</code> service factory classes. 449 * 450 * @deprecated This API is ICU internal only. 451 * @hide original deprecated declaration 452 * @hide draft / provisional / internal are hidden on Android 453 */ 454 @Deprecated 455 public static abstract class Factory { 456 /** 457 * The factory method of <code>TimeZoneNames</code>. 458 * 459 * @param locale 460 * The display locale 461 * @return An instance of <code>TimeZoneNames</code>. 462 * @deprecated This API is ICU internal only. 463 * @hide original deprecated declaration 464 * @hide draft / provisional / internal are hidden on Android 465 */ 466 @Deprecated 467 public abstract TimeZoneNames getTimeZoneNames(ULocale locale); 468 469 /** 470 * Sole constructor 471 * @deprecated This API is ICU internal only. 472 * @hide original deprecated declaration 473 * @hide draft / provisional / internal are hidden on Android 474 */ 475 @Deprecated 476 protected Factory() { 477 } 478 } 479 480 /** 481 * TimeZoneNames cache used by {@link TimeZoneNames#getInstance(ULocale)} 482 */ 483 private static class Cache extends SoftCache<String, TimeZoneNames, ULocale> { 484 485 /* 486 * (non-Javadoc) 487 * 488 * @see android.icu.impl.CacheBase#createInstance(java.lang.Object, java.lang.Object) 489 */ 490 @Override 491 protected TimeZoneNames createInstance(String key, ULocale data) { 492 return TZNAMES_FACTORY.getTimeZoneNames(data); 493 } 494 495 } 496 497 ///CLOVER:OFF 498 /** 499 * The default implementation of <code>TimeZoneNames</code> used by {@link TimeZoneNames#getInstance(ULocale)} when 500 * the ICU4J tznamedata component is not available. 501 */ 502 private static class DefaultTimeZoneNames extends TimeZoneNames { 503 504 private static final long serialVersionUID = -995672072494349071L; 505 506 public static final DefaultTimeZoneNames INSTANCE = new DefaultTimeZoneNames(); 507 508 /* (non-Javadoc) 509 * @see android.icu.text.TimeZoneNames#getAvailableMetaZoneIDs() 510 */ 511 @Override 512 public Set<String> getAvailableMetaZoneIDs() { 513 return Collections.emptySet(); 514 } 515 516 /* (non-Javadoc) 517 * @see android.icu.text.TimeZoneNames#getAvailableMetaZoneIDs(java.lang.String) 518 */ 519 @Override 520 public Set<String> getAvailableMetaZoneIDs(String tzID) { 521 return Collections.emptySet(); 522 } 523 524 /* 525 * (non-Javadoc) 526 * 527 * @see android.icu.text.TimeZoneNames#getMetaZoneID (java.lang.String, long) 528 */ 529 @Override 530 public String getMetaZoneID(String tzID, long date) { 531 return null; 532 } 533 534 /* 535 * (non-Javadoc) 536 * 537 * @see android.icu.text.TimeZoneNames#getReferenceZoneID(java.lang.String, java.lang.String) 538 */ 539 @Override 540 public String getReferenceZoneID(String mzID, String region) { 541 return null; 542 } 543 544 /* 545 * (non-Javadoc) 546 * @see android.icu.text.TimeZoneNames#getMetaZoneDisplayName(java.lang.String, android.icu.text.TimeZoneNames.NameType) 547 */ 548 @Override 549 public String getMetaZoneDisplayName(String mzID, NameType type) { 550 return null; 551 } 552 553 /* 554 * (non-Javadoc) 555 * @see android.icu.text.TimeZoneNames#getTimeZoneDisplayName(java.lang.String, android.icu.text.TimeZoneNames.NameType) 556 */ 557 @Override 558 public String getTimeZoneDisplayName(String tzID, NameType type) { 559 return null; 560 } 561 562 /* (non-Javadoc) 563 * @see android.icu.text.TimeZoneNames#find(java.lang.CharSequence, int, android.icu.text.TimeZoneNames.NameType[]) 564 */ 565 @Override 566 public Collection<MatchInfo> find(CharSequence text, int start, EnumSet<NameType> nameTypes) { 567 return Collections.emptyList(); 568 } 569 570 /** 571 * The default <code>TimeZoneNames</code> factory called from {@link TimeZoneNames#getInstance(ULocale)} when 572 * the ICU4J tznamedata component is not available. 573 */ 574 public static class FactoryImpl extends Factory { 575 576 /* 577 * (non-Javadoc) 578 * 579 * @see android.icu.text.TimeZoneNames.Factory#getTimeZoneNames (android.icu.util.ULocale) 580 */ 581 @Override 582 public TimeZoneNames getTimeZoneNames(ULocale locale) { 583 return DefaultTimeZoneNames.INSTANCE; 584 } 585 } 586 } 587 ///CLOVER:ON 588} 589