ResourceBundle Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Resource bundles contain locale-specific objects.
[Android.Runtime.Register("java/util/ResourceBundle", DoNotGenerateAcw=true)]
public abstract class ResourceBundle : Java.Lang.Object[<Android.Runtime.Register("java/util/ResourceBundle", DoNotGenerateAcw=true)>]
type ResourceBundle = class
inherit Object- Inheritance
- Derived
- Attributes
Remarks
Resource bundles contain locale-specific objects. When your program needs a locale-specific resource, a String for example, your program can load it from the resource bundle that is appropriate for the current user's locale. In this way, you can write program code that is largely independent of the user's locale isolating most, if not all, of the locale-specific information in resource bundles.
This allows you to write programs that can: <UL> <LI> be easily localized, or translated, into different languages <LI> handle multiple locales at once <LI> be easily modified later to support even more locales </UL>
Resource bundles belong to families whose members share a common base name, but whose names also have additional components that identify their locales. For example, the base name of a family of resource bundles might be "MyResources". The family should have a default resource bundle which simply has the same name as its family - "MyResources" - and will be used as the bundle of last resort if a specific locale is not supported. The family can then provide as many locale-specific members as needed, for example a German one named "MyResources_de".
Each resource bundle in a family contains the same items, but the items have been translated for the locale represented by that resource bundle. For example, both "MyResources" and "MyResources_de" may have a String that's used on a button for canceling operations. In "MyResources" the String may contain "Cancel" and in "MyResources_de" it may contain "Abbrechen".
If there are different resources for different countries, you can make specializations: for example, "MyResources_de_CH" contains objects for the German language (de) in Switzerland (CH). If you want to only modify some of the resources in the specialization, you can do so.
When your program needs a locale-specific object, it loads the ResourceBundle class using the #getBundle(java.lang.String, java.util.Locale) getBundle method: <blockquote>
ResourceBundle myResources =
ResourceBundle.getBundle("MyResources", currentLocale);
</blockquote>
Resource bundles contain key/value pairs. The keys uniquely identify a locale-specific object in the bundle. Here's an example of a ListResourceBundle that contains two key/value pairs: <blockquote>
public class MyResources extends ListResourceBundle {
protected Object[][] getContents() {
return new Object[][] {
// LOCALIZE THE SECOND STRING OF EACH ARRAY (e.g., "OK")
{"OkKey", "OK"},
{"CancelKey", "Cancel"},
// END OF MATERIAL TO LOCALIZE
};
}
}
</blockquote> Keys are always Strings. In this example, the keys are "OkKey" and "CancelKey". In the above example, the values are also Strings--"OK" and "Cancel"--but they don't have to be. The values can be any type of object.
You retrieve an object from resource bundle using the appropriate getter method. Because "OkKey" and "CancelKey" are both strings, you would use getString to retrieve them: <blockquote>
button1 = new Button(myResources.getString("OkKey"));
button2 = new Button(myResources.getString("CancelKey"));
</blockquote> The getter methods all require the key as an argument and return the object if found. If the object is not found, the getter method throws a MissingResourceException.
Besides getString, ResourceBundle also provides a method for getting string arrays, getStringArray, as well as a generic getObject method for any other type of object. When using getObject, you'll have to cast the result to the appropriate type. For example: <blockquote>
int[] myIntegers = (int[]) myResources.getObject("intList");
</blockquote>
The Java Platform provides two subclasses of ResourceBundle, ListResourceBundle and PropertyResourceBundle, that provide a fairly simple way to create resources. As you saw briefly in a previous example, ListResourceBundle manages its resource as a list of key/value pairs. PropertyResourceBundle uses a properties file to manage its resources.
If ListResourceBundle or PropertyResourceBundle do not suit your needs, you can write your own ResourceBundle subclass. Your subclasses must override two methods: handleGetObject and getKeys().
The implementation of a ResourceBundle subclass must be thread-safe if it's simultaneously used by multiple threads. The default implementations of the non-abstract methods in this class, and the methods in the direct known concrete subclasses ListResourceBundle and PropertyResourceBundle are thread-safe.
<h3>ResourceBundle.Control</h3>
The ResourceBundle.Control class provides information necessary to perform the bundle loading process by the getBundle factory methods that take a ResourceBundle.Control instance. You can implement your own subclass in order to enable non-standard resource bundle formats, change the search strategy, or define caching parameters. Refer to the descriptions of the class and the #getBundle(String, Locale, ClassLoader, Control) getBundle factory method for details.
<h3>Cache Management</h3>
Resource bundle instances created by the getBundle factory methods are cached by default, and the factory methods return the same resource bundle instance multiple times if it has been cached. getBundle clients may clear the cache, manage the lifetime of cached resource bundle instances using time-to-live values, or specify not to cache resource bundle instances. Refer to the descriptions of the #getBundle(String, Locale, ClassLoader, Control) <code>getBundle</code> factory method, #clearCache(ClassLoader) clearCache, Control#getTimeToLive(String, Locale) ResourceBundle.Control.getTimeToLive, and Control#needsReload(String, Locale, String, ClassLoader, ResourceBundle, long) ResourceBundle.Control.needsReload for details.
<h3>Example</h3>
The following is a very simple example of a ResourceBundle subclass, MyResources, that manages two resources (for a larger number of resources you would probably use a Map). Notice that you don't need to supply a value if a "parent-level" ResourceBundle handles the same key with the same value (as for the okKey below). <blockquote>
// default (English language, United States)
public class MyResources extends ResourceBundle {
public Object handleGetObject(String key) {
if (key.equals("okKey")) return "Ok";
if (key.equals("cancelKey")) return "Cancel";
return null;
}
public Enumeration<String> getKeys() {
return Collections.enumeration(keySet());
}
// Overrides handleKeySet() so that the getKeys() implementation
// can rely on the keySet() value.
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("okKey", "cancelKey"));
}
}
// German language
public class MyResources_de extends MyResources {
public Object handleGetObject(String key) {
// don't need okKey, since parent level handles it.
if (key.equals("cancelKey")) return "Abbrechen";
return null;
}
protected Set<String> handleKeySet() {
return new HashSet<String>(Arrays.asList("cancelKey"));
}
}
</blockquote> You do not have to restrict yourself to using a single family of ResourceBundles. For example, you could have a set of bundles for exception messages, ExceptionResources (ExceptionResources_fr, ExceptionResources_de, ...), and one for widgets, WidgetResource (WidgetResources_fr, WidgetResources_de, ...); breaking up the resources however you like.
Added in 1.1.
Java documentation for java.util.ResourceBundle.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Constructors
| ResourceBundle() |
Sole constructor. |
| ResourceBundle(IntPtr, JniHandleOwnership) |
A constructor used when creating managed representations of JNI objects; called by the runtime. |
Properties
| BaseBundleName |
Returns the base name of this bundle, if known, or |
| Class |
Returns the runtime class of this |
| Handle |
The handle to the underlying Android instance. (Inherited from Object) |
| JniIdentityHashCode | (Inherited from Object) |
| JniPeerMembers | |
| Keys |
Returns the names of the resources contained in this |
| Locale |
Returns the locale of this resource bundle. |
| Parent |
The parent bundle of this bundle. |
| PeerReference | (Inherited from Object) |
| ThresholdClass |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
| ThresholdType |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
Methods
| ClearCache() |
Removes all resource bundles from the cache that have been loaded using the caller's class loader. |
| ClearCache(ClassLoader) |
Removes all resource bundles from the cache that have been loaded by the given class loader. |
| Clone() |
Creates and returns a copy of this object. (Inherited from Object) |
| ContainsKey(String) |
Determines whether the given |
| Dispose() | (Inherited from Object) |
| Dispose(Boolean) | (Inherited from Object) |
| Equals(Object) |
Indicates whether some other object is "equal to" this one. (Inherited from Object) |
| GetBundle(String, Locale, ClassLoader, ResourceBundle+Control) |
Gets a resource bundle using the specified base name, the default locale, and the caller's class loader. |
| GetBundle(String, Locale, ClassLoader) |
Gets a resource bundle using the specified base name, locale, and class loader. |
| GetBundle(String, Locale, ResourceBundle+Control) |
Gets a resource bundle using the specified base name, the default locale, and the caller's class loader. |
| GetBundle(String, Locale) |
Gets a resource bundle using the specified base name and locale, and the caller's class loader. |
| GetBundle(String, ResourceBundle+Control) |
Gets a resource bundle using the specified base name, the default locale, and the caller's class loader. |
| GetBundle(String) |
Gets a resource bundle using the specified base name, the default locale, and the caller's class loader. |
| GetHashCode() |
Returns a hash code value for the object. (Inherited from Object) |
| GetObject(String) |
Gets an object for the given key from this resource bundle or one of its parents. |
| GetString(String) |
Gets a string for the given key from this resource bundle or one of its parents. |
| GetStringArray(String) |
Gets a string array for the given key from this resource bundle or one of its parents. |
| HandleGetObject(String) |
Gets an object for the given key from this resource bundle. |
| HandleKeySet() |
Returns a |
| JavaFinalize() |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object) |
| KeySet() |
Returns a |
| Notify() |
Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object) |
| NotifyAll() |
Wakes up all threads that are waiting on this object's monitor. (Inherited from Object) |
| SetHandle(IntPtr, JniHandleOwnership) |
Sets the Handle property. (Inherited from Object) |
| SetParent(ResourceBundle) |
Sets the parent bundle of this bundle. |
| ToArray<T>() | (Inherited from Object) |
| ToString() |
Returns a string representation of the object. (Inherited from Object) |
| UnregisterFromRuntime() | (Inherited from Object) |
| Wait() |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object) |
| Wait(Int64, Int32) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wait(Int64) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
Explicit Interface Implementations
| IJavaPeerable.Disposed() | (Inherited from Object) |
| IJavaPeerable.DisposeUnlessReferenced() | (Inherited from Object) |
| IJavaPeerable.Finalized() | (Inherited from Object) |
| IJavaPeerable.JniManagedPeerState | (Inherited from Object) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) | (Inherited from Object) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from Object) |
| IJavaPeerable.SetPeerReference(JniObjectReference) | (Inherited from Object) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |