com.ibm.icu.util
Class UResourceBundle

java.lang.Object
  extended by java.util.ResourceBundle
      extended by com.ibm.icu.util.UResourceBundle

public abstract class UResourceBundle
extends ResourceBundle

A class representing a collection of resource information pertaining to a given locale. A resource bundle provides a way of accessing locale- specific information in a data file. You create a resource bundle that manages the resources for a given locale and then ask it for individual resources.

In ResourceBundle class, an object is created and the sub items are fetched using getString, getObject methods. In UResourceBundle,each individual element of a resource is a resource by itself.

Resource bundles in ICU are currently defined using text files which conform to the following BNF definition. More on resource bundle concepts and syntax can be found in the Users Guide.

The packaging of ICU *.res files can be of two types ICU4C:

       root.res
         |
      --------
     |        |
   fr.res  en.res
     |
   --------
  |        |
 fr_CA.res fr_FR.res
 
JAVA/JDK:
    LocaleElements.res
         |
      -------------------
     |                   |
 LocaleElements_fr.res  LocaleElements_en.res
     |
   ---------------------------
  |                            |
 LocaleElements_fr_CA.res   LocaleElements_fr_FR.res
 
Depending on the organization of your resources, the syntax to getBundleInstance will change. To open ICU style organization use:
      UResourceBundle bundle = UResourceBundle.getBundleInstance("com/mycompany/resources", "en_US", myClassLoader);
 
To open Java/JDK style organization use:
      UResourceBundle bundle = UResourceBundle.getBundleInstance("com.mycompany.resources.LocaleElements", "en_US", myClassLoader);
 
Please use pass a class loader for loading non-ICU resources. Java security does not allow loading of resources across jar files. You must provide your class loader to load the resources

Author:
ram
Status:
Stable ICU 3.0.

Nested Class Summary
 
Nested classes/interfaces inherited from class java.util.ResourceBundle
ResourceBundle.Control
 
Field Summary
protected static int ALIAS
          Deprecated. This API is ICU internal only.
static int ARRAY
          Resource type constant for arrays of resources.
static int BINARY
          Resource type constant for binary data.
static int INT
          Resource type constant for a single 28-bit integer, interpreted as signed or unsigned by the getInt() function.
static int INT_VECTOR
          Resource type constant for vectors of 32-bit integers.
protected  boolean isTopLevel
          Deprecated. This API is ICU internal only.
protected  String key
          Deprecated. This API is ICU internal only.
static int NONE
          Resource type constant for "no resource".
protected  long resource
          Deprecated. This API is ICU internal only.
protected  int size
          Deprecated. This API is ICU internal only.
static int STRING
          Resource type constant for strings.
static int TABLE
          Resource type constant for tables of key-value pairs.
protected static int TABLE32
          Deprecated. This API is ICU internal only.
 
Fields inherited from class java.util.ResourceBundle
parent
 
Constructor Summary
UResourceBundle()
          Sole constructor.
 
Method Summary
protected static void addToCache(ClassLoader cl, String fullName, ULocale defaultLocale, UResourceBundle b)
          Deprecated. This API is ICU internal only.
 UResourceBundle get(int index)
          Returns the resource in a given resource at the specified index.
 UResourceBundle get(String aKey)
          Returns a resource in a given resource that has a given key.
protected abstract  String getBaseName()
          Gets the base name of the resource bundle
 ByteBuffer getBinary()
          Returns a binary data from a binary resource.
 byte[] getBinary(byte[] ba)
          Returns a binary data from a binary resource.
static UResourceBundle getBundleInstance(String baseName)
          Creates a UResourceBundle for the default locale and specified base name, from which users can extract resources by using their corresponding keys.
static UResourceBundle getBundleInstance(String baseName, Locale locale)
          Creates a UResourceBundle for the specified locale and specified base name, from which users can extract resources by using their corresponding keys.
static UResourceBundle getBundleInstance(String baseName, Locale locale, ClassLoader loader)
          Creates a UResourceBundle for the specified locale and specified base name, from which users can extract resources by using their corresponding keys.
static UResourceBundle getBundleInstance(String baseName, String localeName)
          Creates a resource bundle using the specified base name and locale.
static UResourceBundle getBundleInstance(String baseName, String localeName, ClassLoader root)
          Creates a resource bundle using the specified base name, locale, and class root.
protected static UResourceBundle getBundleInstance(String baseName, String localeName, ClassLoader root, boolean disableFallback)
          Creates a resource bundle using the specified base name, locale, and class root.
static UResourceBundle getBundleInstance(String baseName, ULocale locale)
          Creates a UResourceBundle, from which users can extract resources by using their corresponding keys.
static UResourceBundle getBundleInstance(String baseName, ULocale locale, ClassLoader loader)
          Creates a UResourceBundle, from which users can extract resources by using their corresponding keys.
static UResourceBundle getBundleInstance(ULocale locale)
          Creates a UResourceBundle for the locale specified, from which users can extract resources by using their corresponding keys.
 int getInt()
          Returns a signed integer from a resource.
 int[] getIntVector()
          Returns a 32 bit integer array from a resource.
 UResourceBundleIterator getIterator()
          Returns the iterator which iterates over this resource bundle
 String getKey()
          Returns the key associated with a given resource.
 Enumeration getKeys()
          Returns the keys in this bundle as an enumeration
 Locale getLocale()
          Get the locale of this bundle
protected abstract  String getLocaleID()
          Gets the localeID
protected abstract  UResourceBundle getParent()
          Gets the parent bundle
 int getSize()
          Returns the size of a resource.
 String getString()
          Returns a string from a string resource type
 String getString(int index)
          Returns the string in a given resource at the specified index.
 String[] getStringArray()
          Returns a string array from a array resource type
 int getType()
          Returns the type of a resource.
 int getUInt()
          Returns a unsigned integer from a resource.
abstract  ULocale getULocale()
          Returns the RFC 3066 conformant locale id of this resource bundle.
 VersionInfo getVersion()
          Return the version number associated with this UResourceBundle as an VersionInfo object.
protected  UResourceBundle handleGet(int index, HashMap table, UResourceBundle requested)
          Actual worker method for fetching a resource based on the given index.
protected  UResourceBundle handleGet(String aKey, HashMap table, UResourceBundle requested)
          Actual worker method for fetching a resource based on the given key.
protected  Enumeration handleGetKeys()
          Actual worker method for fetching the keys of resources contained in the resource.
protected  Object handleGetObject(String aKey)
          
protected  String[] handleGetStringArray()
          Actual worker method for fetching the array of strings in a resource.
protected static UResourceBundle instantiateBundle(String baseName, String localeName, ClassLoader root, boolean disableFallback)
          Loads a new resource bundle for the give base name, locale and class loader.
protected static UResourceBundle loadFromCache(ClassLoader cl, String fullName, ULocale defaultLocale)
          Deprecated. This API is ICU internal only.
protected abstract  void setLoadingStatus(int newStatus)
          Deprecated. This API is ICU internal only.
 
Methods inherited from class java.util.ResourceBundle
clearCache, clearCache, containsKey, getBundle, getBundle, getBundle, getBundle, getBundle, getBundle, getObject, getString, getStringArray, handleKeySet, keySet, setParent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NONE

public static final int NONE
Resource type constant for "no resource".

See Also:
Constant Field Values
Status:
Stable ICU 3.8.

STRING

public static final int STRING
Resource type constant for strings.

See Also:
Constant Field Values
Status:
Stable ICU 3.8.

BINARY

public static final int BINARY
Resource type constant for binary data.

See Also:
Constant Field Values
Status:
Stable ICU 3.8.

TABLE

public static final int TABLE
Resource type constant for tables of key-value pairs.

See Also:
Constant Field Values
Status:
Stable ICU 3.8.

ALIAS

protected static final int ALIAS
Deprecated. This API is ICU internal only.
Resource type constant for aliases; internally stores a string which identifies the actual resource storing the data (can be in a different resource bundle). Resolved internally before delivering the actual resource through the API.

See Also:
Constant Field Values
Status:
Internal. This API is ICU internal only.

TABLE32

protected static final int TABLE32
Deprecated. This API is ICU internal only.
Internal use only. Alternative resource type constant for tables of key-value pairs. Never returned by getType().

See Also:
Constant Field Values
Status:
Internal. This API is ICU internal only.

INT

public static final int INT
Resource type constant for a single 28-bit integer, interpreted as signed or unsigned by the getInt() function.

See Also:
getInt(), Constant Field Values
Status:
Stable ICU 3.8.

ARRAY

public static final int ARRAY
Resource type constant for arrays of resources.

See Also:
Constant Field Values
Status:
Stable ICU 3.8.

INT_VECTOR

public static final int INT_VECTOR
Resource type constant for vectors of 32-bit integers.

See Also:
getIntVector(), Constant Field Values
Status:
Stable ICU 3.8.

key

protected String key
Deprecated. This API is ICU internal only.
Data member where the subclasses store the key

Status:
Internal. This API is ICU internal only.

size

protected int size
Deprecated. This API is ICU internal only.
Data member where the subclasses store the size of resources

Status:
Internal. This API is ICU internal only.

resource

protected long resource
Deprecated. This API is ICU internal only.
Data member where the subclasses store the offset within resource data

Status:
Internal. This API is ICU internal only.

isTopLevel

protected boolean isTopLevel
Deprecated. This API is ICU internal only.
Data member where the subclasses store whether the resource is top level

Status:
Internal. This API is ICU internal only.
Constructor Detail

UResourceBundle

public UResourceBundle()
Sole constructor. (For invocation by subclass constructors, typically implicit.) This is public for compatibility with Java, whose compiler will generate public default constructors for an abstract class.

Status:
Stable ICU 3.0.
Method Detail

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                String localeName)
Creates a resource bundle using the specified base name and locale. ICU_DATA_CLASS is used as the default root.

Parameters:
baseName - the base name of the resource bundle, a fully qualified class name
localeName - the locale for which a resource bundle is desired
Returns:
a resource bundle for the given base name and locale
Throws:
MissingResourceException - if no resource bundle for the specified base name can be found
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                String localeName,
                                                ClassLoader root)
Creates a resource bundle using the specified base name, locale, and class root.

Parameters:
baseName - the base name of the resource bundle, a fully qualified class name
localeName - the locale for which a resource bundle is desired
root - the class object from which to load the resource bundle
Returns:
a resource bundle for the given base name and locale
Throws:
MissingResourceException - if no resource bundle for the specified base name can be found
Status:
Stable ICU 3.0.

getBundleInstance

protected static UResourceBundle getBundleInstance(String baseName,
                                                   String localeName,
                                                   ClassLoader root,
                                                   boolean disableFallback)
Creates a resource bundle using the specified base name, locale, and class root.

Parameters:
baseName - the base name of the resource bundle, a fully qualified class name
localeName - the locale for which a resource bundle is desired
root - the class object from which to load the resource bundle
disableFallback - Option to disable locale inheritence. If true the fallback chain will not be built.
Returns:
a resource bundle for the given base name and locale
Throws:
MissingResourceException - if no resource bundle for the specified base name can be found
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(ULocale locale)
Creates a UResourceBundle for the locale specified, from which users can extract resources by using their corresponding keys.

Parameters:
locale - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
Returns:
a resource bundle for the given locale
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName)
Creates a UResourceBundle for the default locale and specified base name, from which users can extract resources by using their corresponding keys.

Parameters:
baseName - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
Returns:
a resource bundle for the given base name and default locale
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                Locale locale)
Creates a UResourceBundle for the specified locale and specified base name, from which users can extract resources by using their corresponding keys.

Parameters:
baseName - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
locale - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
Returns:
a resource bundle for the given base name and locale
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                ULocale locale)
Creates a UResourceBundle, from which users can extract resources by using their corresponding keys.

Parameters:
baseName - string containing the name of the data package. If null the default ICU package name is used.
locale - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
Returns:
a resource bundle for the given base name and locale
Status:
Stable ICU 3.0.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                Locale locale,
                                                ClassLoader loader)
Creates a UResourceBundle for the specified locale and specified base name, from which users can extract resources by using their corresponding keys.

Parameters:
baseName - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
locale - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
loader - the loader to use
Returns:
a resource bundle for the given base name and locale
Status:
Stable ICU 3.8.

getBundleInstance

public static UResourceBundle getBundleInstance(String baseName,
                                                ULocale locale,
                                                ClassLoader loader)
Creates a UResourceBundle, from which users can extract resources by using their corresponding keys.

Note: Please use this API for loading non-ICU resources. Java security does not allow loading of resources across jar files. You must provide your class loader to load the resources

Parameters:
baseName - string containing the name of the data package. If null the default ICU package name is used.
locale - specifies the locale for which we want to open the resource. If null the bundle for default locale is opened.
loader - the loader to use
Returns:
a resource bundle for the given base name and locale
Status:
Stable ICU 3.8.

getULocale

public abstract ULocale getULocale()
Returns the RFC 3066 conformant locale id of this resource bundle. This method can be used after a call to getBundleInstance() to determine whether the resource bundle returned really corresponds to the requested locale or is a fallback.

Returns:
the locale of this resource bundle
Status:
Stable ICU 3.0.

getLocaleID

protected abstract String getLocaleID()
Gets the localeID

Returns:
The string representation of the localeID
Status:
Stable ICU 3.0.

getBaseName

protected abstract String getBaseName()
Gets the base name of the resource bundle

Returns:
The string representation of the base name
Status:
Stable ICU 3.0.

getParent

protected abstract UResourceBundle getParent()
Gets the parent bundle

Returns:
The parent bundle
Status:
Stable ICU 3.0.

getLocale

public Locale getLocale()
Get the locale of this bundle

Overrides:
getLocale in class ResourceBundle
Returns:
the locale of this resource bundle
Status:
Stable ICU 3.0.

addToCache

protected static void addToCache(ClassLoader cl,
                                 String fullName,
                                 ULocale defaultLocale,
                                 UResourceBundle b)
Deprecated. This API is ICU internal only.

Method used by subclasses to add the a particular resource bundle object to the managed cache

Status:
Internal. This API is ICU internal only.

loadFromCache

protected static UResourceBundle loadFromCache(ClassLoader cl,
                                               String fullName,
                                               ULocale defaultLocale)
Deprecated. This API is ICU internal only.

Method used by sub classes to load a resource bundle object from the managed cache

Status:
Internal. This API is ICU internal only.

instantiateBundle

protected static UResourceBundle instantiateBundle(String baseName,
                                                   String localeName,
                                                   ClassLoader root,
                                                   boolean disableFallback)
Loads a new resource bundle for the give base name, locale and class loader. Optionally will disable loading of fallback bundles.

Parameters:
baseName - the base name of the resource bundle, a fully qualified class name
localeName - the locale for which a resource bundle is desired
root - the class object from which to load the resource bundle
disableFallback - disables loading of fallback lookup chain
Returns:
a resource bundle for the given base name and locale
Throws:
MissingResourceException - if no resource bundle for the specified base name can be found
Status:
Stable ICU 3.0.

getBinary

public ByteBuffer getBinary()
Returns a binary data from a binary resource.

Returns:
a pointer to a chuck of unsigned bytes which live in a memory mapped/DLL file.
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getIntVector(), getInt()
Status:
Stable ICU 3.8.

getString

public String getString()
Returns a string from a string resource type

Returns:
a string
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getBinary(), getIntVector(), getInt()
Status:
Stable ICU 3.8.

getStringArray

public String[] getStringArray()
Returns a string array from a array resource type

Returns:
a string
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getString(), getIntVector()
Status:
Stable ICU 3.8.

getBinary

public byte[] getBinary(byte[] ba)
Returns a binary data from a binary resource.

Parameters:
ba - The byte array to write the bytes to. A null variable is OK.
Returns:
an array bytes containing the binary data from the resource.
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getIntVector(), getInt()
Status:
Stable ICU 3.8.

getIntVector

public int[] getIntVector()
Returns a 32 bit integer array from a resource.

Returns:
a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getBinary(), getInt()
Status:
Stable ICU 3.8.

getInt

public int getInt()
Returns a signed integer from a resource.

Returns:
an integer value
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getIntVector(), getBinary()
Status:
Stable ICU 3.8.

getUInt

public int getUInt()
Returns a unsigned integer from a resource. This integer is originally 28 bit and the sign gets propagated.

Returns:
an integer value
Throws:
MissingResourceException
UResourceTypeMismatchException
See Also:
getIntVector(), getBinary()
Status:
Stable ICU 3.8.

get

public UResourceBundle get(String aKey)
Returns a resource in a given resource that has a given key.

Parameters:
aKey - a key associated with the wanted resource
Returns:
a resource bundle object representing the resource
Throws:
MissingResourceException
Status:
Stable ICU 3.8.

getString

public String getString(int index)
Returns the string in a given resource at the specified index.

Parameters:
index - an index to the wanted string.
Returns:
a string which lives in the resource.
Throws:
IndexOutOfBoundsException
UResourceTypeMismatchException
Status:
Stable ICU 3.8.

get

public UResourceBundle get(int index)
Returns the resource in a given resource at the specified index.

Parameters:
index - an index to the wanted resource.
Returns:
the sub resource UResourceBundle object
Throws:
IndexOutOfBoundsException
MissingResourceException
Status:
Stable ICU 3.8.

getKeys

public Enumeration getKeys()
Returns the keys in this bundle as an enumeration

Specified by:
getKeys in class ResourceBundle
Returns:
an enumeration containing key strings
Status:
Stable ICU 3.8.

getSize

public int getSize()
Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is the number of child resources.
Warning: Integer array is treated as a scalar type. There are no APIs to access individual members of an integer array. It is always returned as a whole.

Returns:
number of resources in a given resource.
Status:
Stable ICU 3.8.

getType

public int getType()
Returns the type of a resource. Available types are INT, ARRAY, BINARY, INT_VECTOR, STRING, TABLE.

Returns:
type of the given resource.
Status:
Stable ICU 3.8.

getVersion

public VersionInfo getVersion()
Return the version number associated with this UResourceBundle as an VersionInfo object.

Returns:
VersionInfo object containing the version of the bundle
Status:
Stable ICU 3.8.

getIterator

public UResourceBundleIterator getIterator()
Returns the iterator which iterates over this resource bundle

Returns:
UResourceBundleIterator that iterates over the resources in the bundle
Status:
Stable ICU 3.8.

getKey

public String getKey()
Returns the key associated with a given resource. Not all the resources have a key - only those that are members of a table.

Returns:
a key associated to this resource, or null if it doesn't have a key
Status:
Stable ICU 3.8.

handleGet

protected UResourceBundle handleGet(String aKey,
                                    HashMap table,
                                    UResourceBundle requested)
Actual worker method for fetching a resource based on the given key. Sub classes must override this method if they support resources with keys.

Parameters:
aKey - the key string of the resource to be fetched
table - hashtable object to hold references of resources already seen
requested - the original resource bundle object on which the get method was invoked. The requested bundle and the bundle on which this method is invoked are the same, except in the cases where aliases are involved.
Returns:
UResourceBundle a resource associated with the key
Status:
Stable ICU 3.8.

handleGet

protected UResourceBundle handleGet(int index,
                                    HashMap table,
                                    UResourceBundle requested)
Actual worker method for fetching a resource based on the given index. Sub classes must override this method if they support arrays of resources.

Parameters:
index - the index of the resource to be fetched
table - hashtable object to hold references of resources already seen
requested - the original resource bundle object on which the get method was invoked. The requested bundle and the bundle on which this method is invoked are the same, except in the cases where aliases are involved.
Returns:
UResourceBundle a resource associated with the index
Status:
Stable ICU 3.8.

handleGetStringArray

protected String[] handleGetStringArray()
Actual worker method for fetching the array of strings in a resource. Sub classes must override this method if they support arrays of strings.

Returns:
String[] An array of strings containing strings
Status:
Stable ICU 3.8.

handleGetKeys

protected Enumeration handleGetKeys()
Actual worker method for fetching the keys of resources contained in the resource. Sub classes must override this method if they support keys and associated resources.

Returns:
Enumeration An enumeration of all the keys in this resource.
Status:
Stable ICU 3.8.

handleGetObject

protected Object handleGetObject(String aKey)

Specified by:
handleGetObject in class ResourceBundle
Status:
Stable ICU 3.8.

setLoadingStatus

protected abstract void setLoadingStatus(int newStatus)
Deprecated. This API is ICU internal only.

This method is for setting the loading status of the resource. The status is analogous to the warning status in ICU4C.

Status:
Internal. This API is ICU internal only.


Copyright (c) 2009 IBM Corporation and others.