Class RenderTool
- java.lang.Object
-
- org.apache.velocity.tools.generic.SafeConfig
-
- org.apache.velocity.tools.generic.RenderTool
-
- Direct Known Subclasses:
ViewRenderTool
@DefaultKey("render") 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)
andrecurse(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)
andrecurse(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: 671010 $ $Date: 2008-06-23 20:40:41 -0700 (Mon, 23 Jun 2008) $
- Author:
- Nathan Bubna
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
catchExceptions
private org.apache.velocity.context.Context
context
static int
DEFAULT_PARSE_DEPTH
The maximum number of loops allowed when recursing.private org.apache.velocity.app.VelocityEngine
engine
private boolean
forceThreadSafe
static java.lang.String
KEY_CATCH_EXCEPTIONS
Deprecated.static java.lang.String
KEY_FORCE_THREAD_SAFE
static java.lang.String
KEY_PARSE_DEPTH
Deprecated.private static java.lang.String
LOG_TAG
private int
parseDepth
-
Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
-
-
Constructor Summary
Constructors Constructor Description RenderTool()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
configure(ValueParser parser)
Looks for deprecated parse depth and catch.exceptions properties, as well as any 'forceThreadSafe' setting.private void
debug(java.lang.String message)
private void
debug(java.lang.String message, java.lang.Throwable t)
java.lang.String
eval(java.lang.String vtl)
Evaluates a String containing VTL using the context passed to thesetVelocityContext(org.apache.velocity.context.Context)
method.java.lang.String
eval(org.apache.velocity.context.Context ctx, java.lang.String vtl)
Evaluates a String containing VTL using the current context, and returns the result as a String.boolean
getCatchExceptions()
Returnstrue
if this render() and eval() methods will catch exceptions thrown during rendering.int
getParseDepth()
Get the maximum number of loops allowed when recursing.protected java.lang.String
internalEval(org.apache.velocity.context.Context ctx, java.lang.String vtl)
protected java.lang.String
internalRecurse(org.apache.velocity.context.Context ctx, java.lang.String vtl, int count)
java.lang.String
recurse(java.lang.String vtl)
Recursively evaluates a String containing VTL using the current context, and returns the result as a String.java.lang.String
recurse(org.apache.velocity.context.Context ctx, java.lang.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)
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, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
-
-
-
-
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 java.lang.String KEY_PARSE_DEPTH
Deprecated.- See Also:
- Constant Field Values
-
KEY_CATCH_EXCEPTIONS
@Deprecated public static final java.lang.String KEY_CATCH_EXCEPTIONS
Deprecated.- See Also:
- Constant Field Values
-
KEY_FORCE_THREAD_SAFE
public static final java.lang.String KEY_FORCE_THREAD_SAFE
- See Also:
- Constant Field Values
-
LOG_TAG
private static final java.lang.String LOG_TAG
- See Also:
- Constant Field Values
-
engine
private org.apache.velocity.app.VelocityEngine engine
-
context
private org.apache.velocity.context.Context context
-
parseDepth
private int parseDepth
-
catchExceptions
private boolean catchExceptions
-
forceThreadSafe
private boolean forceThreadSafe
-
-
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 classSafeConfig
-
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.
-
setParseDepth
public void setParseDepth(int depth)
Set the maximum number of loops allowed when recursing.- Since:
- VelocityTools 1.2
-
setVelocityContext
public void setVelocityContext(org.apache.velocity.context.Context context)
-
getParseDepth
public int getParseDepth()
Get the maximum number of loops allowed when recursing.- 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.- Since:
- VelocityTools 1.3
-
getCatchExceptions
public boolean getCatchExceptions()
Returnstrue
if this render() and eval() methods will catch exceptions thrown during rendering.- Since:
- VelocityTools 1.3
-
eval
public java.lang.String eval(java.lang.String vtl) throws java.lang.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:
java.lang.Exception
-
recurse
public java.lang.String recurse(java.lang.String vtl) throws java.lang.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:
java.lang.Exception
- See Also:
eval(String)
-
eval
public java.lang.String eval(org.apache.velocity.context.Context ctx, java.lang.String vtl) throws java.lang.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 Contextvtl
- the code to be evaluated- Returns:
- the evaluated code as a String
- Throws:
java.lang.Exception
-
internalEval
protected java.lang.String internalEval(org.apache.velocity.context.Context ctx, java.lang.String vtl) throws java.lang.Exception
- Throws:
java.lang.Exception
-
recurse
public java.lang.String recurse(org.apache.velocity.context.Context ctx, java.lang.String vtl) throws java.lang.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 Contextvtl
- the code to be evaluated- Returns:
- the evaluated code as a String
- Throws:
java.lang.Exception
-
internalRecurse
protected java.lang.String internalRecurse(org.apache.velocity.context.Context ctx, java.lang.String vtl, int count) throws java.lang.Exception
- Throws:
java.lang.Exception
-
debug
private void debug(java.lang.String message)
-
debug
private void debug(java.lang.String message, java.lang.Throwable t)
-
-