|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.velocity.tools.generic.SafeConfig org.apache.velocity.tools.generic.RenderTool
@DefaultKey(value="render") public class RenderTool
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.
Field Summary | |
---|---|
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 | |
---|---|
RenderTool()
|
Method Summary | |
---|---|
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(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. |
java.lang.String |
eval(java.lang.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 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(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. |
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. |
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, isConfigLocked, isSafeMode, setLockConfig, setSafeMode |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int DEFAULT_PARSE_DEPTH
@Deprecated public static final java.lang.String KEY_PARSE_DEPTH
@Deprecated public static final java.lang.String KEY_CATCH_EXCEPTIONS
public static final java.lang.String KEY_FORCE_THREAD_SAFE
private static final java.lang.String LOG_TAG
private org.apache.velocity.app.VelocityEngine engine
private org.apache.velocity.context.Context context
private int parseDepth
private boolean catchExceptions
private boolean forceThreadSafe
Constructor Detail |
---|
public RenderTool()
Method Detail |
---|
protected void configure(ValueParser parser)
configure
in class SafeConfig
public void setVelocityEngine(org.apache.velocity.app.VelocityEngine ve)
public void setParseDepth(int depth)
public void setVelocityContext(org.apache.velocity.context.Context context)
Context
to be used by the eval(String)
and recurse(String)
methods.
public int getParseDepth()
public void setCatchExceptions(boolean catchExceptions)
public boolean getCatchExceptions()
true
if this render() and eval() methods will
catch exceptions thrown during rendering.
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.
vtl
- the code to be evaluated
java.lang.Exception
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.
vtl
- the code to be evaluated
java.lang.Exception
eval(String)
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.
ctx
- the current Contextvtl
- the code to be evaluated
java.lang.Exception
protected java.lang.String internalEval(org.apache.velocity.context.Context ctx, java.lang.String vtl) throws java.lang.Exception
java.lang.Exception
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.
ctx
- the current Contextvtl
- the code to be evaluated
java.lang.Exception
protected java.lang.String internalRecurse(org.apache.velocity.context.Context ctx, java.lang.String vtl, int count) throws java.lang.Exception
java.lang.Exception
private void debug(java.lang.String message)
private void debug(java.lang.String message, java.lang.Throwable t)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |