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

All Implemented Interfaces:
  Serializable

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

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$ $Date: 2006-11-27 10:49:37 -0800 (Mon, 27 Nov 2006) $
Author:
  Nathan Bubna
See Also:
  Serialized Form

### Nested Class Summary

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

### Field Summary

Fields
`static String` `BUNDLES_KEY`

### 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, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`ResourceTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`ResourceTool.Key` `bundle(String bundle)`
`protected void` `configure(ValueParser parser)` Does the actual configuration.
`ResourceTool.Key` `get(Object k)` Accepts objects and uses their string value as the key.
`Object` `get(Object k, String[] bundles, Object l)` Retrieve a resource for the specified key from the first of the specified bundles in which a matching resource is found.
`Object` `get(Object key, String baseName, Object loc)` Returns the value for the specified key in the ResourceBundle for the specified basename and locale.
`ResourceTool.Key` `get(String key)` Accepts objects and uses their string value as the key.
`protected ResourceBundle` `getBundle(String baseName, Object loc)` Retrieves the `ResourceBundle` for the specified baseName and locale, if such exists.
`protected String` `getDefaultBundle()`
`List<String>` `getKeys()` Lists available keys
`List<String>` `getKeys(String prefix, String[] bundles, Object loc)` Returns a `List` of the key strings in the specified ResourceBundles.
`List<String>` `getKeys(String prefix, String baseName, Object loc)` Returns a `List` of the key strings in the ResourceBundle with the specified baseName and locale.
`ResourceTool.Key` `insert(List args)`
`ResourceTool.Key` `insert(Object arg)`
`ResourceTool.Key` `insert(Object[] args)`
`ResourceTool.Key` `insert(Object arg0, Object arg1)`
`ResourceTool.Key` `locale(Object locale)`
`String` `render(Object resource, Object[] args)` Renders the specified resource value and arguments as a String.
`protected void` `setDefaultBundle(String bundle)`

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

`getLocale, setLocale, toLocale`

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

`configure, getLog, initLogger, 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 String BUNDLES_KEY

See Also:
  Constant Field Values

### Constructor Detail

#### ResourceTool

    public ResourceTool()

### Method Detail

#### setDefaultBundle

    protected final void setDefaultBundle(String bundle)

#### getDefaultBundle

    protected final String getDefaultBundle()

#### 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`
Parameters:
  `parser` - configuration values

#### get

    public ResourceTool.Key get(Object k)

Accepts objects and uses their string value as the key.

Parameters:
  `k` - key
Returns:
  Key object

#### get

    public ResourceTool.Key get(String key)

Accepts objects and uses their string value as the key.

Parameters:
  `key` - key
Returns:
  Key object

#### getKeys

    public List<String> getKeys()

Lists available keys

Returns:
  keys list

#### bundle

    public ResourceTool.Key bundle(String bundle)

#### locale

    public ResourceTool.Key locale(Object locale)

#### insert

    public ResourceTool.Key insert(Object[] args)

#### insert

    public ResourceTool.Key insert(List args)

#### insert

    public ResourceTool.Key insert(Object arg)

#### insert

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

#### getBundle

    protected ResourceBundle getBundle(String baseName,
                                       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.

Parameters:
  `baseName` - base name
  `loc` - locale
Returns:
  resource bundle

#### get

    public Object get(Object key,
                      String baseName,
                      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
Returns:
  value

#### get

    public Object get(Object k,
                      String[] bundles,
                      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
Returns:
  value

#### getKeys

    public List<String> getKeys(String prefix,
                                String baseName,
                                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
  `baseName` - the resource bundle base name
  `loc` - the locale to use
Returns:
  keys list

#### getKeys

    public List<String> getKeys(String prefix,
                                String[] bundles,
                                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
Returns:
  keys list
See Also:
  `getKeys(String,String,Object)`

#### render

    public String render(Object resource,
                         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.

Parameters:
  `resource` - resource object
  `args` - arguments
Returns:
  formatted string