sample/java.util.ResourceBundle.txt

   1 *java.util.ResourceBundle* *ResourceBundle* Resource bundles contain locale-spec
   2
   3 public abstract class ResourceBundle
   4   extends    |java.lang.Object|
   5
   6 |java.util.ResourceBundle_Description|
   7 |java.util.ResourceBundle_Fields|
   8 |java.util.ResourceBundle_Constructors|
   9 |java.util.ResourceBundle_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.ResourceBundle_Fields*
  14 |java.util.ResourceBundle_java.util.ResourceBundle.parent|
  15
  16 *java.util.ResourceBundle_Constructors*
  17 |java.util.ResourceBundle()|Sole constructor.
  18
  19 *java.util.ResourceBundle_Methods*
  20 |java.util.ResourceBundle.getBundle(String)|Gets a resource bundle using the sp
  21 |java.util.ResourceBundle.getBundle(String,Locale)|Gets a resource bundle using
  22 |java.util.ResourceBundle.getBundle(String,Locale,ClassLoader)|Gets a resource
  23 |java.util.ResourceBundle.getKeys()|Returns an enumeration of the keys.
  24 |java.util.ResourceBundle.getLocale()|Returns the locale of this resource bundl
  25 |java.util.ResourceBundle.getObject(String)|Gets an object for the given key fr
  26 |java.util.ResourceBundle.getString(String)|Gets a string for the given key fro
  27 |java.util.ResourceBundle.getStringArray(String)|Gets a string array for the gi
  28 |java.util.ResourceBundle.handleGetObject(String)|Gets an object for the given
  29 |java.util.ResourceBundle.setParent(ResourceBundle)|Sets the parent bundle of t
  30
  31 *java.util.ResourceBundle_Description*
  32
  33 Resource bundles contain locale-specific objects. When your program needs a
  34 locale-specific resource, a String for example, your program can load it from
  35 the resource bundle that is appropriate for the current user's locale. In this
  36 way, you can write program code that is largely independent of the user's
  37 locale isolating most, if not all, of the locale-specific information in
  38 resource bundles.
  39
  40 This allows you to write programs that can:
  41
  42 be easily localized, or translated, into different languages handle multiple
  43 locales at once be easily modified later to support even more locales
  44
  45 Resource bundles belong to families whose members share a common base name, but
  46 whose names also have additional components that identify their locales. For
  47 example, the base name of a family of resource bundles might be "MyResources".
  48 The family should have a default resource bundle which simply has the same name
  49 as its family - "MyResources" - and will be used as the bundle of last resort
  50 if a specific locale is not supported. The family can then provide as many
  51 locale-specific members as needed, for example a German one named
  52 "MyResources_de".
  53
  54 Each resource bundle in a family contains the same items, but the items have
  55 been translated for the locale represented by that resource bundle. For
  56 example, both "MyResources" and "MyResources_de" may have a String that's used
  57 on a button for canceling operations. In "MyResources" the String may contain
  58 "Cancel" and in "MyResources_de" it may contain "Abbrechen".
  59
  60 If there are different resources for different countries, you can make
  61 specializations: for example, "MyResources_de_CH" contains objects for the
  62 German language (de) in Switzerland (CH). If you want to only modify some of
  63 the resources in the specialization, you can do so.
  64
  65 When your program needs a locale-specific object, it loads the ResourceBundle
  66 class using the getBundle(|java.util.ResourceBundle|) method:
  67
  68
  69
  70 ResourceBundle myResources = ResourceBundle.getBundle("MyResources",
  71 currentLocale);
  72
  73
  74
  75 Resource bundles contain key/value pairs. The keys uniquely identify a
  76 locale-specific object in the bundle. Here's an example of a ListResourceBundle
  77 that contains two key/value pairs:
  78
  79
  80
  81 public class MyResources extends ListResourceBundle { public Object[][]
  82 getContents() { return contents; } static final Object[][] contents = { //
  83 LOCALIZE THIS {"OkKey", "OK"}, {"CancelKey", "Cancel"}, // END OF MATERIAL TO
  84 LOCALIZE }; }
  85
  86 Keys are always Strings. In this example, the keys are "OkKey" and "CancelKey".
  87 In the above example, the values are also Strings--"OK" and "Cancel"--but they
  88 don't have to be. The values can be any type of object.
  89
  90 You retrieve an object from resource bundle using the appropriate getter
  91 method. Because "OkKey" and "CancelKey" are both strings, you would use
  92 getString to retrieve them:
  93
  94
  95
  96 button1 = new Button(myResources.getString("OkKey")); button2 = new
  97 Button(myResources.getString("CancelKey"));
  98
  99 The getter methods all require the key as an argument and return the object if
 100 found. If the object is not found, the getter method throws a
 101 MissingResourceException.
 102
 103 Besides getString, ResourceBundle also provides a method for getting string
 104 arrays, getStringArray, as well as a generic getObject method for any other
 105 type of object. When using getObject, you'll have to cast the result to the
 106 appropriate type. For example:
 107
 108
 109
 110 int[] myIntegers = (int[]) myResources.getObject("intList");
 111
 112
 113
 114 The Java 2 platform provides two subclasses of ResourceBundle,
 115 ListResourceBundle and PropertyResourceBundle, that provide a fairly simple way
 116 to create resources. As you saw briefly in a previous example,
 117 ListResourceBundle manages its resource as a List of key/value pairs.
 118 PropertyResourceBundle uses a properties file to manage its resources.
 119
 120 If ListResourceBundle or PropertyResourceBundle do not suit your needs, you can
 121 write your own ResourceBundle subclass. Your subclasses must override two
 122 methods: handleGetObject and getKeys().
 123
 124 The following is a very simple example of a ResourceBundle subclass,
 125 MyResources, that manages two resources (for a larger number of resources you
 126 would probably use a Hashtable). Notice that you don't need to supply a value
 127 if a "parent-level" ResourceBundle handles the same key with the same value (as
 128 for the okKey below). Example:
 129
 130
 131
 132 // default (English language, United States) public class MyResources extends
 133 ResourceBundle { public Object handleGetObject(String key) { if
 134 (key.equals("okKey")) return "Ok"; if (key.equals("cancelKey")) return
 135 "Cancel"; return null; } }
 136
 137 // German language public class MyResources_de extends MyResources { public
 138 Object handleGetObject(String key) { // don't need okKey, since parent level
 139 handles it. if (key.equals("cancelKey")) return "Abbrechen"; return null; } }
 140
 141 You do not have to restrict yourself to using a single family of
 142 ResourceBundles. For example, you could have a set of bundles for exception
 143 messages, ExceptionResources (ExceptionResources_fr, ExceptionResources_de,
 144 ...), and one for widgets, WidgetResource (WidgetResources_fr,
 145 WidgetResources_de, ...); breaking up the resources however you like.
 146
 147
 148 *java.util.ResourceBundle_java.util.ResourceBundle.parent*
 149
 150 Resource bundles contain locale-specific objects. When your program needs a
 151 locale-specific resource, a String for example, your program can load it from
 152 the resource bundle that is appropriate for the current user's locale. In this
 153 way, you can write program code that is largely independent of the user's
 154 locale isolating most, if not all, of the locale-specific information in
 155 resource bundles.
 156
 157 This allows you to write programs that can:
 158
 159 be easily localized, or translated, into different languages handle multiple
 160 locales at once be easily modified later to support even more locales
 161
 162 Resource bundles belong to families whose members share a common base name, but
 163 whose names also have additional components that identify their locales. For
 164 example, the base name of a family of resource bundles might be "MyResources".
 165 The family should have a default resource bundle which simply has the same name
 166 as its family - "MyResources" - and will be used as the bundle of last resort
 167 if a specific locale is not supported. The family can then provide as many
 168 locale-specific members as needed, for example a German one named
 169 "MyResources_de".
 170
 171 Each resource bundle in a family contains the same items, but the items have
 172 been translated for the locale represented by that resource bundle. For
 173 example, both "MyResources" and "MyResources_de" may have a String that's used
 174 on a button for canceling operations. In "MyResources" the String may contain
 175 "Cancel" and in "MyResources_de" it may contain "Abbrechen".
 176
 177 If there are different resources for different countries, you can make
 178 specializations: for example, "MyResources_de_CH" contains objects for the
 179 German language (de) in Switzerland (CH). If you want to only modify some of
 180 the resources in the specialization, you can do so.
 181
 182 When your program needs a locale-specific object, it loads the ResourceBundle
 183 class using the getBundle(|java.util.ResourceBundle|) method:
 184
 185
 186
 187 ResourceBundle myResources = ResourceBundle.getBundle("MyResources",
 188 currentLocale);
 189
 190
 191
 192 Resource bundles contain key/value pairs. The keys uniquely identify a
 193 locale-specific object in the bundle. Here's an example of a ListResourceBundle
 194 that contains two key/value pairs:
 195
 196
 197
 198 public class MyResources extends ListResourceBundle { public Object[][]
 199 getContents() { return contents; } static final Object[][] contents = { //
 200 LOCALIZE THIS {"OkKey", "OK"}, {"CancelKey", "Cancel"}, // END OF MATERIAL TO
 201 LOCALIZE }; }
 202
 203 Keys are always Strings. In this example, the keys are "OkKey" and "CancelKey".
 204 In the above example, the values are also Strings--"OK" and "Cancel"--but they
 205 don't have to be. The values can be any type of object.
 206
 207 You retrieve an object from resource bundle using the appropriate getter
 208 method. Because "OkKey" and "CancelKey" are both strings, you would use
 209 getString to retrieve them:
 210
 211
 212
 213 button1 = new Button(myResources.getString("OkKey")); button2 = new
 214 Button(myResources.getString("CancelKey"));
 215
 216 The getter methods all require the key as an argument and return the object if
 217 found. If the object is not found, the getter method throws a
 218 MissingResourceException.
 219
 220 Besides getString, ResourceBundle also provides a method for getting string
 221 arrays, getStringArray, as well as a generic getObject method for any other
 222 type of object. When using getObject, you'll have to cast the result to the
 223 appropriate type. For example:
 224
 225
 226
 227 int[] myIntegers = (int[]) myResources.getObject("intList");
 228
 229
 230
 231 The Java 2 platform provides two subclasses of ResourceBundle,
 232 ListResourceBundle and PropertyResourceBundle, that provide a fairly simple way
 233 to create resources. As you saw briefly in a previous example,
 234 ListResourceBundle manages its resource as a List of key/value pairs.
 235 PropertyResourceBundle uses a properties file to manage its resources.
 236
 237 If ListResourceBundle or PropertyResourceBundle do not suit your needs, you can
 238 write your own ResourceBundle subclass. Your subclasses must override two
 239 methods: handleGetObject and getKeys().
 240
 241 The following is a very simple example of a ResourceBundle subclass,
 242 MyResources, that manages two resources (for a larger number of resources you
 243 would probably use a Hashtable). Notice that you don't need to supply a value
 244 if a "parent-level" ResourceBundle handles the same key with the same value (as
 245 for the okKey below). Example:
 246
 247
 248
 249 // default (English language, United States) public class MyResources extends
 250 ResourceBundle { public Object handleGetObject(String key) { if
 251 (key.equals("okKey")) return "Ok"; if (key.equals("cancelKey")) return
 252 "Cancel"; return null; } }
 253
 254 // German language public class MyResources_de extends MyResources { public
 255 Object handleGetObject(String key) { // don't need okKey, since parent level
 256 handles it. if (key.equals("cancelKey")) return "Abbrechen"; return null; } }
 257
 258 You do not have to restrict yourself to using a single family of
 259 ResourceBundles. For example, you could have a set of bundles for exception
 260 messages, ExceptionResources (ExceptionResources_fr, ExceptionResources_de,
 261 ...), and one for widgets, WidgetResource (WidgetResources_fr,
 262 WidgetResources_de, ...); breaking up the resources however you like.
 263
 264
 265
 266 *java.util.ResourceBundle()*
 267
 268 public ResourceBundle()
 269
 270 Sole constructor. (For invocation by subclass constructors, typically
 271 implicit.)
 272
 273
 274 *java.util.ResourceBundle.getBundle(String)*
 275
 276 public static final |java.util.ResourceBundle| getBundle(java.lang.String baseName)
 277
 278 Gets a resource bundle using the specified base name, the default locale, and
 279 the caller's class loader. Calling this method is equivalent to calling
 280
 281 getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader()),
 282
 283 except that getClassLoader() is run with the security privileges of
 284 ResourceBundle. See getBundle(|java.util.ResourceBundle|) for a complete
 285 description of the search and instantiation strategy.
 286
 287     baseName - the base name of the resource bundle, a fully qualified class name
 288
 289     Returns: a resource bundle for the given base name and the default locale
 290 *java.util.ResourceBundle.getBundle(String,Locale)*
 291
 292 public static final |java.util.ResourceBundle| getBundle(
 293   java.lang.String baseName,
 294   java.util.Locale locale)
 295
 296 Gets a resource bundle using the specified base name and locale, and the
 297 caller's class loader. Calling this method is equivalent to calling
 298
 299 getBundle(baseName, locale, this.getClass().getClassLoader()),
 300
 301 except that getClassLoader() is run with the security privileges of
 302 ResourceBundle. See getBundle(|java.util.ResourceBundle|) for a complete
 303 description of the search and instantiation strategy.
 304
 305     baseName - the base name of the resource bundle, a fully qualified class name
 306     locale - the locale for which a resource bundle is desired
 307
 308     Returns: a resource bundle for the given base name and locale
 309 *java.util.ResourceBundle.getBundle(String,Locale,ClassLoader)*
 310
 311 public static |java.util.ResourceBundle| getBundle(
 312   java.lang.String baseName,
 313   java.util.Locale locale,
 314   java.lang.ClassLoader loader)
 315
 316 Gets a resource bundle using the specified base name, locale, and class loader.
 317
 318 Conceptually, getBundle uses the following strategy for locating and
 319 instantiating resource bundles:
 320
 321 getBundle uses the base name, the specified locale, and the default locale
 322 (obtained from Locale.getDefault(|java.util.Locale|) ) to generate a sequence
 323 of candidate bundle names. If the specified locale's language, country, and
 324 variant are all empty strings, then the base name is the only candidate bundle
 325 name. Otherwise, the following sequence is generated from the attribute values
 326 of the specified locale (language1, country1, and variant1) and of the default
 327 locale (language2, country2, and variant2):
 328
 329 baseName + "_" + language1 + "_" + country1 + "_" + variant1 baseName + "_" +
 330 language1 + "_" + country1 baseName + "_" + language1 baseName + "_" +
 331 language2 + "_" + country2 + "_" + variant2 baseName + "_" + language2 + "_" +
 332 country2 baseName + "_" + language2 baseName
 333
 334 Candidate bundle names where the final component is an empty string are
 335 omitted. For example, if country1 is an empty string, the second candidate
 336 bundle name is omitted.
 337
 338 getBundle then iterates over the candidate bundle names to find the first one
 339 for which it can instantiate an actual resource bundle. For each candidate
 340 bundle name, it attempts to create a resource bundle:
 341
 342 First, it attempts to load a class using the candidate bundle name. If such a
 343 class can be found and loaded using the specified class loader, is assignment
 344 compatible with ResourceBundle, is accessible from ResourceBundle, and can be
 345 instantiated, getBundle creates a new instance of this class and uses it as the
 346 result resource bundle.
 347
 348 Otherwise, getBundle attempts to locate a property resource file. It generates
 349 a path name from the candidate bundle name by replacing all "." characters with
 350 "/" and appending the string ".properties". It attempts to find a "resource"
 351 with this name using ClassLoader.getResource(|java.lang.ClassLoader|) . (Note
 352 that a "resource" in the sense of getResource has nothing to do with the
 353 contents of a resource bundle, it is just a container of data, such as a file.)
 354 If it finds a "resource", it attempts to create a new
 355 (|java.util.PropertyResourceBundle|) instance from its contents. If successful,
 356 this instance becomes the result resource bundle.
 357
 358 If no result resource bundle has been found, a MissingResourceException is
 359 thrown.
 360
 361 Once a result resource bundle has been found, its parent chain is instantiated.
 362 getBundle iterates over the candidate bundle names that can be obtained by
 363 successively removing variant, country, and language (each time with the
 364 preceding "_") from the bundle name of the result resource bundle. As above,
 365 candidate bundle names where the final component is an empty string are
 366 omitted. With each of the candidate bundle names it attempts to instantiate a
 367 resource bundle, as described above. Whenever it succeeds, it calls the
 368 previously instantiated resource bundle's setParent(|java.util.ResourceBundle|)
 369 method with the new resource bundle, unless the previously instantiated
 370 resource bundle already has a non-null parent.
 371
 372 Implementations of getBundle may cache instantiated resource bundles and return
 373 the same resource bundle instance multiple times. They may also vary the
 374 sequence in which resource bundles are instantiated as long as the selection of
 375 the result resource bundle and its parent chain are compatible with the
 376 description above.
 377
 378 The baseName argument should be a fully qualified class name. However, for
 379 compatibility with earlier versions, Sun's Java 2 runtime environments do not
 380 verify this, and so it is possible to access PropertyResourceBundles by
 381 specifying a path name (using "/") instead of a fully qualified class name
 382 (using ".").
 383
 384 Example: The following class and property files are provided:
 385 MyResources.class, MyResources_fr_CH.properties, MyResources_fr_CH.class,
 386 MyResources_fr.properties, MyResources_en.properties, MyResources_es_ES.class.
 387 The contents of all files are valid (that is, public non-abstract subclasses of
 388 ResourceBundle for the ".class" files, syntactically correct ".properties"
 389 files). The default locale is Locale("en", "GB").
 390
 391 Calling getBundle with the shown locale argument values instantiates resource
 392 bundles from the following sources:
 393
 394 Locale("fr", "CH"): result MyResources_fr_CH.class, parent
 395 MyResources_fr.properties, parent MyResources.class Locale("fr", "FR"): result
 396 MyResources_fr.properties, parent MyResources.class Locale("de", "DE"): result
 397 MyResources_en.properties, parent MyResources.class Locale("en", "US"): result
 398 MyResources_en.properties, parent MyResources.class Locale("es", "ES"): result
 399 MyResources_es_ES.class, parent MyResources.class
 400
 401 The file MyResources_fr_CH.properties is never used because it is hidden by
 402 MyResources_fr_CH.class.
 403
 404
 405
 406     baseName - the base name of the resource bundle, a fully qualified class name
 407     locale - the locale for which a resource bundle is desired
 408     loader - the class loader from which to load the resource bundle
 409
 410     Returns: a resource bundle for the given base name and locale
 411 *java.util.ResourceBundle.getKeys()*
 412
 413 public abstract |java.util.Enumeration| getKeys()
 414
 415 Returns an enumeration of the keys.
 416
 417
 418 *java.util.ResourceBundle.getLocale()*
 419
 420 public |java.util.Locale| getLocale()
 421
 422 Returns the locale of this resource bundle. This method can be used after a
 423 call to getBundle() to determine whether the resource bundle returned really
 424 corresponds to the requested locale or is a fallback.
 425
 426
 427     Returns: the locale of this resource bundle
 428 *java.util.ResourceBundle.getObject(String)*
 429
 430 public final |java.lang.Object| getObject(java.lang.String key)
 431
 432 Gets an object for the given key from this resource bundle or one of its
 433 parents. This method first tries to obtain the object from this resource bundle
 434 using handleGetObject(|java.util.ResourceBundle|) . If not successful, and the
 435 parent resource bundle is not null, it calls the parent's getObject method. If
 436 still not successful, it throws a MissingResourceException.
 437
 438     key - the key for the desired object
 439
 440     Returns: the object for the given key
 441 *java.util.ResourceBundle.getString(String)*
 442
 443 public final |java.lang.String| getString(java.lang.String key)
 444
 445 Gets a string for the given key from this resource bundle or one of its
 446 parents. Calling this method is equivalent to calling
 447
 448 (String) getObject(|java.util.ResourceBundle|) (key).
 449
 450     key - the key for the desired string
 451
 452     Returns: the string for the given key
 453 *java.util.ResourceBundle.getStringArray(String)*
 454
 455 public final |java.lang.String| getStringArray(java.lang.String key)
 456
 457 Gets a string array for the given key from this resource bundle or one of its
 458 parents. Calling this method is equivalent to calling
 459
 460 (String[]) getObject(|java.util.ResourceBundle|) (key).
 461
 462     key - the key for the desired string array
 463
 464     Returns: the string array for the given key
 465 *java.util.ResourceBundle.handleGetObject(String)*
 466
 467 protected abstract |java.lang.Object| handleGetObject(java.lang.String key)
 468
 469 Gets an object for the given key from this resource bundle. Returns null if
 470 this resource bundle does not contain an object for the given key.
 471
 472     key - the key for the desired object
 473
 474     Returns: the object for the given key, or null
 475 *java.util.ResourceBundle.setParent(ResourceBundle)*
 476
 477 protected void setParent(java.util.ResourceBundle parent)
 478
 479 Sets the parent bundle of this bundle. The parent bundle is searched by
 480 getObject(|java.util.ResourceBundle|) when this bundle does not contain a
 481 particular resource.
 482
 483     parent - this bundle's parent bundle.
 484
 485