velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nbu...@apache.org
Subject svn commit: r628994 - in /velocity/tools/trunk: examples/showcase/ src/main/java/org/apache/velocity/tools/generic/ src/main/java/org/apache/velocity/tools/view/ src/main/java/org/apache/velocity/tools/view/tools/
Date Tue, 19 Feb 2008 05:39:15 GMT
Author: nbubna
Date: Mon Feb 18 21:38:59 2008
New Revision: 628994

URL: http://svn.apache.org/viewvc?rev=628994&view=rev
Log:
given the flexibility of the core tool management infrastructure, we can now move ViewRenderTool's
abilities (and more) into RenderTool

Modified:
    velocity/tools/trunk/examples/showcase/render.vm
    velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/RenderTool.java
    velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml
    velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools.xml
    velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools/ViewRenderTool.java

Modified: velocity/tools/trunk/examples/showcase/render.vm
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/examples/showcase/render.vm?rev=628994&r1=628993&r2=628994&view=diff
==============================================================================
--- velocity/tools/trunk/examples/showcase/render.vm (original)
+++ velocity/tools/trunk/examples/showcase/render.vm Mon Feb 18 21:38:59 2008
@@ -17,7 +17,7 @@
 #title( 'ViewRenderTool' )
 <p>
 #set( $demo = $text.demo )
-$demo.thisPage.insert("#doclink( 'ViewRenderTool' false )").
+$demo.thisPage.insert("#doclink( 'RenderTool' true )").
 </p>
 
 #demoTableStart()

Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/RenderTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/RenderTool.java?rev=628994&r1=628993&r2=628994&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/RenderTool.java (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/RenderTool.java Mon
Feb 18 21:38:59 2008
@@ -20,21 +20,18 @@
  */
 
 import java.io.StringWriter;
+import org.apache.velocity.VelocityContext;
 import org.apache.velocity.app.Velocity;
 import org.apache.velocity.app.VelocityEngine;
 import org.apache.velocity.context.Context;
+import org.apache.velocity.tools.Scope;
 import org.apache.velocity.tools.config.DefaultKey;
 
 /**
  * This tool exposes methods to evaluate the given
  * strings as VTL (Velocity Template Language)
- * using the given context.
- * <p>
- *   NOTE: These examples assume you have placed an
- *   instance of the current context within itself
- *   as 'ctx'. And, of course, the RenderTool is
- *   assumed to be available as 'render'.
- * </p>
+ * using either a pre-configured context or one you
+ * provide directly.
  * <pre>
  * Example of eval():
  *      Input
@@ -42,7 +39,7 @@
  *      #set( $list = [1,2,3] )
  *      #set( $object = '$list' )
  *      #set( $method = 'size()' )
- *      $render.eval($ctx, "${object}.$method")
+ *      $render.eval("${object}.$method")
  *
  *      Output
  *      ------
@@ -54,7 +51,7 @@
  *      #macro( say_hi )hello world!#end
  *      #set( $foo = '#say_hi()' )
  *      #set( $bar = '$foo' )
- *      $render.recurse($ctx, $bar)
+ *      $render.recurse($bar)
  *
  *      Output
  *      ------
@@ -63,8 +60,10 @@
  *
  * Toolbox configuration:
  * &lt;tools&gt;
- *   &lt;toolbox scope="application"&gt;
- *     &lt;tool class="org.apache.velocity.tools.generic.RenderTool"/&gt;
+ *   &lt;toolbox scope="request"&gt;
+ *     &lt;tool class="org.apache.velocity.tools.generic.RenderTool"&gt;
+ *       &lt;property name="parseDepth" type="number" value="10"/&gt;
+ *     &lt;/tool&gt;
  *   &lt;/toolbox&gt;
  * &lt;/tools&gt;
  * </pre>
@@ -74,8 +73,27 @@
  * and we always tell them to write a tool.  Now we can just tell
  * them to use this tool.</p>
  *
- * <p>This tool is safe (and optimized) for use in the application
- * scope of a servlet environment.</p>
+ * <p>This tool may be used in any scope, however, the context provided
+ * for the {@link #eval(String)} and {@link #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'. </p>
+ *
+ * <p>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
+ * {@link #eval(Context,String)} and {@link #recurse(Context,String)}
+ * methods. :)</p>
+ *
+ * <p>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.</p>
  *
  * @author Nathan Bubna
  * @version $Revision$ $Date$
@@ -93,14 +111,19 @@
     @Deprecated
     public static final String KEY_CATCH_EXCEPTIONS = "catch.exceptions";
 
+    public static final String KEY_FORCE_THREAD_SAFE = "forceThreadSafe";
+
     private static final String LOG_TAG = "RenderTool.eval()";
 
     private VelocityEngine engine = null;
+    private Context context;
     private int parseDepth = DEFAULT_PARSE_DEPTH;
     private boolean catchExceptions = true;
+    private boolean forceThreadSafe = true;
 
     /**
-     * Looks for parse depth and catch.exceptions parameters.
+     * Looks for deprecated parse depth and catch.exceptions properties,
+     * as well as any 'forceThreadSafe' setting.
      */
     protected void configure(ValueParser parser)
     {
@@ -117,6 +140,15 @@
         {
             setCatchExceptions(catchEm);
         }
+
+        // check if they want thread-safety manually turned off
+        this.forceThreadSafe =
+            parser.getBoolean(KEY_FORCE_THREAD_SAFE, forceThreadSafe);
+        // if we're request-scoped, then there's no point in forcing the issue
+        if (Scope.REQUEST.equals(parser.getString("scope")))
+        {
+            this.forceThreadSafe = false;
+        }
     }
 
     /**
@@ -139,6 +171,30 @@
         {
             this.parseDepth = depth;
         }
+        else if (this.parseDepth != depth)
+        {
+            debug("RenderTool: Attempt was made to alter parse depth while config was locked.");
+        }
+    }
+
+    /**
+     * Sets the {@link Context} to be used by the {@link #eval(String)}
+     * and {@link #recurse(String)} methods.
+     */
+    public void setVelocityContext(Context context)
+    {
+        if (!isConfigLocked())
+        {
+            if (context == null)
+            {
+                throw new NullPointerException("context must not be null");
+            }
+            this.context = context;
+        }
+        else if (this.context != context)
+        {
+            debug("RenderTool: Attempt was made to set a new context while config was locked.");
+        }
     }
 
     /**
@@ -162,6 +218,10 @@
         {
             this.catchExceptions = catchExceptions;
         }
+        else if (this.catchExceptions != catchExceptions)
+        {
+            debug("RenderTool: Attempt was made to alter catchE while config was locked.");
+        }
     }
 
     /**
@@ -175,6 +235,44 @@
     }
 
     /**
+     * <p>Evaluates a String containing VTL using the context passed
+     * to the {@link #setVelocityContext} 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,
+     * <code>null</code> will be returned when this throws an exception.
+     * This evaluation is not recursive.</p>
+     *
+     * @param vtl the code to be evaluated
+     * @return the evaluated code as a String
+     */
+    public String eval(String vtl) throws Exception
+    {
+        Context ctx = forceThreadSafe ? new VelocityContext(context) : context;
+        return eval(ctx, vtl);
+    }
+
+
+    /**
+     * <p>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.</p>
+     *
+     * @see #eval(String)
+     * @param vtl the code to be evaluated
+     * @return the evaluated code as a String
+     */
+    public String recurse(String vtl) throws Exception
+    {
+        Context ctx = forceThreadSafe ? new VelocityContext(context) : context;
+        return recurse(ctx, vtl);
+    }
+
+    /**
      * <p>Evaluates a String containing VTL using the current context,
      * and returns the result as a String.  By default if this fails, then
      * <code>null</code> will be returned, though this tool can be configured
@@ -194,15 +292,7 @@
             }
             catch (Exception e)
             {
-                String msg = LOG_TAG + " threw Exception: " + e;
-                if (engine == null)
-                {
-                    Velocity.getLog().debug(msg);
-                }
-                else
-                {
-                    engine.getLog().debug(msg);
-                }
+                debug(LOG_TAG+" failed due to "+e, e);
                 return null;
             }
         }
@@ -214,7 +304,7 @@
 
 
     /* Internal implementation of the eval() method function. */
-    private String internalEval(Context ctx, String vtl) throws Exception
+    protected String internalEval(Context ctx, String vtl) throws Exception
     {
         if (vtl == null)
         {
@@ -272,10 +362,36 @@
             }
             else
             {
-                // abort and return what we have so far
-                //FIXME: notify the developer or user somehow??
+                // abort, log and return what we have so far
+                debug("RenderTool.recurse() exceeded the maximum parse depth of "
+                      + parseDepth + "on the following template: "+vtl);
                 return result;
             }
+        }
+    }
+
+    // internal convenience methods
+    private void debug(String message)
+    {
+        if (engine == null)
+        {
+            Velocity.getLog().debug(message);
+        }
+        else
+        {
+            engine.getLog().debug(message);
+        }
+    }
+
+    private void debug(String message, Throwable t)
+    {
+        if (engine == null)
+        {
+            Velocity.getLog().debug(message, t);
+        }
+        else
+        {
+            engine.getLog().debug(message, t);
         }
     }
 

Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml?rev=628994&r1=628993&r2=628994&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/generic/tools.xml Mon Feb
18 21:38:59 2008
@@ -40,6 +40,7 @@
     <toolbox scope="request">
         <tool class="org.apache.velocity.tools.generic.ContextTool"/>
         <tool class="org.apache.velocity.tools.generic.LoopTool"/>
+        <tool class="org.apache.velocity.tools.generic.RenderTool"/>
         <!-- 
         This is not useful in its default form.
         But, if it were, it'd be request-scoped.

Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools.xml?rev=628994&r1=628993&r2=628994&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools.xml (original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools.xml Mon Feb 18
21:38:59 2008
@@ -28,7 +28,6 @@
         <tool class="org.apache.velocity.tools.view.PagerTool"/>
         <tool class="org.apache.velocity.tools.view.ParameterTool"/>
         <tool class="org.apache.velocity.tools.view.ViewContextTool"/>
-        <tool class="org.apache.velocity.tools.view.ViewRenderTool"/>
         <tool class="org.apache.velocity.tools.view.ViewResourceTool"/>
         <!-- 
         This is not directly useable.

Modified: velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools/ViewRenderTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools/ViewRenderTool.java?rev=628994&r1=628993&r2=628994&view=diff
==============================================================================
--- velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools/ViewRenderTool.java
(original)
+++ velocity/tools/trunk/src/main/java/org/apache/velocity/tools/view/tools/ViewRenderTool.java
Mon Feb 18 21:38:59 2008
@@ -22,11 +22,11 @@
 import org.apache.velocity.context.Context;
 
 /**
- * Use {@link org.apache.velocity.tools.view.ViewRenderTool}
+ * Use {@link org.apache.velocity.tools.generic.RenderTool}
  */
 @Deprecated
 public class ViewRenderTool extends
-    org.apache.velocity.tools.view.ViewRenderTool
+    org.apache.velocity.tools.generic.RenderTool
 {
     @Deprecated
     public void init(Object obj)



Mime
View raw message