|
BenQ Mobile |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.microedition.global.ResourceManager
Resource manager for MIDlet suites. Can read individual resources of a particular MIDlet for the specified locale (possibly the default one). Each MIDlet in a suite can have has its own resource manager, identified by a base name . You can also use an arbitrary base name for resources that are common to two or more MIDlets in a suite.
There can be only one resource manager per base name. If the base name is
null
, the manager can only retrieve device-specific
resources. The base name must not be empty.
There are two kinds of resources: application resources and device resources.
These are retrieved using the same method, getResource
.
Application resources are specific to a base name, whereas each manager
returns device resources from a common pool.
The resource IDs used by the manager are integers instead of strings.
Different types of resources must be assigned non-overlapping, consecutive,
non-negative integer IDs. Application resource IDs must be in the range
0x00000000
to 0x0FFFFFFF
, while device
resource IDs must be in the range 0x10000000
to
0x7FFFFFFF
. Each resource manager maintains its own set of
application resource IDs, so there can be several resources with the same ID,
as long as they are associated with different base names. Device resource IDs
are unique across managers, i.e. each manager returns the same device
resource for the same ID, irrespective of the base name.
Resources retrieved by the getResource(int id)
method are
returned as Java objects. 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 retrieved resources are strings, the
getString(int)
method returns the string resource, to avoid
typecasting in the application. For convenience, there is also a
getImage(int)
for retrieving images usable in the MIDP 2.0
LCDUI.
A resource manager is always constructed using a base name. The supported
locales are those for which resources exist for the manager's base name. This
is reflected by the 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, using the system's default locale. A resource manager can also be constructed for a specific locale, and hierachical matching is used to try more generic locales derived from the specified one if the exact specified locale is not supported. If an array of locales is passed, all the locales in the array are tried successively.
The base name and the actual locale can be retrieved using the
getBaseName
and getLocale
methods.
To avoid repeated reading of resources from possibly slow media, a resource
manager should support the caching of resources in memory. When a
resource is first read, it should be stored in memory and retrieved from
there. The isCaching
method returns the caching status. The
actual caching algorithm is implementation specific.
ResourceException
is thrown with an appropriate error code
and detail message.
Copyright: Copyright (c) Siemens AG 2004 * ALL RIGHTS RESERVED
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 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 manager. |
boolean |
isValidResourceID(int id)
Determines if the given resource ID is valid in this implementation. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final java.lang.String DEVICE
Method Detail |
public static final ResourceManager getManager(java.lang.String baseName) throws ResourceException, UnsupportedLocaleException
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.
baseName
- the base name, DEVICE to retrieve
device-specific resources
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 localepublic static final ResourceManager getManager(java.lang.String baseName, java.lang.String locale) throws ResourceException, UnsupportedLocaleException
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.
baseName
- - the base name, non-empty for
application resources, DEVICE (the empty string) for device resourceslocale
- - the locale to use either as is or as a starting point
for hierarchical matching
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)public static final ResourceManager getManager(java.lang.String baseName, java.lang.String[] locales) throws ResourceException, UnsupportedLocaleException
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.
baseName
- - the base name, non-empty for application resources,
or DEVICE (the empty string) for device resourceslocales
- - the array of locale identifiers to try
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 localespublic java.lang.String getBaseName()
public byte[] getData(int id) throws ResourceException, java.lang.IllegalArgumentException
id
- - the resource ID
ResourceException
- - if the resource does not exist,
or if the resource is not the correct type
java.lang.IllegalArgumentException
- -
if the resource ID is invalidpublic java.lang.String getLocale()
public java.lang.Object getResource(int id) throws ResourceException, java.lang.IllegalArgumentException
id
- - the resource ID
ResourceException
- - if the resource is not found,
or if an application resource has an unknown type
java.lang.IllegalArgumentException
- -
if the resource ID is invalidpublic java.lang.String getString(int id) throws ResourceException, java.lang.IllegalArgumentException
id
- - the resource ID
ResourceException
- - if the resource does not exist,
or if the resource is not the correct type
java.lang.IllegalArgumentException
- -
if the resource ID is invalidpublic boolean isValidResourceID(int id) throws java.lang.IllegalArgumentException
id
- the resource ID
true
if the resource ID is valid,
false
if not
java.lang.IllegalArgumentException
getResource(int)
,
getString(int)
public static java.lang.String[] getSupportedLocales(java.lang.String baseName) throws ResourceException, java.lang.NullPointerException
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.
baseName
- - the base name, non-empty for application resources,
DEVICE (the empty string) for device resources
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 formatpublic boolean isCaching()
|
BenQ Mobile |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2006 BenQ Mobile GmbH & Co. OHG or respective copyright owner. All Rights Reserved. BenQ Corp. is a trademark licensee of Siemens AG. |
For further information about Mobility Toolkit (MTK) visit our Developer Portal. |