org.apache.velocity.tools.generic

## Class FieldTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.generic.FieldTool

    @DefaultKey(value="field")
     @ValidScope(value="application")
    public class FieldTool
    extends SafeConfig

This is a simple tools class to allow easy access to static fields in a class, such as string constants from within a template. Velocity will not introspect for class fields (and won't in the future :), but writing setter/getter methods to do this is a pain, so use this if you really have to access fields.

Example uses in a template:

       ## here we access a constant in a class include in the configuration
         $field.COUNTER_NAME

       ## here we dynamically lookup a class' fields to find another constant
         $field.in("org.com.SomeClass").ANOTHER_CONSTANT

       ## here we pass an object instance in (an Integer in this case) and
       ## retrieve a static constant from that instance's class
         $field.in(0).MIN_VALUE

       ## by default, once we've searched a class' fields, those fields stay
       ## available in the tool (change this by storeDynamicLookups="false")
       ## so here we get another constant from the Integer class
         $field.MAX_VALUE

Example tools.xml config:

     <tools>
       <toolbox scope="application">
         <tool class="org.apache.velocity.tools.generic.FieldTool"
                  include="org.apache.velocity.runtime.RuntimeConstants,com.org.MyConstants"/>
       </toolbox>
     </tools>

Right now, this tool only gives access to `public static` fields. It seems that anything else is too dangerous. This is for convenient access to 'constants'. If you have fields that aren't `static`, handle them by explicitly placing them into the context or writing a getter method.

Since:
  VelocityTools 2.0
Version:
  $Id: FieldTool.java 463298 2006-10-12 16:10:32Z henning $
Author:
  Geir Magnusson Jr., Nathan Bubna

### Nested Class Summary

Nested Classes
`static class` `FieldTool.FieldToolSub` Holds a `Map` of results for a particular class.
`class` `FieldTool.MutableField` Holds a `Field` and `Class` reference for later retrieval of the value of a field that is not final and may change at different lookups.

### Field Summary

Fields
`static String` `INCLUDE_KEY` The key used for specifying which classes should be inspected for public static methods to be made available.
`protected HashMap` `storage`
`static String` `STORE_DYNAMIC_KEY` The key used for specifying whether or not the tool should store fields in classes dynamically looked up from within a template.
`protected boolean` `storeDynamicLookups`

### 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
`FieldTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `configure(ValueParser values)` Does the actual configuration.
`Object` `get(String name)` Returns the value for the specified field name as found in the stored `Map` of field names to values (or placeholders).
`FieldTool.FieldToolSub` `in(Class clazz)` Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the specified `Class`.
`FieldTool.FieldToolSub` `in(Object instance)` Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the `Class` of the specified Object.
`FieldTool.FieldToolSub` `in(String classname)` Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the specified class(name).
`protected Map<String,Object>` `inspect(Class clazz)` Looks for all public, static fields in the specified class and stores their value (if final) or else a `FieldTool.MutableField` for in a `Map` under the fields' names.
`protected Object` `retrieve(Field field, Class clazz)` Retrieves and returns the value of the specified `Field` in the specified `Class`.

### 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

#### INCLUDE_KEY

    public static final String INCLUDE_KEY

The key used for specifying which classes should be inspected for public static methods to be made available.

See Also:
  Constant Field Values

#### STORE_DYNAMIC_KEY

    public static final String STORE_DYNAMIC_KEY

The key used for specifying whether or not the tool should store fields in classes dynamically looked up from within a template. The default value is true.

See Also:
  Constant Field Values

#### storage

    protected HashMap storage

#### storeDynamicLookups

    protected boolean storeDynamicLookups

### Constructor Detail

#### FieldTool

    public FieldTool()

### Method Detail

#### configure

    protected void configure(ValueParser values)

Description copied from class: `SafeConfig`
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 `SafeConfig`
Parameters:
  `values` - configuration values

#### get

    public Object get(String name)

Returns the value for the specified field name as found in the stored `Map` of field names to values (or placeholders). Returns `null` if there is no matching field.

Parameters:
  `name` - field name
Returns:
  field value

#### in

    public FieldTool.FieldToolSub in(String classname)

Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the specified class(name). If the `Class` with the specified name cannot be loaded, this will return `null`, rather than throw an exception.

Parameters:
  `classname` - target class name
Returns:
  `FieldTool.FieldToolSub` object
See Also:
  `in(Class clazz)`

#### in

    public FieldTool.FieldToolSub in(Object instance)

Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the `Class` of the specified Object.

Parameters:
  `instance` - target instance
Returns:
  `FieldTool.FieldToolSub` object
See Also:
  `in(Class clazz)`

#### in

    public FieldTool.FieldToolSub in(Class clazz)

Returns a `FieldTool.FieldToolSub` holding a `Map` of all the public static field names to values (or a placeholder if the value is not final) for the specified `Class`.

Parameters:
  `clazz` - target class
Returns:
  `FieldTool.FieldToolSub` object

#### inspect

    protected Map<String,Object> inspect(Class clazz)

Looks for all public, static fields in the specified class and stores their value (if final) or else a `FieldTool.MutableField` for in a `Map` under the fields' names. This will never return null, only an empty Map if there are no public static fields.

Parameters:
  `clazz` - target class
Returns:
  fields map

#### retrieve

    protected Object retrieve(Field field,
                              Class clazz)

Retrieves and returns the value of the specified `Field` in the specified `Class`. Returns `null` in case of failure.

Parameters:
  `field` - target field
  `clazz` - target class
Returns:
  field value