sample/java.util.ResourceBundle.Control.txt

   1 *java.util.ResourceBundle.Control* *ResourceBundle.Control* ResourceBundle.Contr
   2
   3 public static class ResourceBundle.Control
   4   extends    |java.lang.Object|
   5
   6 |java.util.ResourceBundle.Control_Description|
   7 |java.util.ResourceBundle.Control_Fields|
   8 |java.util.ResourceBundle.Control_Constructors|
   9 |java.util.ResourceBundle.Control_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.ResourceBundle.Control_Fields*
  14 |java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_CLASS|
  15 |java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_DEFAULT|
  16 |java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_PROPERTIES|
  17 |long_java.util.ResourceBundle.Control.TTL_DONT_CACHE|
  18 |long_java.util.ResourceBundle.Control.TTL_NO_EXPIRATION_CONTROL|
  19
  20 *java.util.ResourceBundle.Control_Constructors*
  21 |java.util.ResourceBundle.Control()|Sole constructor.
  22
  23 *java.util.ResourceBundle.Control_Methods*
  24 |java.util.ResourceBundle.Control.getCandidateLocales(String,Locale)|Returns a
  25 |java.util.ResourceBundle.Control.getControl(List<String>)|Returns a ResourceBu
  26 |java.util.ResourceBundle.Control.getFallbackLocale(String,Locale)|Returns a Lo
  27 |java.util.ResourceBundle.Control.getFormats(String)|Returns a List of Strings
  28 |java.util.ResourceBundle.Control.getNoFallbackControl(List<String>)|Returns a
  29 |java.util.ResourceBundle.Control.getTimeToLive(String,Locale)|Returns the time
  30 |java.util.ResourceBundle.Control.needsReload(String,Locale,String,ClassLoader,ResourceBundle,long)|
  31 |java.util.ResourceBundle.Control.newBundle(String,Locale,String,ClassLoader,boolean)|
  32 |java.util.ResourceBundle.Control.toBundleName(String,Locale)|Converts the give
  33 |java.util.ResourceBundle.Control.toResourceName(String,String)|Converts the gi
  34
  35 *java.util.ResourceBundle.Control_Description*
  36
  37 ResourceBundle.Control defines a set of callback methods that are invoked by
  38 the ResourceBundle.getBundle(|java.util.ResourceBundle|) factory methods during
  39 the bundle loading process. In other words, a ResourceBundle.Control
  40 collaborates with the factory methods for loading resource bundles. The default
  41 implementation of the callback methods provides the information necessary for
  42 the factory methods to perform the default behavior.
  43
  44 In addition to the callback methods, the
  45 toBundleName(|java.util.ResourceBundle.Control|) and
  46 toResourceName(|java.util.ResourceBundle.Control|) methods are defined
  47 primarily for convenience in implementing the callback methods. However, the
  48 toBundleName method could be overridden to provide different conventions in the
  49 organization and packaging of localized resources. The toResourceName method is
  50 final to avoid use of wrong resource and class name separators.
  51
  52 Two factory methods, (|java.util.ResourceBundle.Control|) and
  53 (|java.util.ResourceBundle.Control|) , provide ResourceBundle.Control instances
  54 that implement common variations of the default bundle loading process.
  55
  56 The formats returned by the getFormats(|java.util.ResourceBundle.Control|)
  57 method and candidate locales returned by the
  58 getCandidateLocales(|java.util.ResourceBundle.Control|) method must be
  59 consistent in all ResourceBundle.getBundle invocations for the same base
  60 bundle. Otherwise, the ResourceBundle.getBundle methods may return unintended
  61 bundles. For example, if only "java.class" is returned by the getFormats method
  62 for the first call to ResourceBundle.getBundle and only "java.properties" for
  63 the second call, then the second call will return the class-based one that has
  64 been cached during the first call.
  65
  66 A ResourceBundle.Control instance must be thread-safe if it's simultaneously
  67 used by multiple threads. ResourceBundle.getBundle does not synchronize to call
  68 the ResourceBundle.Control methods. The default implementations of the methods
  69 are thread-safe.
  70
  71 Applications can specify ResourceBundle.Control instances returned by the
  72 getControl factory methods or created from a subclass of ResourceBundle.Control
  73 to customize the bundle loading process. The following are examples of changing
  74 the default bundle loading process.
  75
  76 Example 1
  77
  78 The following code lets ResourceBundle.getBundle look up only properties-based
  79 resources.
  80
  81
  82
  83 import java.util.*; import static java.util.ResourceBundle.Control.*; ...
  84 ResourceBundle bundle = ResourceBundle.getBundle("MyResources", new
  85 Locale("fr", "CH"), ResourceBundle.Control.getControl(FORMAT_PROPERTIES));
  86
  87 Given the resource bundles in the example in the ResourceBundle.getBundle
  88 description, this ResourceBundle.getBundle call loads
  89 MyResources_fr_CH.properties whose parent is MyResources_fr.properties whose
  90 parent is MyResources.properties. (MyResources_fr_CH.properties is not hidden,
  91 but MyResources_fr_CH.class is.)
  92
  93 Example 2
  94
  95 The following is an example of loading XML-based bundles using
  96 Properties.loadFromXML(|java.util.Properties|) .
  97
  98
  99
 100 ResourceBundle rb = ResourceBundle.getBundle("Messages", new
 101 ResourceBundle.Control() { public List<String> getFormats(String baseName) { if
 102 (baseName == null) throw new NullPointerException(); return
 103 Arrays.asList("xml"); } public ResourceBundle newBundle(String baseName, Locale
 104 locale, String format, ClassLoader loader, boolean reload) throws
 105 IllegalAccessException, InstantiationException, IOException { if (baseName ==
 106 null || locale == null || format == null || loader == null) throw new
 107 NullPointerException(); ResourceBundle bundle = null; if (format.equals("xml"))
 108 { String bundleName = toBundleName(baseName, locale); String resourceName =
 109 toResourceName(bundleName, format); InputStream stream = null; if (reload) {
 110 URL url = loader.getResource(resourceName); if (url != null) { URLConnection
 111 connection = url.openConnection(); if (connection != null) { // Disable caches
 112 to get fresh data for // reloading. connection.setUseCaches(false); stream =
 113 connection.getInputStream(); } } } else { stream =
 114 loader.getResourceAsStream(resourceName); } if (stream != null) {
 115 BufferedInputStream bis = new BufferedInputStream(stream); bundle = new
 116 XMLResourceBundle(bis); bis.close(); } } return bundle; } });
 117
 118 ...
 119
 120 private static class XMLResourceBundle extends ResourceBundle { private
 121 Properties props; XMLResourceBundle(InputStream stream) throws IOException {
 122 props = new Properties(); props.loadFromXML(stream); } protected Object
 123 handleGetObject(String key) { return props.getProperty(key); } public
 124 Enumeration<String> getKeys() { ... } }
 125
 126
 127
 128 *java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_CLASS*
 129
 130 The class-only format List containing "java.class". This List is
 131 unmodifiable(|java.util.Collections|) .
 132
 133
 134 *java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_DEFAULT*
 135
 136 The default format List, which contains the strings "java.class" and
 137 "java.properties", in this order. This List is
 138 unmodifiable(|java.util.Collections|) .
 139
 140
 141 *java.util.List<java.lang.String>_java.util.ResourceBundle.Control.FORMAT_PROPERTIES*
 142
 143 The properties-only format List containing "java.properties". This List is
 144 unmodifiable(|java.util.Collections|) .
 145
 146
 147 *long_java.util.ResourceBundle.Control.TTL_DONT_CACHE*
 148
 149 The time-to-live constant for not caching loaded resource bundle instances.
 150
 151
 152 *long_java.util.ResourceBundle.Control.TTL_NO_EXPIRATION_CONTROL*
 153
 154 The time-to-live constant for disabling the expiration control for loaded
 155 resource bundle instances in the cache.
 156
 157
 158
 159 *java.util.ResourceBundle.Control()*
 160
 161 protected ResourceBundle.Control()
 162
 163 Sole constructor. (For invocation by subclass constructors, typically
 164 implicit.)
 165
 166
 167 *java.util.ResourceBundle.Control.getCandidateLocales(String,Locale)*
 168
 169 public |java.util.List|<Locale> getCandidateLocales(
 170   java.lang.String baseName,
 171   java.util.Locale locale)
 172
 173 Returns a List of Locales as candidate locales for baseName and locale. This
 174 method is called by the ResourceBundle.getBundle factory method each time the
 175 factory method tries finding a resource bundle for a target Locale.
 176
 177 The sequence of the candidate locales also corresponds to the runtime resource
 178 lookup path (also known as the parent chain), if the corresponding resource
 179 bundles for the candidate locales exist and their parents are not defined by
 180 loaded resource bundles themselves. The last element of the list must be a root
 181 locale(|java.util.Locale|) if it is desired to have the base bundle as the
 182 terminal of the parent chain.
 183
 184 If the given locale is equal to Locale.ROOT (the root locale), a List
 185 containing only the root Locale must be returned. In this case, the
 186 ResourceBundle.getBundle factory method loads only the base bundle as the
 187 resulting resource bundle.
 188
 189 It is not a requirement to return an immutable (unmodifiable) List. However,
 190 the returned List must not be mutated after it has been returned by
 191 getCandidateLocales.
 192
 193 The default implementation returns a List containing Locales in the following
 194 sequence:
 195
 196 Locale(language, country, variant) Locale(language, country) Locale(language)
 197 Locale.ROOT
 198
 199 where language, country and variant are the language, country and variant
 200 values of the given locale, respectively. Locales where the final component
 201 values are empty strings are omitted.
 202
 203 The default implementation uses an (|java.util.ArrayList|) that overriding
 204 implementations may modify before returning it to the caller. However, a
 205 subclass must not modify it after it has been returned by getCandidateLocales.
 206
 207 For example, if the given baseName is "Messages" and the given locale is
 208 Locale("ja","","XX"), then a List of Locales:
 209
 210 Locale("ja", "", "XX") Locale("ja") Locale.ROOT
 211
 212 is returned. And if the resource bundles for the "ja" and "" Locales are found,
 213 then the runtime resource lookup path (parent chain) is:
 214
 215 Messages_ja -> Messages
 216
 217
 218     baseName - the base name of the resource bundle, a fully qualified class name
 219     locale - the locale for which a resource bundle is desired
 220
 221     Returns: a List of candidate Locales for the given locale
 222
 223 *java.util.ResourceBundle.Control.getControl(List<String>)*
 224
 225 public static final |java.util.ResourceBundle.Control| getControl(java.util.List<java.lang.String> formats)
 226
 227 Returns a ResourceBundle.Control in which the
 228 getFormats(|java.util.ResourceBundle.Control|) method returns the specified
 229 formats. The formats must be equal to one of
 230 (|java.util.ResourceBundle.Control|) , (|java.util.ResourceBundle.Control|) or
 231 (|java.util.ResourceBundle.Control|) . ResourceBundle.Control instances
 232 returned by this method are singletons and thread-safe.
 233
 234 Specifying (|java.util.ResourceBundle.Control|) is equivalent to instantiating
 235 the ResourceBundle.Control class, except that this method returns a singleton.
 236
 237
 238     formats - the formats to be returned by the ResourceBundle.Control.getFormats method
 239
 240     Returns: a ResourceBundle.Control supporting the specified formats
 241
 242 *java.util.ResourceBundle.Control.getFallbackLocale(String,Locale)*
 243
 244 public |java.util.Locale| getFallbackLocale(
 245   java.lang.String baseName,
 246   java.util.Locale locale)
 247
 248 Returns a Locale to be used as a fallback locale for further resource bundle
 249 searches by the ResourceBundle.getBundle factory method. This method is called
 250 from the factory method every time when no resulting resource bundle has been
 251 found for baseName and locale, where locale is either the parameter for
 252 ResourceBundle.getBundle or the previous fallback locale returned by this
 253 method.
 254
 255 The method returns null if no further fallback search is desired.
 256
 257 The default implementation returns the default
 258 <code>Locale</code>(|java.util.Locale|) if the given locale isn't the default
 259 one. Otherwise, null is returned.
 260
 261
 262     baseName - the base name of the resource bundle, a fully qualified class name for which
 263        ResourceBundle.getBundle has been unable to find any resource bundles
 264        (except for the base bundle)
 265     locale - the Locale for which ResourceBundle.getBundle has been unable to find any
 266        resource bundles (except for the base bundle)
 267
 268     Returns: a Locale for the fallback search, or null if no further fallback search is
 269              desired.
 270
 271 *java.util.ResourceBundle.Control.getFormats(String)*
 272
 273 public |java.util.List|<String> getFormats(java.lang.String baseName)
 274
 275 Returns a List of Strings containing formats to be used to load resource
 276 bundles for the given baseName. The ResourceBundle.getBundle factory method
 277 tries to load resource bundles with formats in the order specified by the list.
 278 The list returned by this method must have at least one String. The predefined
 279 formats are "java.class" for class-based resource bundles and "java.properties"
 280 for properties-based(|java.util.PropertyResourceBundle|) ones. Strings starting
 281 with "java." are reserved for future extensions and must not be used by
 282 application-defined formats.
 283
 284 It is not a requirement to return an immutable (unmodifiable) List. However,
 285 the returned List must not be mutated after it has been returned by getFormats.
 286
 287 The default implementation returns (|java.util.ResourceBundle.Control|) so that
 288 the ResourceBundle.getBundle factory method looks up first class-based resource
 289 bundles, then properties-based ones.
 290
 291
 292     baseName - the base name of the resource bundle, a fully qualified class name
 293
 294     Returns: a List of Strings containing formats for loading resource bundles.
 295
 296 *java.util.ResourceBundle.Control.getNoFallbackControl(List<String>)*
 297
 298 public static final |java.util.ResourceBundle.Control| getNoFallbackControl(java.util.List<java.lang.String> formats)
 299
 300 Returns a ResourceBundle.Control in which the
 301 getFormats(|java.util.ResourceBundle.Control|) method returns the specified
 302 formats and the getFallbackLocale(|java.util.ResourceBundle.Control|) method
 303 returns null. The formats must be equal to one of
 304 (|java.util.ResourceBundle.Control|) , (|java.util.ResourceBundle.Control|) or
 305 (|java.util.ResourceBundle.Control|) . ResourceBundle.Control instances
 306 returned by this method are singletons and thread-safe.
 307
 308
 309     formats - the formats to be returned by the ResourceBundle.Control.getFormats method
 310
 311     Returns: a ResourceBundle.Control supporting the specified formats with no fallback
 312              Locale support
 313
 314 *java.util.ResourceBundle.Control.getTimeToLive(String,Locale)*
 315
 316 public long getTimeToLive(
 317   java.lang.String baseName,
 318   java.util.Locale locale)
 319
 320 Returns the time-to-live (TTL) value for resource bundles that are loaded under
 321 this ResourceBundle.Control. Positive time-to-live values specify the number of
 322 milliseconds a bundle can remain in the cache without being validated against
 323 the source data from which it was constructed. The value 0 indicates that a
 324 bundle must be validated each time it is retrieved from the cache.
 325 (|java.util.ResourceBundle.Control|) specifies that loaded resource bundles are
 326 not put in the cache. (|java.util.ResourceBundle.Control|) specifies that
 327 loaded resource bundles are put in the cache with no expiration control.
 328
 329 The expiration affects only the bundle loading process by the
 330 ResourceBundle.getBundle factory method. That is, if the factory method finds a
 331 resource bundle in the cache that has expired, the factory method calls the
 332 needsReload(|java.util.ResourceBundle.Control|) method to determine whether the
 333 resource bundle needs to be reloaded. If needsReload returns true, the cached
 334 resource bundle instance is removed from the cache. Otherwise, the instance
 335 stays in the cache, updated with the new TTL value returned by this method.
 336
 337 All cached resource bundles are subject to removal from the cache due to memory
 338 constraints of the runtime environment. Returning a large positive value
 339 doesn't mean to lock loaded resource bundles in the cache.
 340
 341 The default implementation returns (|java.util.ResourceBundle.Control|) .
 342
 343
 344     baseName - the base name of the resource bundle for which the expiration value is
 345        specified.
 346     locale - the locale of the resource bundle for which the expiration value is specified.
 347
 348     Returns: the time (0 or a positive millisecond offset from the cached time) to get
 349              loaded bundles expired in the cache, {@link
 350              #TTL_NO_EXPIRATION_CONTROL} to disable the expiration control, or
 351              {@link #TTL_DONT_CACHE} to disable caching.
 352
 353 *java.util.ResourceBundle.Control.needsReload(String,Locale,String,ClassLoader,ResourceBundle,long)*
 354
 355 public boolean needsReload(
 356   java.lang.String baseName,
 357   java.util.Locale locale,
 358   java.lang.String format,
 359   java.lang.ClassLoader loader,
 360   java.util.ResourceBundle bundle,
 361   long loadTime)
 362
 363 Determines if the expired bundle in the cache needs to be reloaded based on the
 364 loading time given by loadTime or some other criteria. The method returns true
 365 if reloading is required; false otherwise. loadTime is a millisecond offset
 366 since the Calendar Epoch.
 367
 368 The calling ResourceBundle.getBundle factory method calls this method on the
 369 ResourceBundle.Control instance used for its current invocation, not on the
 370 instance used in the invocation that originally loaded the resource bundle.
 371
 372 The default implementation compares loadTime and the last modified time of the
 373 source data of the resource bundle. If it's determined that the source data has
 374 been modified since loadTime, true is returned. Otherwise, false is returned.
 375 This implementation assumes that the given format is the same string as its
 376 file suffix if it's not one of the default formats, "java.class" or
 377 "java.properties".
 378
 379
 380     baseName - the base bundle name of the resource bundle, a fully qualified class name
 381     locale - the locale for which the resource bundle should be instantiated
 382     format - the resource bundle format to be loaded
 383     loader - the ClassLoader to use to load the bundle
 384     bundle - the resource bundle instance that has been expired in the cache
 385     loadTime - the time when bundle was loaded and put in the cache
 386
 387     Returns: true if the expired bundle needs to be reloaded; false otherwise.
 388
 389 *java.util.ResourceBundle.Control.newBundle(String,Locale,String,ClassLoader,boolean)*
 390
 391 public |java.util.ResourceBundle| newBundle(
 392   java.lang.String baseName,
 393   java.util.Locale locale,
 394   java.lang.String format,
 395   java.lang.ClassLoader loader,
 396   boolean reload)
 397   throws |java.lang.IllegalAccessException|
 398          |java.lang.InstantiationException|
 399          |java.io.IOException|
 400
 401 Instantiates a resource bundle for the given bundle name of the given format
 402 and locale, using the given class loader if necessary. This method returns null
 403 if there is no resource bundle available for the given parameters. If a
 404 resource bundle can't be instantiated due to an unexpected error, the error
 405 must be reported by throwing an Error or Exception rather than simply returning
 406 null.
 407
 408 If the reload flag is true, it indicates that this method is being called
 409 because the previously loaded resource bundle has expired.
 410
 411 The default implementation instantiates a ResourceBundle as follows.
 412
 413
 414
 415 The bundle name is obtained by calling toBundleName(baseName,
 416 locale)(|java.util.ResourceBundle.Control|) .
 417
 418 If format is "java.class", the (|java.lang.Class|) specified by the bundle name
 419 is loaded by calling (|java.lang.ClassLoader|) . Then, a ResourceBundle is
 420 instantiated by calling (|java.lang.Class|) . Note that the reload flag is
 421 ignored for loading class-based resource bundles in this default
 422 implementation.
 423
 424 If format is "java.properties", toResourceName(bundlename,
 425 "properties")(|java.util.ResourceBundle.Control|) is called to get the resource
 426 name. If reload is true, load.getResource(|java.lang.ClassLoader|) is called to
 427 get a (|java.net.URL|) for creating a (|java.net.URLConnection|) . This
 428 URLConnection is used to disable the caches(|java.net.URLConnection|) of the
 429 underlying resource loading layers, and to get an
 430 <code>InputStream</code>(|java.net.URLConnection|) . Otherwise,
 431 loader.getResourceAsStream(|java.lang.ClassLoader|) is called to get an
 432 (|java.io.InputStream|) . Then, a (|java.util.PropertyResourceBundle|) is
 433 constructed with the InputStream.
 434
 435 If format is neither "java.class" nor "java.properties", an
 436 IllegalArgumentException is thrown.
 437
 438
 439
 440
 441     baseName - the base bundle name of the resource bundle, a fully qualified class name
 442     locale - the locale for which the resource bundle should be instantiated
 443     format - the resource bundle format to be loaded
 444     loader - the ClassLoader to use to load the bundle
 445     reload - the flag to indicate bundle reloading; true if reloading an expired resource
 446        bundle, false otherwise
 447
 448     Returns: the resource bundle instance, or null if none could be found.
 449
 450 *java.util.ResourceBundle.Control.toBundleName(String,Locale)*
 451
 452 public |java.lang.String| toBundleName(
 453   java.lang.String baseName,
 454   java.util.Locale locale)
 455
 456 Converts the given baseName and locale to the bundle name. This method is
 457 called from the default implementation of the
 458 newBundle(|java.util.ResourceBundle.Control|) and
 459 needsReload(|java.util.ResourceBundle.Control|) methods.
 460
 461 This implementation returns the following value:
 462
 463 baseName + "_" + language + "_" + country + "_" + variant
 464
 465 where language, country and variant are the language, country and variant
 466 values of locale, respectively. Final component values that are empty Strings
 467 are omitted along with the preceding '_'. If all of the values are empty
 468 strings, then baseName is returned.
 469
 470 For example, if baseName is "baseName" and locale is Locale("ja","","XX"), then
 471 "baseName_ja__XX" is returned. If the given locale is Locale("en"), then
 472 "baseName_en" is returned.
 473
 474 Overriding this method allows applications to use different conventions in the
 475 organization and packaging of localized resources.
 476
 477
 478     baseName - the base name of the resource bundle, a fully qualified class name
 479     locale - the locale for which a resource bundle should be loaded
 480
 481     Returns: the bundle name for the resource bundle
 482
 483 *java.util.ResourceBundle.Control.toResourceName(String,String)*
 484
 485 public final |java.lang.String| toResourceName(
 486   java.lang.String bundleName,
 487   java.lang.String suffix)
 488
 489 Converts the given bundleName to the form required by the
 490 ClassLoader.getResource(|java.lang.ClassLoader|) method by replacing all
 491 occurrences of '.' in bundleName with '/' and appending a '.' and the given
 492 file suffix. For example, if bundleName is "foo.bar.MyResources_ja_JP" and
 493 suffix is "properties", then "foo/bar/MyResources_ja_JP.properties" is
 494 returned.
 495
 496
 497     bundleName - the bundle name
 498     suffix - the file type suffix
 499
 500     Returns: the converted resource name
 501
 502