javax.microedition.global
Class ResourceManager

java.lang.Object
  javax.microedition.global.ResourceManager

public class ResourceManager

extends java.lang.Object

Resource manager for applications. Provides an interface to the resources for a specified base name and the specified locale. The locale is typically the system default locale, but another locale can be specified. This specification does not mandate any partitioning of the base names and applications, so each application can use as many base names as necessary.

Resource managers are constructed using some variant of the static factory method getManager. One resource manager MUST dispense either application resources or device resources, but not both. If the base name is "DEVICE" (defined as the empty string), the manager MUST only retrieve device resources. Non-empty base names MUST be used for application resources.

Resource types and IDs

Application resources and device resources are retrieved using the same method, getResource. Resources retrieved by the getResource(int id) method MUST be returned as Java objects.

The resource IDs used by the manager MUST be integers in the range 0...0x7FFFFFFF. The application resource IDs MUST be unique to each base name, but there can be several resources with the same ID in the system, as long as they are associated with different base names. Device resource IDs MUST be unique across resource managers, i.e. each manager MUST return the same device resource for the same ID.

Application resources are specific to a base name, whereas each manager returns device resources from a common pool. For application resources, the application programmer keeps track of the actual type of each resource. For device resources, the device manufacturer MUST publish this information along with the valid resource IDs. Since most of the retrieved resources are strings, the getString(int id) method MUST return the string resource associated with the ID, to avoid typecasting in the application.

For a discussion of the resource file format refer to the "Resource files" section in the specification overview.

Resource inheritance

To save storage, resources that are exactly the same for two or more locales can be stored in a common locale. For example, the strings "OK" and "Cancel" would typically be used in both U.S. English and British English (locale identifiers "en-US" and "en-GB", respectively). Instead of duplicating these strings in both locales, they can be stored in the "en" locale. It can be said that the "en-US" and "en-GB" locales "inherit" the strings from the "en" locale.

The resource retrieval mechanism MUST support resource inheritance by implementing hierarchical matching as described in the Resource matching section.

Resource matching and lookup

A resource manager is always constructed using a base name. The supported locales of a resource manager are those for which resources exist for the manager's base name. This is reflected by the static getSupportedLocales method.

The type of construction of the resource manager determines the matching rules used for resource lookup. The simplest form specifies only the base name and uses the system's default locale. A resource manager can also be constructed for a specific locale by passing a locale identifier. If resources for the system default locale or the passed locale are not found, hierachical matching is performed.

Hierarchical matching successively tries more generic locales derived from the specified one by removing first the variant, then the country, and finally the language component from the locale. If no resources are found even in the common locale, a ResourceException MUST be thrown.

If an array of locale identifiers is passed, all the locales in the array MUST be tried successively until there is a match, or the array is exhausted.

Valid locale identifiers

Valid locale identifiers consist of all valid MIDP 2.0 locale identifiers and the empty string. The empty string MUST be used as a shortcut for resources with the same base name that are common to all locales.

The locale resolved by matching can end up different than the one specified. The base name of the resource manager and the actual resolved locale can be retrieved using the getBaseName and getLocale methods, respectively.

Resource caching

To avoid repeated reading of resources from possibly slow media, a resource manager SHOULD support the caching of resources in memory. If caching is supported, then when a resource is read for the first time, it SHOULD be stored in memory and retrieved from there. The isCaching method MUST return the caching status. The actual caching algorithm is implementation specific.

Error conditions

The following conditions MUST cause a ResourceException to be thrown with the appropriate error code and detail message:

• If the resource file does not adhere to the specified resource file format.
• If there are no resources for the specified base name in any specified locale(s).
• If the specified resource ID is invalid or non-existent.
• If no locale is specified in the construction, but the system's default locale is null.
• The type of the retrieved resource does not fit the method (i.e. a string resource retrieved with getData).

See Also:

ResourceException

Field Summary

static java.lang.String

DEVICE Constant to indicate device resources.

Method Summary

java.lang.String	getBaseName() Gets the base name of this resource manager.
byte[]	getData(int id) Gets a resource with the specified resource ID as a byte array containing arbitrary binary data.
java.lang.String	getLocale() Gets the locale of this resource manager.
static ResourceManager	getManager(java.lang.String baseName) Gets a resource manager for the specified base name and the system's default locale.
static ResourceManager	getManager(java.lang.String baseName, java.lang.String locale) Gets a resource manager for the specified base name and locale.
static ResourceManager	getManager(java.lang.String baseName, java.lang.String[] locales) Gets a resource manager for the specified base name and the first matching locale in the supplied array.
java.lang.Object	getResource(int id) Gets a resource with the specified ID.
java.lang.String	getString(int id) Gets a string with the specified resource ID.
static java.lang.String[]	getSupportedLocales(java.lang.String baseName) Gets the locales supported by this resource manager for the given base name.
boolean	isCaching() Returns the caching status of this resource manager.
boolean	isValidResourceID(int id) Determines if the given resource ID is valid in this implementation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEVICE

public static final java.lang.String DEVICE

Constant to indicate device resources.

See Also:

Constant Field Values

Method Detail

getBaseName

public java.lang.String getBaseName()

Gets the base name of this resource manager.

Returns:

the base name (DEVICE if this resource manager is retrieving device-specific resources)

getData

public byte[] getData(int id)
               throws ResourceException

Gets a resource with the specified resource ID as a byte array containing arbitrary binary data. If the resource with the specified ID is not binary data, or the resource does not exist, a ResourceException is thrown with the appropriate error code.

This method performs a hierarchical lookup of the resource.

Parameters:

id - the resource ID

Returns:

byte array containing the data

Throws:

ResourceException - if the resource does not exist, or if the resource is not the correct type

java.lang.IllegalArgumentException - if the resource ID is invalid

getLocale

public java.lang.String getLocale()

Gets the locale of this resource manager.

Returns:

the locale identifier

getManager

public static final ResourceManager getManager(java.lang.String baseName)
                                        throws ResourceException,
                                               UnsupportedLocaleException

Gets a resource manager for the specified base name and the system's default locale.

If the base name is DEVICE, the resource manager can only retrieve device-specific resources. Other base names retrieve application-specific resources. The base name must not be null.

If the system's default locale is null, a ResourceException is thrown. If it is non-null but no resources are found, this method performs the hierarchical matching of locales.

If no resources are found for the combination of base name and locale, a ResourceException is thrown with the appropriate error code and detail message.

Parameters:

baseName - the base name, DEVICE to retrieve device-specific resources

Returns:

the manager instance for the specified base name

Throws:

java.lang.NullPointerException - if the base name is null

ResourceException - if the system default locale is null, or the resource file is invalid

UnsupportedLocaleException - if the system's default locale (when non-null) is not listed in the meta-information file of this base name (for application resources only), or when device resources are not supported for the system's default locale

See Also:

getManager(String, String), DEVICE

getManager

public static final ResourceManager getManager(java.lang.String baseName,
                                               java.lang.String locale)
                                        throws ResourceException,
                                               UnsupportedLocaleException

Gets a resource manager for the specified base name and locale.

If the base name is DEVICE (the empty string), the resource manager can only retrieve device resources. Other base names retrieve application resources. The base name must not be null.

If resources for the specified locale are not found, this method attempts to find resources by hierarchical matching. The matching proceeds from language-country-variant to language-country, then on to language, and finally to the empty string. An empty string can also be used as the locale. It is a shortcut to using common resources without going through the matching process.

If resources for the combination of the base name and the matching locale are found, this method returns a manager for those resources. If no resources are found for the combination, a ResourceException is thrown.

Parameters:

baseName - the base name, non-empty for application resources, DEVICE (the empty string) for device resources

locale - the locale to use either as is or as a starting point for hierarchical matching

Returns:

the manager instance for the base name and the specified or matched locale

Throws:

java.lang.NullPointerException - if the base name is null or if the locale is null

java.lang.IllegalArgumentException - if the locale identifier is not valid according to the MIDP 2.0 specification

ResourceException - if no resources for the combination of base name and locale are found, or the resource file is invalid

UnsupportedLocaleException - if locale is not listed in the meta-information file of this base name (application resources only)

See Also:

DEVICE

getManager

public static final ResourceManager getManager(java.lang.String baseName,
                                               java.lang.String[] locales)
                                        throws ResourceException,
                                               UnsupportedLocaleException

Gets a resource manager for the specified base name and the first matching locale in the supplied array.

If the base name is "DEVICE" (the empty string), the resource manager can only retrieve device resources. Other base names retrieve application resources. The base name MUST NOT be null.

This method attempts to get a resource manager for a combination of the base name and one of the locales in the array. The locales are tried successively, stopping at the first match. This method MUST NOT perform hierarchical matching. If none of the locales in the array result in a match, a ResourceException MUST be thrown with the appropriate error code.

For example, if the array of locales contains { "de-DE", "fr", "en" }, and resources are not found for "de-DE" or "fr", but are found for "en", then this method gets a manager for "en". However, if resources are not found for "de-DE", but are found for "fr", then this method gets a manager for "fr" and disregards the "en" locale. In this case if resources are not found for "de-DE", the locale "de" MUST NOT be tried; instead the matching proceeds to the next locale in the array.

The locales array MUST NOT be null or empty. Each of the locale identifiers in the array MUST be a valid locale identifier, otherwise an IllegalArgumentException is thrown. As an extension, the empty string can be used to use resources common to all locales.

Parameters:

baseName - the base name, non-empty for application resources, or DEVICE (the empty string) for device resources

locales - the array of locale identifiers to try

Returns:

the manager instance for the base name and the matched locale

Throws:

java.lang.NullPointerException - if the locales array is null, or if any of the locales in the array is null, or the base name is null

java.lang.IllegalArgumentException - if any of the locale identifiers in the array is invalid according to the MIDP 2.0 specification, or if the array is empty

ResourceException - if no resources for the base name and any of the locales in the array are found

UnsupportedLocaleException - if none of the locales in the array are listed in the meta-information file of this base name (for application resources), or when device resources are not supported for any of the locales

See Also:

DEVICE

getResource

public java.lang.Object getResource(int id)
                             throws ResourceException

Gets a resource with the specified ID. The resource is either an application-specific resource or a device resource, depending on the base name of the resource manager.

This method performs a hierarchical lookup of the resource.

Parameters:

id - the resource ID

Returns:

the resource object

Throws:

ResourceException - if the resource is not found, or if an application resource has an unknown type

java.lang.IllegalArgumentException - if the resource ID is invalid

See Also:

getString(int), getData(int)

getString

public java.lang.String getString(int id)
                           throws ResourceException

Gets a string with the specified resource ID. This is a convenience method to avoid typecasting in applications. If the resource with the specified ID is not a string, or the resource does not exist, a ResourceException is thrown with the appropriate error code.

This method performs a hierarchical lookup of the resource.

Parameters:

id - the resource ID

Returns:

the string

Throws:

ResourceException - if the resource does not exist, or if the resource is not the correct type

java.lang.IllegalArgumentException - if the resource ID is invalid

getSupportedLocales

public static java.lang.String[] getSupportedLocales(java.lang.String baseName)

Gets the locales supported by this resource manager for the given base name. Returns an array of valid microedition.locale values. If there are no supported locales, returns an empty array (not null).

The base name is used to distinguish between application and device resources. If the base name is non-empty, this method returns the list of locales for which application-specific resources are defined. If the base name is "DEVICE" (the empty string), the set of supported device locales is returned instead.

The returned array MAY be empty if no locales are supported for the specified base name. It MUST NOT be null.

Values in the array MUST be unique. The value null MUST NOT appear in the returned array. However, if there are resources for this base name which are common to all locales, the array MUST contain the empty string. It SHOULD be first element in the array.

The supported locales for an application resource manager require a base name specific meta-information file described in the "Enumerating supported locales" section of the specification overview. If the meta-information file is not found, this method MUST throw a ResourceException with the error code METAFILE_NOT_FOUND.

If the content of the meta-information file is not syntactically valid, this method MUST throw a ResourceException with the error code DATA_ERROR.

The list of locales supported by a resource manager for a base name MAY be different than in a formatter, i.e. the implementation MAY support formatting rules for a certain set of locales, but an application can supply resources for an entirely different (or overlapping) set of locales.

Parameters:

baseName - the base name, non-empty for application resources, DEVICE (the empty string) for device resources

Returns:

the list of supported locales for the specified base name, possibly empty

Throws:

java.lang.NullPointerException - if the base name is null

ResourceException - if the meta-information file is not found or it is not of the specified format

See Also:

Formatter.getSupportedLocales(), StringComparator.getSupportedLocales(), ResourceException

isCaching

public boolean isCaching()

Returns the caching status of this resource manager.

Returns:

true if caching, false if not

isValidResourceID

public boolean isValidResourceID(int id)

Determines if the given resource ID is valid in this implementation. In this context "valid" means that a resource exists with the given resource ID, and calling getResource with that ID returns a non-null object instance.

The method does not discriminate between application and device resources, since one resource manager can only handle one type of resource.

Parameters:

id - the resource ID

Returns:

true if the resource ID is valid, false if not

Throws:

java.lang.IllegalArgumentException - if the resource ID is not in the defined range

See Also:

getResource(int), getString(int), getData(int)