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")
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

static class	FieldTool.FieldToolSub Holds a Map of results for a particular class.
static 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

static java.lang.String	INCLUDE_KEY The key used for specifying which classes should be inspected for public static methods to be made available.
protected org.apache.velocity.runtime.log.Log	log
protected java.util.HashMap	storage
static java.lang.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, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

FieldTool()

Method Summary

protected void	configure(ValueParser values) Does the actual configuration.
java.lang.Object	get(java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.util.Map<java.lang.String,java.lang.Object>	inspect(java.lang.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 static java.lang.Object	retrieve(java.lang.reflect.Field field, java.lang.Class clazz, org.apache.velocity.runtime.log.Log log) Retrieves and returns the value of the specified Field in the specified Class.

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

INCLUDE_KEY

public static final java.lang.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 java.lang.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

log

protected org.apache.velocity.runtime.log.Log log

storage

protected java.util.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

get

public java.lang.Object get(java.lang.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.

in

public FieldTool.FieldToolSub in(java.lang.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.

See Also:

in(Class clazz)

in

public FieldTool.FieldToolSub in(java.lang.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.

See Also:

in(Class clazz)

in

public FieldTool.FieldToolSub in(java.lang.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.

inspect

protected java.util.Map<java.lang.String,java.lang.Object> inspect(java.lang.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.

retrieve

protected static java.lang.Object retrieve(java.lang.reflect.Field field,
                                           java.lang.Class clazz,
                                           org.apache.velocity.runtime.log.Log log)

Retrieves and returns the value of the specified Field in the specified Class. If Log is provided, then access errors will be logged, otherwise this will fail silently and return null.