org.apache.commons.resources
Interface Resources

All Superinterfaces:

Serializable

All Known Implementing Classes:

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

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 parameter) 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 attribute 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) Return the content for the specified key as a byte array, localized based on the specified locale.
InputStream	getInputStream(String key, Locale locale) Return the content for the specified key as an InputStream, localized based on the specified locale.
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) Return the content for the specified key as an Object, localized based on the specified locale.
Reader	getReader(String key, Locale locale) Return the content for the specified key as a Reader, localized based on the specified locale.
String	getString(String key, Locale locale) Return the content for the specified key as a String, localized based on the specified locale.
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

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

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

Iterator getKeys()

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

Returns:

The keys contained in this resources instance.

getName

String getName()

Return the logical name of this Resources instance.

Returns:

The name of this resources instance.

isReturnNull

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

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

byte[] getBytes(String key,
                Locale locale)

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

Parameters:

key - Identifier for the requested content

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

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

InputStream getInputStream(String key,
                           Locale locale)

Return the content for the specified key as an InputStream, localized based on the specified locale.

Parameters:

key - Identifier for the requested content

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

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

Object getObject(String key,
                 Locale locale)

Return the content for the specified key as an Object, localized based on the specified locale.

Parameters:

key - Identifier for the requested content

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

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

Reader getReader(String key,
                 Locale locale)

Return the content for the specified key as a Reader, localized based on the specified locale.

Parameters:

key - Identifier for the requested content

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

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

String getString(String key,
                 Locale locale)

Return the content for the specified key as a String, localized based on the specified locale.

Parameters:

key - Identifier for the requested content

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

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