org.apache.velocity.tools.generic
Class ResourceTool

java.lang.Object
  org.apache.velocity.tools.generic.SafeConfig
      org.apache.velocity.tools.generic.LocaleConfig
          org.apache.velocity.tools.generic.ResourceTool

Direct Known Subclasses:

ViewResourceTool

@DefaultKey(value="text")
public class ResourceTool
extends LocaleConfig

Tool for accessing ResourceBundles and formatting messages therein.

 Template example(s):
   $text.foo                      ->  bar
   $text.hello.world              ->  Hello World!
   $text.keys                     ->  [foo, hello.world, world]
   #set( $otherText = $text.bundle('otherBundle') )
   $otherText.foo                 ->  woogie
   $otherText.bar                 ->  The args are {0} and {1}.
   $otherText.bar.insert(4)       ->  The args are 4 and {1}.
   $otherText.bar.insert(4,true)  ->  The args are 4 and true.

 Toolbox configuration example:
 <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.generic.ResourceTool"
              bundles="resources,com.foo.moreResources"
              locale="en_US"/>
   </toolbox>
 </tools>
 

This comes in very handy when internationalizing templates. Note that the default resource bundle baseName is "resources", and the default locale is either:

• the result of HttpServletRequest.getLocale() (if used in request scope of a VelocityView app)
• the configured locale for this tool (as shown above)
• the configured locale for the toolbox this tool is in
• the configured locale for the toolbox factory managing this tool
• the system locale, if none of the above

.

Also, be aware that very few performance considerations have been made in this initial version. It should do fine, but if you have performance issues, please report them to dev@velocity.apache.org, so we can make improvements.

Since:

VelocityTools 1.3

Version:

$Revision: 722509 $ $Date: 2006-11-27 10:49:37 -0800 (Mon, 27 Nov 2006) $

Author:

Nathan Bubna

Nested Class Summary

class

ResourceTool.Key Internal class used to enable an elegant syntax for accessing resources.

Field Summary

private java.lang.String[]	bundles
static java.lang.String	BUNDLES_KEY
private boolean	deprecationSupportMode

Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig

DEFAULT_LOCALE

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

ResourceTool()

Method Summary

ResourceTool.Key	bundle(java.lang.String bundle)
protected void	configure(ValueParser parser) Does the actual configuration.
ResourceTool.Key	get(java.lang.Object k) Accepts objects and uses their string value as the key.
java.lang.Object	get(java.lang.Object k, java.lang.String[] bundles, java.lang.Object l) Retrieve a resource for the specified key from the first of the specified bundles in which a matching resource is found.
java.lang.Object	get(java.lang.Object key, java.lang.String baseName, java.lang.Object loc) Returns the value for the specified key in the ResourceBundle for the specified basename and locale.
ResourceTool.Key	get(java.lang.String key)
protected java.util.ResourceBundle	getBundle(java.lang.String baseName, java.lang.Object loc) Retrieves the ResourceBundle for the specified baseName and locale, if such exists.
protected java.lang.String	getDefaultBundle()
protected java.util.Locale	getDefaultLocale() Deprecated.
java.util.List<java.lang.String>	getKeys()
java.util.List<java.lang.String>	getKeys(java.lang.String prefix, java.lang.String[] bundles, java.lang.Object loc) Returns a List of the key strings in the specified ResourceBundles.
java.util.List<java.lang.String>	getKeys(java.lang.String prefix, java.lang.String baseName, java.lang.Object loc) Returns a List of the key strings in the ResourceBundle with the specified baseName and locale.
ResourceTool.Key	insert(java.util.List args)
ResourceTool.Key	insert(java.lang.Object arg)
ResourceTool.Key	insert(java.lang.Object[] args)
ResourceTool.Key	insert(java.lang.Object arg0, java.lang.Object arg1)
ResourceTool.Key	locale(java.lang.Object locale)
java.lang.String	render(java.lang.Object resource, java.lang.Object[] args) Renders the specified resource value and arguments as a String.
protected void	setDefaultBundle(java.lang.String bundle)
protected void	setDefaultLocale(java.util.Locale locale) Deprecated.
void	setDeprecationSupportMode(boolean depMode) Deprecated.
private java.util.Locale	toLocale(java.lang.Object obj)

Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

getLocale, setLocale

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

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

Field Detail

BUNDLES_KEY

public static final java.lang.String BUNDLES_KEY

See Also:

Constant Field Values

bundles

private java.lang.String[] bundles

deprecationSupportMode

private boolean deprecationSupportMode

Constructor Detail

ResourceTool

public ResourceTool()

Method Detail

setDefaultBundle

protected final void setDefaultBundle(java.lang.String bundle)

getDefaultBundle

protected final java.lang.String getDefaultBundle()

setDefaultLocale

@Deprecated
protected final void setDefaultLocale(java.util.Locale locale)

Deprecated.

getDefaultLocale

@Deprecated
protected final java.util.Locale getDefaultLocale()

Deprecated.

setDeprecationSupportMode

@Deprecated
public void setDeprecationSupportMode(boolean depMode)

Deprecated.

configure

protected void configure(ValueParser parser)

Description copied from class: LocaleConfig

Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.

Overrides:

configure in class LocaleConfig

get

public ResourceTool.Key get(java.lang.Object k)

Accepts objects and uses their string value as the key.

get

public ResourceTool.Key get(java.lang.String key)

getKeys

public java.util.List<java.lang.String> getKeys()

bundle

public ResourceTool.Key bundle(java.lang.String bundle)

locale

public ResourceTool.Key locale(java.lang.Object locale)

insert

public ResourceTool.Key insert(java.lang.Object[] args)

insert

public ResourceTool.Key insert(java.util.List args)

insert

public ResourceTool.Key insert(java.lang.Object arg)

insert

public ResourceTool.Key insert(java.lang.Object arg0,
                               java.lang.Object arg1)

getBundle

protected java.util.ResourceBundle getBundle(java.lang.String baseName,
                                             java.lang.Object loc)

Retrieves the ResourceBundle for the specified baseName and locale, if such exists. If the baseName or locale is null or if the locale argument cannot be converted to a Locale, then this will return null.

get

public java.lang.Object get(java.lang.Object key,
                            java.lang.String baseName,
                            java.lang.Object loc)

Returns the value for the specified key in the ResourceBundle for the specified basename and locale. If no such resource can be found, no errors are thrown and null is returned.

Parameters:

key - the key for the requested resource

baseName - the base name of the resource bundle to search

loc - the locale to use

get

public java.lang.Object get(java.lang.Object k,
                            java.lang.String[] bundles,
                            java.lang.Object l)

Retrieve a resource for the specified key from the first of the specified bundles in which a matching resource is found. If no resource is found, no exception will be thrown and null will be returned.

Parameters:

k - the key for the requested resource

bundles - the resource bundles to search

l - the locale to use

getKeys

public java.util.List<java.lang.String> getKeys(java.lang.String prefix,
                                                java.lang.String baseName,
                                                java.lang.Object loc)

Returns a List of the key strings in the ResourceBundle with the specified baseName and locale. If the specified prefix is not null, then this will skip any keys that do not begin with that prefix and trim the prefix and any subsequent '.' off of the remaining ones. If the prefix is null, then no filtering or trimming will be done.

Parameters:

prefix - the prefix for the requested keys

bundles - the resource bundles to search

loc - the locale to use

getKeys

public java.util.List<java.lang.String> getKeys(java.lang.String prefix,
                                                java.lang.String[] bundles,
                                                java.lang.Object loc)

Returns a List of the key strings in the specified ResourceBundles. If the specified prefix is not null, then this will skip any keys that do not begin with that prefix and trim the prefix and any subsequent '.' off of the remaining ones. If the prefix is null, then no filtering or trimming will be done.

Parameters:

prefix - the prefix for the requested keys

bundles - the resource bundles to search

loc - the locale to use

See Also:

getKeys(String,String,Object)

toLocale

private java.util.Locale toLocale(java.lang.Object obj)

render

public java.lang.String render(java.lang.Object resource,
                               java.lang.Object[] args)

Renders the specified resource value and arguments as a String. The resource is treated as a MessageFormat pattern which is used for formatting along with any specified argument values. If deprecationSupportMode is set to true, then this will return the resource directly when there are no args (as it did in 1.x versions).