org.apache.commons.resources
Interface Resources

All Superinterfaces:

Serializable

All Known Implementing Classes:

ResourcesBase

public interface Resources

extends Serializable

An abstract representation of a set of internationalized resources, which are arbitrary objects identified by a unique String key. Localized versions of the resources (based on Locale and optional TimeZone parameters) can be retrieved in a variety of formats.

When presented with an invalid key value, resource getter methods will behave differently based on the current value of the returnNull property for this Resources instance. If the property value is true, the getter method will return null (which may be ambiguous if null is a valid resource value). If the property value is false, a ResourcesKeyException will be thrown instead.

Different implementations of the Resources interface support a variety of mechanisms for acquiring the data content represented by the keys. Examples could include property files, XML files, databases, web application resources, and other specialized approaches as desired.

Different implementations of the Resources interface may apply different semantics to the use of the locale and/or timeZone attributes used to perform localization. Consult the documentation for the specific Resources implementation you are using for the specific details of your implementation.

Developers implementing Resources should extend the ResourcesBase class, and override the necessary methods, to shield themselves from future changes that may occur in this interface.

See Also:

ResourcesBase, CollectionResourcesBase, JDBCResources, PropertyResources, ResourceBundleResources, WebappPropertyResources, WebappXMLResources, XMLResources

Method Summary

void	destroy() This method must be called when the manager of this resource decides that it's no longer needed.
byte[]	getBytes(String key, Locale locale, TimeZone timeZone) Return the content for the specified key as a byte array, localized based on the specified locale and/or timeZone.
InputStream	getInputStream(String key, Locale locale, TimeZone timeZone) Return the content for the specified key as an InputStream, localized based on the specified locale and/or timeZone.
Iterator	getKeys() Return an Iterator over the defined keys in this Resources instance.
String	getName() Return the logical name of this Resources instance.
Object	getObject(String key, Locale locale, TimeZone timeZone) Return the content for the specified key as an Object, localized based on the specified locale and/or timeZone.
Reader	getReader(String key, Locale locale, TimeZone timeZone) Return the content for the specified key as a Reader, localized based on the specified locale and/or timeZone.
String	getString(String key, Locale locale, TimeZone timeZone) Return the content for the specified key as a String, localized based on the specified locale and/or timeZone.
void	init() This must be called to initialize the data content of this Resources instance, before any of the getXxx() methods are called.
boolean	isReturnNull() Return true if resource getter methods will return null instead of throwing an exception on invalid key values.
void	setReturnNull(boolean returnNull) Set a flag determining whether resource getter methods should return null instead of throwing an exception on invalid key values.

Method Detail

init

public void init()

This must be called to initialize the data content of this Resources instance, before any of the getXxx() methods are called.

Throws:

ResourcesException - if an error occurs during initialization

destroy

public void destroy()

This method must be called when the manager of this resource decides that it's no longer needed. After this method is called, no further calls to any of the getXxx() methods are allowed.

Throws:

ResourcesException - if an error occurs during finalization

getKeys

public Iterator getKeys()

Return an Iterator over the defined keys in this Resources instance.

Returns:

The keys contained in this resources instance.

getName

public String getName()

Return the logical name of this Resources instance.

Returns:

The name of this resources instance.

isReturnNull

public boolean isReturnNull()

Return true if resource getter methods will return null instead of throwing an exception on invalid key values.

Returns:

true if null is returned for invalid key values.

setReturnNull

public void setReturnNull(boolean returnNull)

Set a flag determining whether resource getter methods should return null instead of throwing an exception on invalid key values.

Parameters:

returnNull - The new flag value

getBytes

public byte[] getBytes(String key,
                       Locale locale,
                       TimeZone timeZone)

Return the content for the specified key as a byte array, localized based on the specified locale and/or timeZone.

Parameters:

key - Identifier for the requested content

locale - Locale with which to localize retrieval, or null for the default Locale

timeZone - TimeZone with which to localize retrieval, or null for the default TimeZone

Returns:

content for a specified key.

Throws:

ResourcesException - if an error occurs retrieving or returning the requested content

ResourcesKeyException - if no value for the specified key was found, and isReturnNull() returns false

getInputStream

public InputStream getInputStream(String key,
                                  Locale locale,
                                  TimeZone timeZone)

Return the content for the specified key as an InputStream, localized based on the specified locale and/or timeZone.

Parameters:

key - Identifier for the requested content

locale - Locale with which to localize retrieval, or null for the default Locale

timeZone - TimeZone with which to localize retrieval, or null for the default TimeZone

Returns:

content for a specified key.

Throws:

ResourcesException - if an error occurs retrieving or returning the requested content

ResourcesKeyException - if no value for the specified key was found, and isReturnNull() returns false

getObject

public Object getObject(String key,
                        Locale locale,
                        TimeZone timeZone)

Return the content for the specified key as an Object, localized based on the specified locale and/or timeZone.

Parameters:

key - Identifier for the requested content

locale - Locale with which to localize retrieval, or null for the default Locale

timeZone - TimeZone with which to localize retrieval, or null for the default TimeZone

Returns:

content for a specified key.

Throws:

ResourcesException - if an error occurs retrieving or returning the requested content

ResourcesKeyException - if no value for the specified key was found, and isReturnNull() returns false

getReader

public Reader getReader(String key,
                        Locale locale,
                        TimeZone timeZone)

Return the content for the specified key as a Reader, localized based on the specified locale and/or timeZone.

Parameters:

key - Identifier for the requested content

locale - Locale with which to localize retrieval, or null for the default Locale

timeZone - TimeZone with which to localize retrieval, or null for the default TimeZone

Returns:

content for a specified key.

Throws:

ResourcesException - if an error occurs retrieving or returning the requested content

ResourcesKeyException - if no value for the specified key was found, and isReturnNull() returns false

getString

public String getString(String key,
                        Locale locale,
                        TimeZone timeZone)

Return the content for the specified key as a String, localized based on the specified locale and/or timeZone.

Parameters:

key - Identifier for the requested content

locale - Locale with which to localize retrieval, or null for the default Locale

timeZone - TimeZone with which to localize retrieval, or null for the default TimeZone

Returns:

content for a specified key.

Throws:

ResourcesException - if an error occurs retrieving or returning the requested content

ResourcesKeyException - if no value for the specified key was found, and isReturnNull() returns false