Modified: velocity/site/production/engine/2.0/developer-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/developer-guide.html?rev=1834410&r1=1834409&r2=1834410&view=diff ============================================================================== --- velocity/site/production/engine/2.0/developer-guide.html (original) +++ velocity/site/production/engine/2.0/developer-guide.html Tue Jun 26 10:03:18 2018 @@ -345,45 +345,45 @@ h2:hover > .headerlink, h3:hover > .head <li>'Merge' the template and your data to produce the ouput.</li> </ol> <p>In code, using the singleton pattern via the <code>org.apache.velocity.app.Velocity</code> class, this looks like</p> -<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.io.StringWriter</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.VelocityContext</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.ResourceNotFoundException</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.ParseErrorException</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.MethodInvocationException</span><span class="p">;</span> +<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.io.StringWriter</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.VelocityContext</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.ResourceNotFoundException</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.ParseErrorException</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.exception.MethodInvocationException</span><span class="o">;</span> -<span class="n">Velocity</span><span class="o">.</span><span class="n">init</span><span class="p">();</span> +<span class="n">Velocity</span><span class="o">.</span><span class="na">init</span><span class="o">();</span> -<span class="n">VelocityContext</span> <span class="n">context</span> <span class="o">=</span> <span class="n">new</span> <span class="n">VelocityContext</span><span class="p">();</span> +<span class="n">VelocityContext</span> <span class="n">context</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityContext</span><span class="o">();</span> -<span class="n">context</span><span class="o">.</span><span class="n">put</span><span class="p">(</span> <span class="s2">"name"</span><span class="p">,</span> <span class="n">new</span> <span class="n">String</span><span class="p">(</span><span class="s2">"Velocity"</span><span class="p">)</span> <span class="p">);</span> +<span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span> <span class="s">"name"</span><span class="o">,</span> <span class="k">new</span> <span class="n">String</span><span class="o">(</span><span class="s">"Velocity"</span><span class="o">)</span> <span class="o">);</span> -<span class="n">Template</span> <span class="n">template</span> <span class="o">=</span> <span class="n">null</span><span class="p">;</span> +<span class="n">Template</span> <span class="n">template</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> <span class="k">try</span> -<span class="p">{</span> - <span class="n">template</span> <span class="o">=</span> <span class="n">Velocity</span><span class="o">.</span><span class="n">getTemplate</span><span class="p">(</span><span class="s2">"mytemplate.vm"</span><span class="p">);</span> -<span class="p">}</span> -<span class="n">catch</span><span class="p">(</span> <span class="n">ResourceNotFoundException</span> <span class="n">rnfe</span> <span class="p">)</span> -<span class="p">{</span> - <span class="o">//</span> <span class="n">couldn</span><span class="s1">'t find the template</span> -<span class="p">}</span> -<span class="n">catch</span><span class="p">(</span> <span class="n">ParseErrorException</span> <span class="n">pee</span> <span class="p">)</span> -<span class="p">{</span> - <span class="o">//</span> <span class="n">syntax</span> <span class="n">error</span><span class="p">:</span> <span class="n">problem</span> <span class="n">parsing</span> <span class="n">the</span> <span class="n">template</span> -<span class="p">}</span> -<span class="n">catch</span><span class="p">(</span> <span class="n">MethodInvocationException</span> <span class="n">mie</span> <span class="p">)</span> -<span class="p">{</span> - <span class="o">//</span> <span class="n">something</span> <span class="n">invoked</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">template</span> - <span class="o">//</span> <span class="n">threw</span> <span class="n">an</span> <span class="n">exception</span> -<span class="p">}</span> -<span class="n">catch</span><span class="p">(</span> <span class="ne">Exception</span> <span class="n">e</span> <span class="p">)</span> -<span class="p">{}</span> +<span class="o">{</span> + <span class="n">template</span> <span class="o">=</span> <span class="n">Velocity</span><span class="o">.</span><span class="na">getTemplate</span><span class="o">(</span><span class="s">"mytemplate.vm"</span><span class="o">);</span> +<span class="o">}</span> +<span class="k">catch</span><span class="o">(</span> <span class="n">ResourceNotFoundException</span> <span class="n">rnfe</span> <span class="o">)</span> +<span class="o">{</span> + <span class="c1">// couldn't find the template</span> +<span class="o">}</span> +<span class="k">catch</span><span class="o">(</span> <span class="n">ParseErrorException</span> <span class="n">pee</span> <span class="o">)</span> +<span class="o">{</span> + <span class="c1">// syntax error: problem parsing the template</span> +<span class="o">}</span> +<span class="k">catch</span><span class="o">(</span> <span class="n">MethodInvocationException</span> <span class="n">mie</span> <span class="o">)</span> +<span class="o">{</span> + <span class="c1">// something invoked in the template</span> + <span class="c1">// threw an exception</span> +<span class="o">}</span> +<span class="k">catch</span><span class="o">(</span> <span class="n">Exception</span> <span class="n">e</span> <span class="o">)</span> +<span class="o">{}</span> -<span class="n">StringWriter</span> <span class="n">sw</span> <span class="o">=</span> <span class="n">new</span> <span class="n">StringWriter</span><span class="p">();</span> +<span class="n">StringWriter</span> <span class="n">sw</span> <span class="o">=</span> <span class="k">new</span> <span class="n">StringWriter</span><span class="o">();</span> -<span class="n">template</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span> <span class="n">context</span><span class="p">,</span> <span class="n">sw</span> <span class="p">);</span> +<span class="n">template</span><span class="o">.</span><span class="na">merge</span><span class="o">(</span> <span class="n">context</span><span class="o">,</span> <span class="n">sw</span> <span class="o">);</span> </pre></div> @@ -392,60 +392,60 @@ h2:hover > .headerlink, h3:hover > .head <p>Developers have two options for using the Velocity engine, the singleton model and the separate instance model. The same core Velocity code is used for both approaches, which are provided to make Velocity easier to integrate into your Java application.</p> <h3 id="singleton-model">Singleton Model<a class="headerlink" href="#singleton-model" title="Permanent link">¶</a></h3> <p>This is the legacy pattern, where there is only one instance of the Velocity engine in the JVM (or web application, depending) that is shared by all. This is very convenient as it allows localized configuration and sharing of resources. For example, this is a very appropriate model for use in a Servlet 2.2+ compliant web application as each web application can have its own instance of Velocity, allowing that web application's servlet to share resources like templates, a logger, etc. The singleton is accessable via the <code>org.apache.velocity.app.Velocity</code> class, and and example of use:</p> -<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="p">;</span> +<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="o">;</span> <span class="o">...</span> -<span class="o">/*</span> - <span class="o">*</span> <span class="n">Configure</span> <span class="n">the</span> <span class="n">engine</span> - <span class="o">*/</span> - -<span class="n">Velocity</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span> - <span class="n">Velocity</span><span class="o">.</span><span class="n">RUNTIME_LOG_NAME</span><span class="p">,</span> <span class="s2">"mylog"</span><span class="p">);</span> - -<span class="o">/*</span> - <span class="o">*</span> <span class="n">now</span> <span class="n">initialize</span> <span class="n">the</span> <span class="n">engine</span> - <span class="o">*/</span> +<span class="cm">/*</span> +<span class="cm"> * Configure the engine</span> +<span class="cm"> */</span> + +<span class="n">Velocity</span><span class="o">.</span><span class="na">setProperty</span><span class="o">(</span> + <span class="n">Velocity</span><span class="o">.</span><span class="na">RUNTIME_LOG_NAME</span><span class="o">,</span> <span class="s">"mylog"</span><span class="o">);</span> + +<span class="cm">/*</span> +<span class="cm"> * now initialize the engine</span> +<span class="cm"> */</span> -<span class="n">Velocity</span><span class="o">.</span><span class="n">init</span><span class="p">();</span> +<span class="n">Velocity</span><span class="o">.</span><span class="na">init</span><span class="o">();</span> <span class="o">...</span> -<span class="n">Template</span> <span class="n">t</span> <span class="o">=</span> <span class="n">Velocity</span><span class="o">.</span><span class="n">getTemplate</span><span class="p">(</span><span class="s2">"foo.vm"</span><span class="p">);</span> +<span class="n">Template</span> <span class="n">t</span> <span class="o">=</span> <span class="n">Velocity</span><span class="o">.</span><span class="na">getTemplate</span><span class="o">(</span><span class="s">"foo.vm"</span><span class="o">);</span> </pre></div> <h3 id="separate-instance">Separate Instance<a class="headerlink" href="#separate-instance" title="Permanent link">¶</a></h3> <p>New in version 1.2, the separate instance allows you to create, configure and use as many instances of Velocity as you wish in the same JVM (or web application.) This is useful when you wish to support separate configurations, such as template directories, loggers, etc in the same application. To use separate instances, use the <code>org.apache.velocity.app.VelocityEngine</code> class. An example, which parallels the above singleton example, looks like:</p> -<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.velocity.app.VelocityEngine</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="p">;</span> +<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.velocity.app.VelocityEngine</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.Template</span><span class="o">;</span> <span class="o">...</span> -<span class="o">/*</span> - <span class="o">*</span> <span class="n">create</span> <span class="n">a</span> <span class="n">new</span> <span class="n">instance</span> <span class="n">of</span> <span class="n">the</span> <span class="n">engine</span> - <span class="o">*/</span> +<span class="cm">/*</span> +<span class="cm"> * create a new instance of the engine</span> +<span class="cm"> */</span> -<span class="n">VelocityEngine</span> <span class="n">ve</span> <span class="o">=</span> <span class="n">new</span> <span class="n">VelocityEngine</span><span class="p">();</span> +<span class="n">VelocityEngine</span> <span class="n">ve</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityEngine</span><span class="o">();</span> -<span class="o">/*</span> - <span class="o">*</span> <span class="n">configure</span> <span class="n">the</span> <span class="n">engine</span><span class="o">.</span> <span class="n">In</span> <span class="n">this</span> <span class="n">case</span><span class="p">,</span> <span class="n">we</span> <span class="n">are</span> <span class="n">using</span> - <span class="o">*</span> <span class="n">a</span> <span class="n">specific</span> <span class="n">logger</span> <span class="n">name</span> - <span class="o">*/</span> +<span class="cm">/*</span> +<span class="cm"> * configure the engine. In this case, we are using</span> +<span class="cm"> * a specific logger name</span> +<span class="cm"> */</span> -<span class="n">ve</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span> - <span class="n">VelocityEngine</span><span class="o">.</span><span class="n">RUNTIME_LOG_NAME</span><span class="p">,</span> <span class="s2">"mylog"</span><span class="p">);</span> +<span class="n">ve</span><span class="o">.</span><span class="na">setProperty</span><span class="o">(</span> + <span class="n">VelocityEngine</span><span class="o">.</span><span class="na">RUNTIME_LOG_NAME</span><span class="o">,</span> <span class="s">"mylog"</span><span class="o">);</span> -<span class="o">/*</span> - <span class="o">*</span> <span class="n">initialize</span> <span class="n">the</span> <span class="n">engine</span> - <span class="o">*/</span> +<span class="cm">/*</span> +<span class="cm"> * initialize the engine</span> +<span class="cm"> */</span> -<span class="n">ve</span><span class="o">.</span><span class="n">init</span><span class="p">();</span> +<span class="n">ve</span><span class="o">.</span><span class="na">init</span><span class="o">();</span> <span class="o">...</span> -<span class="n">Template</span> <span class="n">t</span> <span class="o">=</span> <span class="n">ve</span><span class="o">.</span><span class="n">getTemplate</span><span class="p">(</span><span class="s2">"foo.vm"</span><span class="p">);</span> +<span class="n">Template</span> <span class="n">t</span> <span class="o">=</span> <span class="n">ve</span><span class="o">.</span><span class="na">getTemplate</span><span class="o">(</span><span class="s">"foo.vm"</span><span class="o">);</span> </pre></div> @@ -458,8 +458,8 @@ h2:hover > .headerlink, h3:hover > .head <p>While Velocity allows you to create your own context classes to support special needs and techniques (like a context that accesses an LDAP server directly, for example), a good basic implementation class called VelocityContext is provided for you as part of the distribution.</p> <p>VelocityContext is suitable for all general purpose needs, and we strongly recommended that you use it. Only in exceptional and advanced cases will you need to extend or create your own context implementation.</p> <p>Using VelocityContext is as simple as using a normal Java Hashtable class. While the interface contains other useful methods, the two main methods you will use are</p> -<div class="codehilite"><pre>public Object put(String key, Object value); -public Object get(String key); +<div class="codehilite"><pre><span class="kd">public</span> <span class="n">Object</span> <span class="nf">put</span><span class="o">(</span><span class="n">String</span> <span class="n">key</span><span class="o">,</span> <span class="n">Object</span> <span class="n">value</span><span class="o">);</span> +<span class="kd">public</span> <span class="n">Object</span> <span class="nf">get</span><span class="o">(</span><span class="n">String</span> <span class="n">key</span><span class="o">);</span> </pre></div> @@ -475,16 +475,16 @@ public Object get(String key); + Any public class with a <code>public Iterator iterator()</code> method that never returns <code>null</code>. As a last resort, Velocity will look for an <code>iterator()</code> method. This provides great flexibility and automatic support for <code>java.util.Iterable</code> interface.</p> <p>In the case of the <code>Iterator</code> and <code>Enumeration</code>, it is recommended that they are placed in the context only when it cannot be avoided, and you should let Velocity find the appropriate reusable iterative interface when that is sufficient and possible.</p> <p>There are good reasons to use the <code>java.util.Iterator</code> interface directly (large data sets via JDBC, for example), but if it can be avoided, it might be better to use something else. By 'directly' , we meant doing something like:</p> -<div class="codehilite"><pre>Vector v = new Vector(); -v.addElement("Hello"); -v.addElement("There"); +<div class="codehilite"><pre><span class="n">Vector</span> <span class="n">v</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Vector</span><span class="o">();</span> +<span class="n">v</span><span class="o">.</span><span class="na">addElement</span><span class="o">(</span><span class="s">"Hello"</span><span class="o">);</span> +<span class="n">v</span><span class="o">.</span><span class="na">addElement</span><span class="o">(</span><span class="s">"There"</span><span class="o">);</span> -context.put("words", v.iterator() ); +<span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"words"</span><span class="o">,</span> <span class="n">v</span><span class="o">.</span><span class="na">iterator</span><span class="o">()</span> <span class="o">);</span> </pre></div> <p>where the Iterator itself is placed into the context. Instead, if you simply did:</p> -<div class="codehilite"><pre>context.put("words", v ); +<div class="codehilite"><pre><span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"words"</span><span class="o">,</span> <span class="n">v</span> <span class="o">);</span> </pre></div> @@ -492,7 +492,7 @@ context.put("words", v.iterato <p>This above isn't meant to give the impression that iterating over collections in Velocity is something that requires great care and thought. Rather, the opposite is true, in general. Just be careful when you place an Iterator into the context.</p> <h3 id="support-for-static-classes">Support for "Static Classes"<a class="headerlink" href="#support-for-static-classes" title="Permanent link">¶</a></h3> <p>Not all classes are instantiable. Classes like <code>java.lang.Math</code> do not provide any public constructor, and yet may contain useful static methods. In order to access these static methods from a template, you can simply add the class itself to the context:</p> -<div class="codehilite"><pre>context.put("Math", Math.class); +<div class="codehilite"><pre><span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"Math"</span><span class="o">,</span> <span class="n">Math</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> </pre></div> @@ -500,18 +500,18 @@ context.put("words", v.iterato <h3 id="context-chaining">Context Chaining<a class="headerlink" href="#context-chaining" title="Permanent link">¶</a></h3> <p>An innovative feature of Velocity's context design is the concept of <em>context chaining</em>. Also sometimes referred to as <em>context wrapping</em>, this advanced feature allows you to connect separate contexts together in a manner that makes it appear as one 'contiguous' context to the template.</p> <p>This is best illustrated by an example:</p> -<div class="codehilite"><pre>VelocityContext context1 = new VelocityContext(); +<div class="codehilite"><pre><span class="n">VelocityContext</span> <span class="n">context1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityContext</span><span class="o">();</span> -context1.put("name","Velocity"); -context1.put("project", "Jakarta"); -context1.put("duplicate", "I am in context1"); +<span class="n">context1</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"name"</span><span class="o">,</span><span class="s">"Velocity"</span><span class="o">);</span> +<span class="n">context1</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"project"</span><span class="o">,</span> <span class="s">"Jakarta"</span><span class="o">);</span> +<span class="n">context1</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"duplicate"</span><span class="o">,</span> <span class="s">"I am in context1"</span><span class="o">);</span> -VelocityContext context2 = new VelocityContext( context1 ); +<span class="n">VelocityContext</span> <span class="n">context2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityContext</span><span class="o">(</span> <span class="n">context1</span> <span class="o">);</span> -context2.put("lang", "Java" ); -context2.put("duplicate", "I am in context2"); +<span class="n">context2</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"lang"</span><span class="o">,</span> <span class="s">"Java"</span> <span class="o">);</span> +<span class="n">context2</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"duplicate"</span><span class="o">,</span> <span class="s">"I am in context2"</span><span class="o">);</span> -template.merge( context2, writer ); +<span class="n">template</span><span class="o">.</span><span class="na">merge</span><span class="o">(</span> <span class="n">context2</span><span class="o">,</span> <span class="n">writer</span> <span class="o">);</span> </pre></div> @@ -524,15 +524,15 @@ template.merge( context2, writer ); <h3 id="objects-created-in-the-template">Objects Created in the Template<a class="headerlink" href="#objects-created-in-the-template" title="Permanent link">¶</a></h3> <p>There are two common situations where the Java code must deal with objects created at runtime in the template:</p> <p>When a template author calls a method of an object placed into the context by Java code.</p> -<div class="codehilite"><pre>#set($myarr = ["a","b","c"] ) -$foo.bar( $myarr ) +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">myarr</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"a"</span><span class="p">,</span><span class="s2">"b"</span><span class="p">,</span><span class="s2">"c"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> +<span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="p">(</span> <span class="p">$</span><span class="nv">myarr</span> <span class="p">)</span><span class="x"></span> </pre></div> <p>When a template adds objects to the context, the Java code can access those objects after the merge process is complete.</p> -<div class="codehilite"><pre>#set($myarr = ["a","b","c"] ) -#set( $foo = 1 ) -#set( $bar = "bar") +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">myarr</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"a"</span><span class="p">,</span><span class="s2">"b"</span><span class="p">,</span><span class="s2">"c"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> +<span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">=</span> <span class="s2">"bar"</span><span class="p">)</span><span class="x"></span> </pre></div> @@ -562,14 +562,13 @@ $foo.bar( $myarr ) <h3 id="the-velocity-helper-class">The Velocity Helper Class<a class="headerlink" href="#the-velocity-helper-class" title="Permanent link">¶</a></h3> <p>Velocity contains an application utility class called Velocity ( <code>org.apache.velocity.app.Velocity</code> ). The purpose of this class is to provide the necessary methods required to initialize Velocity, as well as useful utility routines to make life easier in using Velocity. This class is documented in the project's javadoc, so please look there for definitive details. This documentation is intended to be of a tutorial nature; therefore for compete API information, the Javadoc is the definitive source.</p> <p>The Velocity runtime engine is a singleton instance that provides resource, logging and other services to all Velocity users running in the same JVM. Therefore, the runtime engine is initialized only once. You can attempt to initialize Velocity more than once, but only the first initialization will apply. The rest of the attempts will be ignored. The Velocity utility class currently provides five methods used in configuration of the runtime engine.</p> -<p>The five configuration methods are: -+ <code>setProperty( String key, Object o )</code></p> -<div class="codehilite"><pre>Sets the property `key` with the value `o`. The value is typically a String, but in special cases can also be a comma-separated list of values (in a single String, ex."foo, bar, woogie") as well as other things that will arise. -</pre></div> - - +<p>The five configuration methods are:</p> <ul> <li> +<p><code>setProperty( String key, Object o )</code></p> +<p>Sets the property <code>key</code> with the value <code>o</code>. The value is typically a String, but in special cases can also be a comma-separated list of values (in a single String, ex."foo, bar, woogie") as well as other things that will arise.</p> +</li> +<li> <p><code>Object getProperty( String key )</code></p> <p>Returns the value of the property key. Note that you must be aware of the type of the return value, as they can be things other than Strings.</p> </li> @@ -615,40 +614,40 @@ $foo.bar( $myarr ) </li> </ul> <p>Once we know about these basic helpers, it is easy to write a Java program that uses Velocity. Here it is:</p> -<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.io.StringWriter</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.VelocityContext</span><span class="p">;</span> +<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.io.StringWriter</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.Velocity</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.VelocityContext</span><span class="o">;</span> -<span class="n">public</span> <span class="k">class</span> <span class="nc">Example2</span> -<span class="p">{</span> - <span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span> <span class="n">String</span> <span class="n">args</span><span class="p">[]</span> <span class="p">)</span> - <span class="p">{</span> - <span class="o">/*</span> <span class="n">first</span><span class="p">,</span> <span class="n">we</span> <span class="n">init</span> <span class="n">the</span> <span class="n">runtime</span> <span class="n">engine</span><span class="o">.</span> <span class="n">Defaults</span> <span class="n">are</span> <span class="n">fine</span><span class="o">.</span> <span class="o">*/</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Example2</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span> <span class="n">String</span> <span class="n">args</span><span class="o">[]</span> <span class="o">)</span> + <span class="o">{</span> + <span class="cm">/* first, we init the runtime engine. Defaults are fine. */</span> - <span class="n">Velocity</span><span class="o">.</span><span class="n">init</span><span class="p">();</span> + <span class="n">Velocity</span><span class="o">.</span><span class="na">init</span><span class="o">();</span> - <span class="o">/*</span> <span class="n">lets</span> <span class="n">make</span> <span class="n">a</span> <span class="n">Context</span> <span class="ow">and</span> <span class="n">put</span> <span class="n">data</span> <span class="n">into</span> <span class="n">it</span> <span class="o">*/</span> + <span class="cm">/* lets make a Context and put data into it */</span> - <span class="n">VelocityContext</span> <span class="n">context</span> <span class="o">=</span> <span class="n">new</span> <span class="n">VelocityContext</span><span class="p">();</span> + <span class="n">VelocityContext</span> <span class="n">context</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityContext</span><span class="o">();</span> - <span class="n">context</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"Velocity"</span><span class="p">);</span> - <span class="n">context</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">"project"</span><span class="p">,</span> <span class="s2">"Jakarta"</span><span class="p">);</span> + <span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"name"</span><span class="o">,</span> <span class="s">"Velocity"</span><span class="o">);</span> + <span class="n">context</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"project"</span><span class="o">,</span> <span class="s">"Jakarta"</span><span class="o">);</span> - <span class="o">/*</span> <span class="n">lets</span> <span class="n">render</span> <span class="n">a</span> <span class="n">template</span> <span class="o">*/</span> + <span class="cm">/* lets render a template */</span> - <span class="n">StringWriter</span> <span class="n">w</span> <span class="o">=</span> <span class="n">new</span> <span class="n">StringWriter</span><span class="p">();</span> + <span class="n">StringWriter</span> <span class="n">w</span> <span class="o">=</span> <span class="k">new</span> <span class="n">StringWriter</span><span class="o">();</span> - <span class="n">Velocity</span><span class="o">.</span><span class="n">mergeTemplate</span><span class="p">(</span><span class="s2">"testtemplate.vm"</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">w</span> <span class="p">);</span> - <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s2">" template : "</span> <span class="o">+</span> <span class="n">w</span> <span class="p">);</span> + <span class="n">Velocity</span><span class="o">.</span><span class="na">mergeTemplate</span><span class="o">(</span><span class="s">"testtemplate.vm"</span><span class="o">,</span> <span class="n">context</span><span class="o">,</span> <span class="n">w</span> <span class="o">);</span> + <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">" template : "</span> <span class="o">+</span> <span class="n">w</span> <span class="o">);</span> - <span class="o">/*</span> <span class="n">lets</span> <span class="n">make</span> <span class="n">our</span> <span class="n">own</span> <span class="n">string</span> <span class="n">to</span> <span class="n">render</span> <span class="o">*/</span> + <span class="cm">/* lets make our own string to render */</span> - <span class="n">String</span> <span class="n">s</span> <span class="o">=</span> <span class="s2">"We are using $project $name to render this."</span><span class="p">;</span> - <span class="n">w</span> <span class="o">=</span> <span class="n">new</span> <span class="n">StringWriter</span><span class="p">();</span> - <span class="n">Velocity</span><span class="o">.</span><span class="n">evaluate</span><span class="p">(</span> <span class="n">context</span><span class="p">,</span> <span class="n">w</span><span class="p">,</span> <span class="s2">"mystring"</span><span class="p">,</span> <span class="n">s</span> <span class="p">);</span> - <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s2">" string : "</span> <span class="o">+</span> <span class="n">w</span> <span class="p">);</span> - <span class="p">}</span> -<span class="p">}</span> + <span class="n">String</span> <span class="n">s</span> <span class="o">=</span> <span class="s">"We are using $project $name to render this."</span><span class="o">;</span> + <span class="n">w</span> <span class="o">=</span> <span class="k">new</span> <span class="n">StringWriter</span><span class="o">();</span> + <span class="n">Velocity</span><span class="o">.</span><span class="na">evaluate</span><span class="o">(</span> <span class="n">context</span><span class="o">,</span> <span class="n">w</span><span class="o">,</span> <span class="s">"mystring"</span><span class="o">,</span> <span class="n">s</span> <span class="o">);</span> + <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">" string : "</span> <span class="o">+</span> <span class="n">w</span> <span class="o">);</span> + <span class="o">}</span> +<span class="o">}</span> </pre></div> @@ -660,7 +659,7 @@ $foo.bar( $myarr ) <p>where the template we used, testtemplate.vm, is</p> -<div class="codehilite"><pre>Hi! This $name from the $project project. +<div class="codehilite"><pre><span class="x">Hi! This </span><span class="p">$</span><span class="nv">name</span><span class="x"> from the </span><span class="p">$</span><span class="nv">project</span><span class="x"> project.</span> </pre></div> @@ -695,18 +694,18 @@ see the Javadoc API documentation.</p> <p>If we wanted to use a different directory than the current directory to load our template from, we could do something like this:</p> <div class="codehilite"><pre> <span class="o">...</span> -<span class="kn">import</span> <span class="nn">java.util.Properties</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">java.util.Properties</span><span class="o">;</span> <span class="o">...</span> -<span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span> <span class="n">String</span> <span class="n">args</span><span class="p">[]</span> <span class="p">)</span> -<span class="p">{</span> - <span class="o">/*</span> <span class="n">first</span><span class="p">,</span> <span class="n">we</span> <span class="n">init</span> <span class="n">the</span> <span class="n">runtime</span> <span class="n">engine</span><span class="o">.</span> <span class="o">*/</span> - - <span class="n">Properties</span> <span class="n">p</span> <span class="o">=</span> <span class="n">new</span> <span class="n">Properties</span><span class="p">();</span> - <span class="n">p</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s2">"file.resource.loader.path"</span><span class="p">,</span> <span class="s2">"/opt/templates"</span><span class="p">);</span> - <span class="n">Velocity</span><span class="o">.</span><span class="n">init</span><span class="p">(</span> <span class="n">p</span> <span class="p">);</span> +<span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span> <span class="n">String</span> <span class="n">args</span><span class="o">[]</span> <span class="o">)</span> +<span class="o">{</span> + <span class="cm">/* first, we init the runtime engine. */</span> + + <span class="n">Properties</span> <span class="n">p</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Properties</span><span class="o">();</span> + <span class="n">p</span><span class="o">.</span><span class="na">setProperty</span><span class="o">(</span><span class="s">"file.resource.loader.path"</span><span class="o">,</span> <span class="s">"/opt/templates"</span><span class="o">);</span> + <span class="n">Velocity</span><span class="o">.</span><span class="na">init</span><span class="o">(</span> <span class="n">p</span> <span class="o">);</span> - <span class="o">/*</span> <span class="n">lets</span> <span class="n">make</span> <span class="n">a</span> <span class="n">Context</span> <span class="ow">and</span> <span class="n">put</span> <span class="n">data</span> <span class="n">into</span> <span class="n">it</span> <span class="o">*/</span> + <span class="cm">/* lets make a Context and put data into it */</span> <span class="o">...</span> </pre></div> @@ -715,19 +714,19 @@ see the Javadoc API documentation.</p> <p>And the same if you want to use a VelocityEngine object rather than the singleton engine:</p> <div class="codehilite"><pre> <span class="o">...</span> -<span class="kn">import</span> <span class="nn">java.util.Properties</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">java.util.Properties</span><span class="o">;</span> <span class="o">...</span> -<span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="p">(</span> <span class="n">String</span> <span class="n">args</span><span class="p">[]</span> <span class="p">)</span> -<span class="p">{</span> - <span class="o">/*</span> <span class="n">first</span><span class="p">,</span> <span class="n">we</span> <span class="n">init</span> <span class="n">the</span> <span class="n">runtime</span> <span class="n">engine</span><span class="o">.</span> <span class="o">*/</span> - - <span class="n">Properties</span> <span class="n">p</span> <span class="o">=</span> <span class="n">new</span> <span class="n">Properties</span><span class="p">();</span> - <span class="n">p</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s2">"file.resource.loader.path"</span><span class="p">,</span> <span class="s2">"/opt/templates"</span><span class="p">);</span> - <span class="n">VelocityEngine</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">new</span> <span class="n">VelocityEngine</span><span class="p">();</span> - <span class="n">engine</span><span class="o">.</span><span class="n">init</span><span class="p">(</span> <span class="n">p</span> <span class="p">);</span> +<span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span> <span class="n">String</span> <span class="n">args</span><span class="o">[]</span> <span class="o">)</span> +<span class="o">{</span> + <span class="cm">/* first, we init the runtime engine. */</span> + + <span class="n">Properties</span> <span class="n">p</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Properties</span><span class="o">();</span> + <span class="n">p</span><span class="o">.</span><span class="na">setProperty</span><span class="o">(</span><span class="s">"file.resource.loader.path"</span><span class="o">,</span> <span class="s">"/opt/templates"</span><span class="o">);</span> + <span class="n">VelocityEngine</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityEngine</span><span class="o">();</span> + <span class="n">engine</span><span class="o">.</span><span class="na">init</span><span class="o">(</span> <span class="n">p</span> <span class="o">);</span> - <span class="o">/*</span> <span class="n">lets</span> <span class="n">make</span> <span class="n">a</span> <span class="n">Context</span> <span class="ow">and</span> <span class="n">put</span> <span class="n">data</span> <span class="n">into</span> <span class="n">it</span> <span class="o">*/</span> + <span class="cm">/* lets make a Context and put data into it */</span> <span class="o">...</span> </pre></div> @@ -1049,13 +1048,13 @@ see the Javadoc API documentation.</p> <p><em>Application Attributes</em> are name-value pairs that can be associated with a RuntimeInstance (either via the <code>VelocityEngine</code> or the <code>Velocity</code> singleton) and accessed from any part of the Velocity engine that has access to the RuntimeInstance.</p> <p>This feature was designed for applications that need to communicate between the application layer and custom parts of the Velocity engine, such as loggers, resource loaders, resource managers, etc.</p> <p>The Application Attribute API is very simple. From the application layer, there is a method of the <code>VelocityEngine</code> and the <code>Velocity</code> classes:</p> -<div class="codehilite"><pre>public void setApplicationAttribute( Object key, Object value ); +<div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">setApplicationAttribute</span><span class="o">(</span> <span class="n">Object</span> <span class="n">key</span><span class="o">,</span> <span class="n">Object</span> <span class="n">value</span> <span class="o">);</span> </pre></div> <p>through which an application can store on Object under an application (or internal component) specified key. There are no restrictions on the key or the value. The value for a key may be set at any time - it is not required that this be set before init() is called.</p> <p>Internal components can access the key-value pairs if they have access to the object via the <code>RuntimeServices</code> interface, using the method</p> -<div class="codehilite"><pre>public Object getApplicationAttribute( Object key ); +<div class="codehilite"><pre><span class="kd">public</span> <span class="n">Object</span> <span class="nf">getApplicationAttribute</span><span class="o">(</span> <span class="n">Object</span> <span class="n">key</span> <span class="o">);</span> </pre></div> @@ -1067,13 +1066,13 @@ see the Javadoc API documentation.</p> <h3 id="orgapachevelocityappeventincludeeventhandler"><code>org.apache.velocity.app.event.IncludeEventHandler</code><a class="headerlink" href="#orgapachevelocityappeventincludeeventhandler" title="Permanent link">¶</a></h3> <blockquote> <p>The <code>IncludeEventHandler</code> can be used to modify the template that is included in a page with <code>#include</code> or <code>#parse</code>. For example, this may be used to make all includes relative to the current directory or to prevent access to unauthorized resources. Multiple <code>IncludeEventHandler</code>'s may be chained, with the return value of the final call used as the name of the template to retrieve.</p> -<div class="codehilite"><pre>public IncludeEventHandler extends EventHandler -{ - public String includeEvent( Context context, - String includeResourcePath, - String currentResourcePath, - String directiveName ); -} +<div class="codehilite"><pre><span class="kd">public</span> <span class="n">IncludeEventHandler</span> <span class="kd">extends</span> <span class="n">EventHandler</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="n">String</span> <span class="nf">includeEvent</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">String</span> <span class="n">includeResourcePath</span><span class="o">,</span> + <span class="n">String</span> <span class="n">currentResourcePath</span><span class="o">,</span> + <span class="n">String</span> <span class="n">directiveName</span> <span class="o">);</span> +<span class="o">}</span> </pre></div> @@ -1086,25 +1085,25 @@ see the Javadoc API documentation.</p> <h3 id="orgapachevelocityappeventinvalidreferenceeventhandler"><code>org.apache.velocity.app.event.InvalidReferenceEventHandler</code><a class="headerlink" href="#orgapachevelocityappeventinvalidreferenceeventhandler" title="Permanent link">¶</a></h3> <blockquote> <p>Normally, when a template contains a bad reference an error message is logged and (unless it is part of a <code>#set</code> or <code>#if</code>), the reference is included verbatim in a page. With the <code>InvalidReferenceEventHandler</code> this behavior can be changed. Substitute values can be inserted, invalid references may be logged, or an exception can be thrown. Multiple <code>InvalidReferenceEventHandler</code>'s may be chained. The exact manner in which chained method calls behave will differ per method. (See the javadoc for the details).</p> -<div class="codehilite"><pre>public InvalidReferenceEventHandler extends EventHandler -{ - public Object invalidGetMethod( Context context, - String reference, - Object object, - String property, - Info info); - - public boolean invalidSetMethod( Context context, - String leftreference, - String rightreference, - Info info); - - public Object invalidMethod( Context context, - String reference, - Object object, - String method, - Info info); -} +<div class="codehilite"><pre><span class="kd">public</span> <span class="n">InvalidReferenceEventHandler</span> <span class="kd">extends</span> <span class="n">EventHandler</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="n">Object</span> <span class="nf">invalidGetMethod</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">String</span> <span class="n">reference</span><span class="o">,</span> + <span class="n">Object</span> <span class="n">object</span><span class="o">,</span> + <span class="n">String</span> <span class="n">property</span><span class="o">,</span> + <span class="n">Info</span> <span class="n">info</span><span class="o">);</span> + + <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">invalidSetMethod</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">String</span> <span class="n">leftreference</span><span class="o">,</span> + <span class="n">String</span> <span class="n">rightreference</span><span class="o">,</span> + <span class="n">Info</span> <span class="n">info</span><span class="o">);</span> + + <span class="kd">public</span> <span class="n">Object</span> <span class="nf">invalidMethod</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">String</span> <span class="n">reference</span><span class="o">,</span> + <span class="n">Object</span> <span class="n">object</span><span class="o">,</span> + <span class="n">String</span> <span class="n">method</span><span class="o">,</span> + <span class="n">Info</span> <span class="n">info</span><span class="o">);</span> +<span class="o">}</span> </pre></div> @@ -1116,14 +1115,14 @@ see the Javadoc API documentation.</p> <h3 id="orgapachevelocityappeventmethodexceptioneventhandler"><code>org.apache.velocity.app.event.MethodExceptionEventHandler</code><a class="headerlink" href="#orgapachevelocityappeventmethodexceptioneventhandler" title="Permanent link">¶</a></h3> <blockquote> <p>When a user-supplied method throws an exception, the <code>MethodExceptionEventHandler</code> is invoked with the Class, method name and thrown Exception. The handler can either return a valid Object to be used as the return value of the method call or throw the passed-in or new Exception, which will be wrapped and propogated to the user as a <code>MethodInvocationException</code>. While <code>MethodExceptionEventHandler</code>'s can be chained only the first handler is actually called -- all others are ignored.</p> -<div class="codehilite"><pre>public interface MethodExceptionEventHandler extends EventHandler -{ - public Object methodException( Context context, - Class claz, - String method, - Exception e ) - throws Exception; -} +<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">MethodExceptionEventHandler</span> <span class="kd">extends</span> <span class="n">EventHandler</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="n">Object</span> <span class="nf">methodException</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">Class</span> <span class="n">claz</span><span class="o">,</span> + <span class="n">String</span> <span class="n">method</span><span class="o">,</span> + <span class="n">Exception</span> <span class="n">e</span> <span class="o">)</span> + <span class="kd">throws</span> <span class="n">Exception</span><span class="o">;</span> +<span class="o">}</span> </pre></div> @@ -1135,12 +1134,12 @@ see the Javadoc API documentation.</p> <h3 id="orgapachevelocityappeventreferenceinsertioneventhandler"><code>org.apache.velocity.app.event.ReferenceInsertionEventHandler</code><a class="headerlink" href="#orgapachevelocityappeventreferenceinsertioneventhandler" title="Permanent link">¶</a></h3> <blockquote> <p>A <code>ReferenceInsertionEventHandler</code> allows the developer to intercept each write of a reference ($foo) value to the output stream and modify that output. Multiple <code>ReferenceInsertionEventHandler</code>'s may be chained with each step potentially altering the inserted reference.</p> -<div class="codehilite"><pre>public interface ReferenceInsertionEventHandler extends EventHandler -{ - public Object referenceInsert( Context context, - String reference, - Object value ); -} +<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">ReferenceInsertionEventHandler</span> <span class="kd">extends</span> <span class="n">EventHandler</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="n">Object</span> <span class="nf">referenceInsert</span><span class="o">(</span> <span class="n">Context</span> <span class="n">context</span><span class="o">,</span> + <span class="n">String</span> <span class="n">reference</span><span class="o">,</span> + <span class="n">Object</span> <span class="n">value</span> <span class="o">);</span> +<span class="o">}</span> </pre></div> @@ -1154,15 +1153,15 @@ see the Javadoc API documentation.</p> </blockquote> <h3 id="registering-event-handlers">Registering Event Handlers<a class="headerlink" href="#registering-event-handlers" title="Permanent link">¶</a></h3> <p>You may register event handlers in either of two manners. The easiest way to register event handlers is to specify them in velocity.properties. (Event handlers configured in this manner are referred to as "global" event handlers). For example, the following property will escape HTML entities in any inserted reference.</p> -<div class="codehilite"><pre>eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference +<div class="codehilite"><pre><span class="na">eventhandler.referenceinsertion.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.app.event.implement.EscapeHtmlReference</span> </pre></div> <p>Most event handler interfaces will also permit event handlers to be chained together. Such a chain may be in a comma separated list or as additional lines with a property/value pair. For example, the following event handler properties install two <code>ReferenceInsertionEventHandler</code>'s. The first will apply to references starting with "msg" (for example <code>$msgText</code>) and will escape HTML entities (e.g. turning <code>&</code> into <code>&amp;</code>). The second will escape all references starting with "sql" (for example <code>$sqlText</code>) according to SQL escaping rules. (note that in these examples, the first two properties given relate to the event handler configuration while the second two properties are used by the specific event handler implementation).</p> -<div class="codehilite"><pre>eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference -eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeSqlReference -eventhandler.escape.html.match = /msg.*/ -eventhandler.escape.sql.match = /sql.*/ +<div class="codehilite"><pre><span class="na">eventhandler.referenceinsertion.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.app.event.implement.EscapeHtmlReference</span> +<span class="na">eventhandler.referenceinsertion.class</span> <span class="o">=</span> <span class="s">org.apache.velocity.app.event.implement.EscapeSqlReference</span> +<span class="na">eventhandler.escape.html.match</span> <span class="o">=</span> <span class="s">/msg.*/</span> +<span class="na">eventhandler.escape.sql.match</span> <span class="o">=</span> <span class="s">/sql.*/</span> </pre></div> @@ -1170,43 +1169,43 @@ eventhandler.escape.sql.match = /sql.*/ <p>The following code shows how to register an event handler with an EventCartridge and a context.</p> <div class="codehilite"><pre> <span class="o">...</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.EventCartridge</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.ReferenceInsertionEventHandler</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.implement.EscapeHtmlReference</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.implement.EscapeSqlReference</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.EventCartridge</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.ReferenceInsertionEventHandler</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.implement.EscapeHtmlReference</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.app.event.implement.EscapeSqlReference</span><span class="o">;</span> <span class="o">...</span> -<span class="n">public</span> <span class="k">class</span> <span class="nc">Test</span> -<span class="p">{</span> - <span class="n">public</span> <span class="n">void</span> <span class="n">myTest</span><span class="p">()</span> - <span class="p">{</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Test</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="kt">void</span> <span class="nf">myTest</span><span class="o">()</span> + <span class="o">{</span> <span class="o">...</span> - <span class="o">/**</span> - <span class="o">*</span> <span class="n">Make</span> <span class="n">a</span> <span class="n">cartridge</span> <span class="n">to</span> <span class="n">hold</span> <span class="n">the</span> <span class="n">event</span> <span class="n">handlers</span> - <span class="o">*/</span> - <span class="n">EventCartridge</span> <span class="n">ec</span> <span class="o">=</span> <span class="n">new</span> <span class="n">EventCartridge</span><span class="p">();</span> - - <span class="o">/*</span> - <span class="o">*</span> <span class="n">then</span> <span class="n">register</span> <span class="ow">and</span> <span class="n">chain</span> <span class="n">two</span> <span class="n">escape</span><span class="o">-</span><span class="n">related</span> <span class="n">handlers</span> - <span class="o">*/</span> - <span class="n">ec</span><span class="o">.</span><span class="n">addEventHandler</span><span class="p">(</span><span class="n">new</span> <span class="n">EscapeHtmlReference</span><span class="p">());</span> - <span class="n">ec</span><span class="o">.</span><span class="n">addEventHandler</span><span class="p">(</span><span class="n">new</span> <span class="n">EscapeSqlReference</span><span class="p">());</span> - - <span class="o">/*</span> - <span class="o">*</span> <span class="ow">and</span> <span class="n">then</span> <span class="k">finally</span> <span class="n">let</span> <span class="n">it</span> <span class="n">attach</span> <span class="n">itself</span> <span class="n">to</span> <span class="n">the</span> <span class="n">context</span> - <span class="o">*/</span> - <span class="n">ec</span><span class="o">.</span><span class="n">attachToContext</span><span class="p">(</span> <span class="n">context</span> <span class="p">);</span> - - <span class="o">/*</span> - <span class="o">*</span> <span class="n">now</span> <span class="n">merge</span> <span class="n">your</span> <span class="n">template</span> <span class="k">with</span> <span class="n">the</span> <span class="n">context</span> <span class="k">as</span> <span class="n">you</span> <span class="n">normally</span> - <span class="o">*</span> <span class="n">do</span> - <span class="o">*/</span> + <span class="cm">/**</span> +<span class="cm"> * Make a cartridge to hold the event handlers </span> +<span class="cm"> */</span> + <span class="n">EventCartridge</span> <span class="n">ec</span> <span class="o">=</span> <span class="k">new</span> <span class="n">EventCartridge</span><span class="o">();</span> + + <span class="cm">/*</span> +<span class="cm"> * then register and chain two escape-related handlers </span> +<span class="cm"> */</span> + <span class="n">ec</span><span class="o">.</span><span class="na">addEventHandler</span><span class="o">(</span><span class="k">new</span> <span class="n">EscapeHtmlReference</span><span class="o">());</span> + <span class="n">ec</span><span class="o">.</span><span class="na">addEventHandler</span><span class="o">(</span><span class="k">new</span> <span class="n">EscapeSqlReference</span><span class="o">());</span> + + <span class="cm">/*</span> +<span class="cm"> * and then finally let it attach itself to the context</span> +<span class="cm"> */</span> + <span class="n">ec</span><span class="o">.</span><span class="na">attachToContext</span><span class="o">(</span> <span class="n">context</span> <span class="o">);</span> + + <span class="cm">/*</span> +<span class="cm"> * now merge your template with the context as you normally</span> +<span class="cm"> * do</span> +<span class="cm"> */</span> <span class="o">...</span> - <span class="p">}</span> -<span class="p">}</span> + <span class="o">}</span> +<span class="o">}</span> </pre></div> @@ -1573,29 +1572,29 @@ eventhandler.escape.sql.match = /sql.*/ <p>You can provide a custom conversion handler class by use of the <code>runtime.conversion.handler</code> property. The class must implement the <a href="apidocs/org/apache/velocity/util/introspection/ConversionHandler.html"><code>org.apache.Velocity.util.introspection.ConversionHandler</code></a> interface. Set it to <code>none</code> to only accept default Java conversions, as for Velocity 1.x.</p> <p>You can also provide custom <a href="apidocs/org/apache/velocity/util/introspection/Converter.html"><code>Converter<T></code></a> objects that handle a conversion towards a specific type:</p> -<div class="codehilite"><pre><span class="n">package</span> <span class="n">mypackage</span><span class="p">;</span> +<div class="codehilite"><pre><span class="kn">package</span> <span class="nn">mypackage</span><span class="o">;</span> -<span class="kn">import</span> <span class="nn">java.util.Date</span><span class="p">;</span> -<span class="kn">import</span> <span class="nn">org.apache.velocity.util.introspection.</span><span class="o">*</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">java.util.Date</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">org.apache.velocity.util.introspection.*</span><span class="o">;</span> -<span class="n">public</span> <span class="k">class</span> <span class="nc">MyUberspector</span> <span class="n">extends</span> <span class="n">UberspectorImpl</span> -<span class="p">{</span> - <span class="n">public</span> <span class="n">void</span> <span class="n">init</span><span class="p">()</span> - <span class="p">{</span> - <span class="nb">super</span><span class="o">.</span><span class="n">init</span><span class="p">();</span> - <span class="n">getConversionHandler</span><span class="p">()</span><span class="o">.</span><span class="n">addConverter</span><span class="p">(</span><span class="n">Integer</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">Date</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">new</span> <span class="n">ConvertToDate</span><span class="p">());</span> - <span class="n">getConversionHandler</span><span class="p">()</span><span class="o">.</span><span class="n">addConverter</span><span class="p">(</span><span class="n">Long</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">Date</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">new</span> <span class="n">ConvertToDate</span><span class="p">());</span> - <span class="p">}</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyUberspector</span> <span class="kd">extends</span> <span class="n">UberspectorImpl</span> +<span class="o">{</span> + <span class="kd">public</span> <span class="kt">void</span> <span class="nf">init</span><span class="o">()</span> + <span class="o">{</span> + <span class="kd">super</span><span class="o">.</span><span class="na">init</span><span class="o">();</span> + <span class="n">getConversionHandler</span><span class="o">().</span><span class="na">addConverter</span><span class="o">(</span><span class="n">Integer</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">Date</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="k">new</span> <span class="n">ConvertToDate</span><span class="o">());</span> + <span class="n">getConversionHandler</span><span class="o">().</span><span class="na">addConverter</span><span class="o">(</span><span class="n">Long</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">Date</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="k">new</span> <span class="n">ConvertToDate</span><span class="o">());</span> + <span class="o">}</span> - <span class="n">public</span> <span class="n">static</span> <span class="k">class</span> <span class="nc">ConvertToDate</span> <span class="n">extends</span> <span class="n">Converter</span><span class="o"><</span><span class="n">Date</span><span class="o">></span> - <span class="p">{</span> + <span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">ConvertToDate</span> <span class="kd">extends</span> <span class="n">Converter</span><span class="o"><</span><span class="n">Date</span><span class="o">></span> + <span class="o">{</span> <span class="nd">@Override</span> - <span class="n">public</span> <span class="n">Date</span> <span class="n">convert</span><span class="p">(</span><span class="n">Object</span> <span class="n">o</span><span class="p">)</span> - <span class="p">{</span> - <span class="k">return</span> <span class="n">new</span> <span class="n">Date</span><span class="p">(((</span><span class="n">Number</span><span class="p">)</span><span class="n">o</span><span class="p">)</span><span class="o">.</span><span class="n">longValue</span><span class="p">());</span> - <span class="p">}</span> - <span class="p">}</span> -<span class="p">}</span> + <span class="kd">public</span> <span class="n">Date</span> <span class="nf">convert</span><span class="o">(</span><span class="n">Object</span> <span class="n">o</span><span class="o">)</span> + <span class="o">{</span> + <span class="k">return</span> <span class="k">new</span> <span class="n">Date</span><span class="o">(((</span><span class="n">Number</span><span class="o">)</span><span class="n">o</span><span class="o">).</span><span class="na">longValue</span><span class="o">());</span> + <span class="o">}</span> + <span class="o">}</span> +<span class="o">}</span> </pre></div> @@ -1622,36 +1621,35 @@ eventhandler.escape.sql.match = /sql.*/ <p>Now make a little Java program that includes code similar to:</p> -<div class="codehilite"><pre><div class="source"><pre> -... +<div class="codehilite"><pre><span class="o">...</span> -SAXBuilder builder; -Document root = null; +<span class="n">SAXBuilder</span> <span class="n">builder</span><span class="o">;</span> +<span class="n">Document</span> <span class="n">root</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> -try -{ - builder = new SAXBuilder( - "org.apache.xerces.parsers.SAXParser" ); - root = builder.build("test.xml"); -} -catch( Exception ee) -{} +<span class="k">try</span> +<span class="o">{</span> + <span class="n">builder</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SAXBuilder</span><span class="o">(</span> + <span class="s">"org.apache.xerces.parsers.SAXParser"</span> <span class="o">);</span> + <span class="n">root</span> <span class="o">=</span> <span class="n">builder</span><span class="o">.</span><span class="na">build</span><span class="o">(</span><span class="s">"test.xml"</span><span class="o">);</span> +<span class="o">}</span> +<span class="k">catch</span><span class="o">(</span> <span class="n">Exception</span> <span class="n">ee</span><span class="o">)</span> +<span class="o">{}</span> -VelocityContext vc = new VelocityContext(); -vc.put("root", root.getRootElement()); +<span class="n">VelocityContext</span> <span class="n">vc</span> <span class="o">=</span> <span class="k">new</span> <span class="n">VelocityContext</span><span class="o">();</span> +<span class="n">vc</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"root"</span><span class="o">,</span> <span class="n">root</span><span class="o">.</span><span class="na">getRootElement</span><span class="o">());</span> -... +<span class="o">...</span> </pre></div> <p>Now, make a regular Velocity template:</p> -<div class="codehilite"><pre><span class="nt"><html></span> - <span class="nt"><body></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">html</span><span class="p">></span> + <span class="p"><</span><span class="nt">body</span><span class="p">></span> The document title is - $root.getChild("document").getChild("properties") + <span class="p">$</span><span class="nv">root</span><span class="p">.</span><span class="nv">getChild</span><span class="p">(</span><span class="s2">"document"</span><span class="p">).</span><span class="nv">getChild</span><span class="p">(</span><span class="s2">"properties"</span><span class="p">)</span> .getChild("title").getText() - <span class="nt"></body></span> + <span class="p"></</span><span class="nt">body</span><span class="p">></span> </pre></div> @@ -1666,30 +1664,30 @@ vc.put("root", root.getRootEle <span class="cp">##</span><span class="c"> and use it as</span> <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">sometext</span> <span class="o">=</span> <span class="s2">" < "</span> <span class="p">)</span> -<span class="nt"><text></span><span class="cp">#</span><span class="nf">xenc</span><span class="p">($</span><span class="nv">sometext</span><span class="p">)</span><span class="nt"></text></span> +<span class="p"><</span><span class="nt">text</span><span class="p">></span><span class="cp">#</span><span class="nf">xenc</span><span class="p">($</span><span class="nv">sometext</span><span class="p">)</</span><span class="nt">text</span><span class="p">></span> </pre></div> <p>where the escapeEntities() is a method that does the escaping for you. Another trick would be to create an encoding utility that takes the context as a constructor parameter and only implements a method:</p> -<div class="codehilite"><pre>public String get(String key) -{ - Object obj = context.get(key) - return (obj != null) - ? Escape.getText( obj.toString() ) - : ""; -} +<div class="codehilite"><pre><span class="kd">public</span> <span class="n">String</span> <span class="nf">get</span><span class="o">(</span><span class="n">String</span> <span class="n">key</span><span class="o">)</span> +<span class="o">{</span> + <span class="n">Object</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">key</span><span class="o">)</span> + <span class="k">return</span> <span class="o">(</span><span class="n">obj</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> + <span class="o">?</span> <span class="n">Escape</span><span class="o">.</span><span class="na">getText</span><span class="o">(</span> <span class="n">obj</span><span class="o">.</span><span class="na">toString</span><span class="o">()</span> <span class="o">)</span> + <span class="o">:</span> <span class="s">""</span><span class="o">;</span> +<span class="o">}</span> </pre></div> <p>Put it into the context as "xenc". Then you can use it as:</p> -<div class="codehilite"><pre><span class="nt"><text></span>$xenc.sometext<span class="nt"></text></span> +<div class="codehilite"><pre><span class="p"><</span><span class="nt">text</span><span class="p">>$</span><span class="nv">xenc</span><span class="p">.</span><span class="nv">sometext</span><span class="p"></</span><span class="nt">text</span><span class="p">></span> </pre></div> <p>This takes advantage of Velocity's introspection process - it will try to call get("sometext") on the $xenc object in the Context - then the xenc object can then get the value from the Context, encode it, and return it.</p> <p>Alternatively, since Velocity makes it easy to implement custom Context objects, you could implement your own context which always applies the encoding to any string returned. Be careful to avoid rendering the output of method calls directly, as they could return objects or strings (which might need encoding). Place them first into the context with a #set() directive and the use that, for example:</p> -<div class="codehilite"><pre>#set( $sometext = $jdomElement.getText() ) -<span class="nt"><text></span>$sometext<span class="nt"></text></span> +<div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">sometext</span> <span class="o">=</span> <span class="p">$</span><span class="nv">jdomElement</span><span class="p">.</span><span class="nv">getText</span><span class="p">()</span> <span class="p">)</span> +<span class="p"><</span><span class="nt">text</span><span class="p">>$</span><span class="nv">sometext</span><span class="p"></</span><span class="nt">text</span><span class="p">></span> </pre></div> @@ -1698,18 +1696,17 @@ vc.put("root", root.getRootEle <p>Velocity can be integrated into the Java Scripting Language Framework (as defined by the <a href="https://www.jcp.org/en/jsr/detail?id=223";>JSR-223 API</a>).</p> <p>This section is a brief illustration of how to use Velocity Scripting framework through the JSR-223 API.</p> <p>Hello World example:</p> -<div class="codehilite"><pre>// get script manager, create a new Velocity script engine factory and get an engine from it -ScriptEngineManager manager = new ScriptEngineManager(); -manager.registerEngineName("velocity", new VelocityScriptEngineFactory()); -ScriptEngine engine = manager.getEngineByName("velocity"); - - -System.setProperty(VelocityScriptEngine.VELOCITY_PROPERTIES, "path/to/velocity.properties"); -String script = "Hello $world"; -Writer writer = new StringWriter(); -engine.getContext().setWriter(writer); -Object result = engine.eval(script); -System.out.println(writer); +<div class="codehilite"><pre><span class="c1">// get script manager, create a new Velocity script engine factory and get an engine from it</span> +<span class="n">ScriptEngineManager</span> <span class="n">manager</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ScriptEngineManager</span><span class="o">();</span> +<span class="n">manager</span><span class="o">.</span><span class="na">registerEngineName</span><span class="o">(</span><span class="s">"velocity"</span><span class="o">,</span> <span class="k">new</span> <span class="n">VelocityScriptEngineFactory</span><span class="o">());</span> +<span class="n">ScriptEngine</span> <span class="n">engine</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="na">getEngineByName</span><span class="o">(</span><span class="s">"velocity"</span><span class="o">);</span> + +<span class="n">System</span><span class="o">.</span><span class="na">setProperty</span><span class="o">(</span><span class="n">VelocityScriptEngine</span><span class="o">.</span><span class="na">VELOCITY_PROPERTIES</span><span class="o">,</span> <span class="s">"path/to/velocity.properties"</span><span class="o">);</span> +<span class="n">String</span> <span class="n">script</span> <span class="o">=</span> <span class="s">"Hello $world"</span><span class="o">;</span> +<span class="n">Writer</span> <span class="n">writer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">StringWriter</span><span class="o">();</span> +<span class="n">engine</span><span class="o">.</span><span class="na">getContext</span><span class="o">().</span><span class="na">setWriter</span><span class="o">(</span><span class="n">writer</span><span class="o">);</span> +<span class="n">Object</span> <span class="n">result</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="na">eval</span><span class="o">(</span><span class="n">script</span><span class="o">);</span> +<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">writer</span><span class="o">);</span> </pre></div>
Modified: velocity/site/production/engine/2.0/source-repository.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/source-repository.html?rev=1834410&r1=1834409&r2=1834410&view=diff ============================================================================== --- velocity/site/production/engine/2.0/source-repository.html (original) +++ velocity/site/production/engine/2.0/source-repository.html Tue Jun 26 10:03:18 2018 @@ -256,7 +256,7 @@ h2:hover > .headerlink, h3:hover > .head <p>The Subversion client can go through a proxy, if you configure it to do so. First, edit your "servers" configuration file to indicate which proxy to use. The file's location depends on your operating system. On Linux or Unix it is located in the directory "~/.subversion". On Windows it is in "%APPDATA%\Subversion". (Try "echo %APPDATA%", note this is a hidden directory.)</p> <p>There are comments in the file explaining what to do. If you don't have that file, get the latest Subversion client and run any command; this will cause the configuration directory and template files to be created.</p> <p>Example: Edit the 'servers' file and add something like:</p> -<div class="codehilite"><pre><span class="k">[global]</span> +<div class="codehilite"><pre><span class="err">[global]</span> <span class="na">http-proxy-host</span> <span class="o">=</span> <span class="s">your.proxy.name</span> <span class="na">http-proxy-port</span> <span class="o">=</span> <span class="s">3128</span> </pre></div></div></div>
