org.apache.velocity.tools.generic

## Class RenderTool

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

    @DefaultKey(value="render")
     @InvalidScope(value="session")
    public class RenderTool
    extends SafeConfig

This tool exposes methods to evaluate the given strings as VTL (Velocity Template Language) using either a pre-configured context or one you provide directly.

     Example of eval():
          Input
          -----
          #set( $list = [1,2,3] )
          #set( $object = '$list' )
          #set( $method = 'size()' )
          $render.eval("${object}.$method")

          Output
          ------
          3

     Example of recurse():
          Input
          -----
          #macro( say_hi )hello world!#end
          #set( $foo = '#say_hi()' )
          #set( $bar = '$foo' )
          $render.recurse($bar)

          Output
          ------
          hello world!

     Toolbox configuration:
     <tools>
       <toolbox scope="request">
         <tool class="org.apache.velocity.tools.generic.RenderTool">
           <property name="parseDepth" type="number" value="10"/>
         </tool>
       </toolbox>
     </tools>

Ok, so these examples are really lame. But, it seems like someone out there is always asking how to do stuff like this and we always tell them to write a tool. Now we can just tell them to use this tool.

This tool may be used in any scope, however, the context provided for the `eval(String)` and `recurse(String)` methods will only be current if the tool is request scoped. If application or session scoped, then the context will be the same one set at the time of the tool's first use. In such a case, each call to eval(String) or recurse(String) will by default create a new Context that wraps the configured one to prevent modifications to the configured Context (concurrent or otherwise). If you wish to risk it and accrete changes then you can relax the thread-safety by setting the 'forceThreadSafe' property to 'false'.

Of course none of the previous paragraph likely applies if you are not using the core tool management facilities or if you stick to the `eval(Context,String)` and `recurse(Context,String)` methods. :)

This tool by default will catch and log any exceptions thrown during rendering and instead return null in such cases. It also limits recursion, by default, to 20 cycles, to prevent infinite loops. Both settings may be configured to behave otherwise.

Version:
  $Revision$ $Date$
Author:
  Nathan Bubna

### Field Summary

Fields
`static int` `DEFAULT_PARSE_DEPTH` The maximum number of loops allowed when recursing.
`static String` `KEY_CATCH_EXCEPTIONS` Deprecated.
`static String` `KEY_FORCE_THREAD_SAFE`
`static String` `KEY_PARSE_DEPTH` Deprecated.

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

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `configure(ValueParser parser)` Looks for deprecated parse depth and catch.exceptions properties, as well as any 'forceThreadSafe' setting.
`String` `eval(org.apache.velocity.context.Context ctx, String vtl)` Evaluates a String containing VTL using the current context, and returns the result as a String.
`String` `eval(String vtl)` Evaluates a String containing VTL using the context passed to the `setVelocityContext(org.apache.velocity.context.Context)` method.
`boolean` `getCatchExceptions()` Returns `true` if this render() and eval() methods will catch exceptions thrown during rendering.
`int` `getParseDepth()` Get the maximum number of loops allowed when recursing.
`protected String` `internalEval(org.apache.velocity.context.Context ctx, String vtl)`
`protected String` `internalRecurse(org.apache.velocity.context.Context ctx, String vtl, int count)`
`String` `recurse(org.apache.velocity.context.Context ctx, String vtl)` Recursively evaluates a String containing VTL using the current context, and returns the result as a String.
`String` `recurse(String vtl)` Recursively evaluates a String containing VTL using the current context, and returns the result as a String.
`void` `setCatchExceptions(boolean catchExceptions)` Sets whether or not the render() and eval() methods should catch exceptions during their execution or not.
`void` `setParseDepth(int depth)` Set the maximum number of loops allowed when recursing.
`void` `setVelocityContext(org.apache.velocity.context.Context context)` Sets the `Context` to be used by the `eval(String)` and `recurse(String)` methods.
`void` `setVelocityEngine(org.apache.velocity.app.VelocityEngine ve)` Allow user to specify a VelocityEngine to be used in place of the Velocity singleton.

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

#### DEFAULT_PARSE_DEPTH

    public static final int DEFAULT_PARSE_DEPTH

The maximum number of loops allowed when recursing.

Since:
  VelocityTools 1.2
See Also:
  Constant Field Values

#### KEY_PARSE_DEPTH

    @Deprecated
    public static final String KEY_PARSE_DEPTH

Deprecated.

See Also:
  Constant Field Values

#### KEY_CATCH_EXCEPTIONS

    @Deprecated
    public static final String KEY_CATCH_EXCEPTIONS

Deprecated.

See Also:
  Constant Field Values

#### KEY_FORCE_THREAD_SAFE

    public static final String KEY_FORCE_THREAD_SAFE

See Also:
  Constant Field Values

### Constructor Detail

#### RenderTool

    public RenderTool()

### Method Detail

#### configure

    protected void configure(ValueParser parser)

Looks for deprecated parse depth and catch.exceptions properties, as well as any 'forceThreadSafe' setting.

Overrides:
  `configure` in class `SafeConfig`
Parameters:
  `parser` - configuration values

#### setVelocityEngine

    public void setVelocityEngine(org.apache.velocity.app.VelocityEngine ve)

Allow user to specify a VelocityEngine to be used in place of the Velocity singleton.

Parameters:
  `ve` - VelocityEngine instance

#### setParseDepth

    public void setParseDepth(int depth)

Set the maximum number of loops allowed when recursing.

Parameters:
  `depth` - parse depth
Since:
  VelocityTools 1.2

#### setVelocityContext

    public void setVelocityContext(org.apache.velocity.context.Context context)

Sets the `Context` to be used by the `eval(String)` and `recurse(String)` methods.

Parameters:
  `context` - Velocity context

#### getParseDepth

    public int getParseDepth()

Get the maximum number of loops allowed when recursing.

Returns:
  parse depth
Since:
  VelocityTools 1.2

#### setCatchExceptions

    public void setCatchExceptions(boolean catchExceptions)

Sets whether or not the render() and eval() methods should catch exceptions during their execution or not.

Parameters:
  `catchExceptions` - whether to catch exceptions
Since:
  VelocityTools 1.3

#### getCatchExceptions

    public boolean getCatchExceptions()

Returns `true` if this render() and eval() methods will catch exceptions thrown during rendering.

Returns:
  whether to catch exceptions
Since:
  VelocityTools 1.3

#### eval

    public String eval(String vtl)
                throws Exception

Evaluates a String containing VTL using the context passed to the `setVelocityContext(org.apache.velocity.context.Context)` method. If this tool is request scoped, then this will be the current context and open to modification by the rendered VTL. If application or session scoped, the context will be a new wrapper around the configured context to protect it from modification. The results of the rendering are returned as a String. By default, `null` will be returned when this throws an exception. This evaluation is not recursive.

Parameters:
  `vtl` - the code to be evaluated
Returns:
  the evaluated code as a String
Throws:
  `Exception` - if womething went wrong

#### recurse

    public String recurse(String vtl)
                   throws Exception

Recursively evaluates a String containing VTL using the current context, and returns the result as a String. It will continue to re-evaluate the output of the last evaluation until an evaluation returns the same code that was fed into it.

Parameters:
  `vtl` - the code to be evaluated
Returns:
  the evaluated code as a String
Throws:
  `Exception` - if womething went wrong
See Also:
  `eval(String)`

#### eval

    public String eval(org.apache.velocity.context.Context ctx,
                       String vtl)
                throws Exception

Evaluates a String containing VTL using the current context, and returns the result as a String. By default if this fails, then `null` will be returned, though this tool can be configured to let Exceptions pass through. This evaluation is not recursive.

Parameters:
  `ctx` - the current Context
  `vtl` - the code to be evaluated
Returns:
  the evaluated code as a String
Throws:
  `Exception` - if womething went wrong

#### internalEval

    protected String internalEval(org.apache.velocity.context.Context ctx,
                                  String vtl)
                           throws Exception

Throws:
  `Exception`

#### recurse

    public String recurse(org.apache.velocity.context.Context ctx,
                          String vtl)
                   throws Exception

Recursively evaluates a String containing VTL using the current context, and returns the result as a String. It will continue to re-evaluate the output of the last evaluation until an evaluation returns the same code that was fed into it or the number of recursive loops exceeds the set parse depth.

Parameters:
  `ctx` - the current Context
  `vtl` - the code to be evaluated
Returns:
  the evaluated code as a String
Throws:
  `Exception` - if womething went wrong

#### internalRecurse

    protected String internalRecurse(org.apache.velocity.context.Context ctx,
                                     String vtl,
                                     int count)
                              throws Exception

Throws:
  `Exception`