click-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From take...@apache.org
Subject svn commit: r797781 [2/3] - in /incubator/click/trunk/tools/eclipse/org.apache.click.eclipse: ./ documentation/ documentation/velocity/ documentation/velocity/images/
Date Sat, 25 Jul 2009 15:27:23 GMT
Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html?rev=797781&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html Sat Jul 25 15:27:17 2009
@@ -0,0 +1,3758 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Content Stylesheet for Site -->
+
+        
+<!-- start the processing -->
+    <!-- ====================================================================== -->
+    <!-- Main Page Section -->
+    <!-- ====================================================================== -->
+    <html>
+        <head>
+            <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+
+                                                    <meta name="author" value="Velocity Documentation Team">
+            <meta name="email" value="geirm@apache.org">
+            
+           
+                                    
+            <title>Velocity - Developer's Guide</title>
+            <style>
+              a:visited { color: blue; }
+              body	{ font-family: arial, helvetica, sans-serif; }
+            </style>
+        </head>
+
+        <body bgcolor="#ffffff" text="#000000" link="#525D76">        
+
+            <table border="0" width="100%" cellspacing="4">
+
+      <tr><td bgcolor="#525D76">&nbsp;
+        <font size="+2" color="#ffffff" face="arial,helvetica,sanserif">
+          <strong>Velocity Developers Guide</strong>
+        </font>
+      </td></tr>
+
+                <tr><td colspan="2">
+                    <hr noshade="" size="1"/>
+                </td></tr>                
+
+                <tr><td width="80%" align="left" valign="top">
+                                                                    <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Contents"><strong>Contents</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+<ol>
+
+<li>
+<a href="developer-guide.html#Introduction">Introduction and Getting Started</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Resources">Resources</a>
+</li>
+
+<li>
+<a href="developer-guide.html#How Velocity Works">How Velocity Works</a>
+<ul>
+ <li><a href="developer-guide.html#The Fundamental Pattern">The Fundamental Pattern</a></li>
+</ul>
+</li>
+
+<li>
+<a href="developer-guide.html#To Singleton Or Not To Singleton...">To Singleton Or Not To Singleton...</a>
+<ul>
+  <li><a href="developer-guide.html#Singleton">Singleton Model</a></li>
+  <li><a href="developer-guide.html#Separate">Separate Instance</a></li>
+</ul>
+</li>
+
+<li>
+<a href="developer-guide.html#The Context">The Context</a>
+<ul>
+<li><a href="developer-guide.html#The Basics">The Basics</a></li>
+<li><a href="developer-guide.html#Support for Iterative Objects for #foreach()">Support for Iterative Objects for #foreach()</a></li>
+<li><a href="developer-guide.html#Context Chaining">Context Chaining</a></li>
+<li><a href="developer-guide.html#Objects Created in the Template">Objects Created by the Template</a></li>
+<li><a href="developer-guide.html#Other Context Issues">Other Context Issues</a></li>
+</ul>
+</li>
+
+<li>
+<a href="developer-guide.html#Using Velocity In Servlets">Using Velocity in Servlets</a>
+<ul>
+<li><a href="developer-guide.html#Servlet Programming">Servlet Programming</a></li>
+<li><a href="developer-guide.html#Deployment">Deployment</a></li>
+</ul>
+</li>
+
+<li>
+<a href="developer-guide.html#Using Velocity In General Applications">Using Velocity in General Applications</a>
+<ul>
+<li><a href="developer-guide.html#The Velocity Helper Class">The Velocity Helper Class</a></li>
+<li><a href="developer-guide.html#Exceptions">Exceptions</a></li>
+<li><a href="developer-guide.html#Miscellaneous Details">Miscellaneous Details</a></li>
+</ul>
+</li>
+
+<li>
+  <a href="developer-guide.html#Application Attributes">Application Attributes</a>
+</li>
+
+<li>
+<a href="developer-guide.html#EventCartridge and Event Handlers">EventCartridge and Event Handlers</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Velocity Configuration Keys and Values">Velocity Configuration Keys and Values</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Configuring the Log System">Configuring the Log System</a>
+ <ul>
+  <li>
+    <a href="developer-guide.html#Using Log4j With Existing Category">Using Log4j With Existing Category</a>
+  </li>
+  <li>
+    <a href="developer-guide.html#Simple Example of a Custom Logger">Simple Example of a Custom Logger</a>
+  </li>
+ </ul>
+</li>
+
+<li>
+<a href="developer-guide.html#Configuring Resource Loaders">Configuring the Resource Loaders (template loaders)</a>
+<ul>
+  <li>
+    <a href="developer-guide.html#Resource Loaders">Resource Loaders</a>
+  </li>
+  <li>
+    <a href="developer-guide.html#Configuration Examples">Configuration Examples</a>
+  </li>
+  <li>
+    <a href="developer-guide.html#Resource Manager and Cache">Pluggable Resource Manager and Resource Cache</a>
+  </li>
+ </ul>
+</li>
+
+<li>
+<a href="developer-guide.html#Template Encoding for Internationalization">Template Encoding for Internationalization</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Velocity and XML">Velocity and XML</a>
+</li>
+
+<li>
+<a href="developer-guide.html#FAQ (Frequently Asked Questions)">FAQ (Frequently Asked Questions)</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Summary">Summary</a>
+</li>
+
+<li>
+<a href="developer-guide.html#Appendix 1 : Deploying the Example Servlet">Appendix 1 : Deploying the Example Servlet</a>
+<ul>
+  <li>
+    <a href="developer-guide.html#TomcatExample">Jakarta Tomcat</a>
+  </li>
+  <li>
+    <a href="developer-guide.html#ResinExample">Caucho Technology's Resin</a>
+  </li>
+  <li>
+    <a href="developer-guide.html#WebLogic">BEA WebLogic</a>
+  </li>
+ </ul>
+</li>
+
+</ol>
+</p>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Introduction"><strong>Introduction</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+Velocity is a Java-based template engine, a simple and powerful development tool
+that allows you to easily create and render documents that format and present
+your data. In this guide, we hope to give an overview of the basics of
+development using Velocity, focusing on the two main areas for Velocity usage :
+</p>
+                                                <ul>
+<li>servlet-based WWW development</li>
+<li>general application use</li>
+</ul>
+                                                <p>
+You will see that there is no real difference between these, other than we make
+servlet development with Velocity very easy if you use our provided class
+VelocityServlet as a base class for your servlet, and offer a utility class to
+help with application development.
+</p>
+                                                <p>
+<strong>Getting Started</strong>
+</p>
+                                                <p>
+While this information is found elsewhere on the Velocity site and in the
+documentation, it is included here for completeness. Getting Velocity running on
+your computer is very easy.  Note that all directory references are relative the
+root of the Velocity distribution tree.
+<ol>
+  <li>
+    Get the Velocity distribution. This is available as a release, nightly snapshot or
+    directly from the CVS code repository. Any are fine, although for the latest
+    features, the nightly snapshot is most likely the best way. For more
+    information, go <a href="index.html">here</a>.
+  </li>
+  <li>
+    If you don't have <a href="http://jakarta.apache.org/ant/">Jakarta Ant</a>,
+    the Java build tool already installed, please do so.  It is required for
+    building Velocity, although not required for <i>using</i> Velocity.
+  </li>
+  <li>
+    Go to the <code>build</code> directory in the distribution.
+  </li>
+  <li>
+    Type <code>ant &lt;build target&gt;</code> where &lt;build target&gt;
+    is one of:
+    <ul>
+      <li>
+        <b><code>jar</code></b> builds the complete Velocity jar in the
+        <code>bin</code> directory.  This jar will be called 'velocity-X.jar',
+        where 'X' is the current version number. This jar does not include
+        necessary dependencies for Velocity.  If you use this
+        target, you must get the Collections component jar from Jakarta Commons and add
+        to your CLASSPATH (or WEB-INF/lib).
+        If you wish to use the built-in logging or template conversion,
+        you must include the appropriate jars in your CLASSPATH or
+        webapp's WEB-INF/lib.
+        For convenience, you can use the <code>jar-dep</code> target to build
+        a jar with ORO, Logkit and Commons Collections included.
+      </li>
+      <li>
+        <b><code>jar-dep</code></b> builds the complete Velocity jar in
+        the <code>bin</code> directory, including necessary
+        support for logging from the
+        <a href="http://jakarta.apache.org/avalon/logkit/index.html">Jakarta
+        Avalon Logkit</a> package, critical configuration support from the
+        <a href="http://jakarta.apache.org/commons/">Jakarta Commons</a>
+        and the necesary support for WebMacro
+        template conversion using the
+        <a href="http://jakarta.apache.org/oro/index.html">Jakarta ORO</a>
+        package.
+       </li>
+       <li>
+        <b><code>jar-core</code></b> builds a slimmer Velocity jar in the
+        <code>bin</code> directory, called 'velocity-core-X.jar'. This jar
+        contains the core Velocity functionality, and doesn't include example
+        and utility things like Anakia, Texen or the VelocityServlet support
+        baseclass.  It has the same external dependency requirements as the
+        regular <code>jar</code> target.
+      </li>
+      <li>
+        <b><code>jar-util</code></b> builds a utility Velocity jar in the
+        <code>bin</code> directory, called 'velocity-util-X.jar'. This jar
+        contains utility code, specifically Anakia, Texen, and the WebMacro
+        template conversion utility. It has the same external dependency requirements as the
+        regular <code>jar</code> target.
+      </li>
+      <li>
+        <b><code>jar-servlet</code></b> builds a utility Velocity jar in the
+        <code>bin</code> directory, called 'velocity-servlet-X.jar'. This jar
+        contains utility code for servlet programmers. It has the same external dependency requirements as the
+        regular <code>jar</code> target.
+      </li>
+      <li>
+        <b><code>jar-J2EE</code></b> builds a complete jar, like the 'jar' target,
+        that includes any components that require J2EE support. Currently, this
+        includes only org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader.
+        As usual, it is placed in the  <code>bin</code> directory, called
+        'velocity-j2ee-X.jar'. NOTE : if you wish to use this build target, you
+        must place (or link) a copy of j2ee.jar into the build/lib directory.
+        We do not provide it as part of the distribution. A good source is
+        http://java.sun.com/.  It has the same external dependency requirements as the
+        regular <code>jar</code> target.
+      </li>
+      <li>
+        <b><code>jar-J2EE-dep</code></b> build a complete jar with J2EE support
+        and includes logging support from the Jakarta Avalon Logkit and
+        regexp support fromt the Jakarta ORO package. See the notes on the
+        <code>jar-dep</code> target, above.
+      </li>
+      <li>
+        <b><code>examples</code></b> builds the example code in the example programs
+        found in the <code>examples</code> directory. This build target will
+        also build the forumdemo example project.
+      </li>
+      <li>
+        <b><code>forumdemo</code></b> builds the example webapplication in the
+        <code>examples/forumdemo</code> directory.
+      </li>
+      <li>
+        <b><code>docs</code></b> builds these docs in the <code>docs</code> directory
+        using Velocity's <a href="anakia.html">Anakia</a> XML transformation tool.
+        Allowing you to use
+        Velocity templates in place of stylesheets
+        - give it a try!  <i>Note: This target requires that the jakarta-site2 project
+        is located as a peer directory to the jakarta-velocity distribution directory.
+        Please see the note in the build.xml file for this target for further information.</i>
+      </li>
+      <li>
+        <b><code>jar-src</code></b> bundles all the Velocity source code into a single
+        jar, placed in the <code>bin</code> directory.
+      </li>
+      <li>
+        <b><code>javadocs</code></b> builds the Javadoc class documentation in the
+        <code>docs/api</code> directory
+      </li>
+      <li>
+        <b><code>test</code></b> (after jar) will test Velocity against it's testbed
+        suite of test routines
+      </li>
+      <li>
+        <b><code>help</code></b> lists the build targets that are available.
+      </li>
+    </ul>
+  </li>
+  <li>
+    While not required, testing the build is a good idea. Use the
+    <code>test</code> target mentioned above.
+  </li>
+  <li>
+    That's it! Velocity is ready to be used. Put the jar into your classpath, or
+    into other appropriate places (such as the lib directory of your webapp if
+    using with servlets)
+  </li>
+  <li>
+    If you want to play with the examples, which is highly recommended when
+    getting started, use build the examples via
+    <code>ant examples</code>.
+  </li>
+</ol>
+</p>
+                                                <strong>Dependencies</strong>
+                                                <p>
+Velocity uses elements of the Java 2 API such as collections, and therefore
+building requires the Java 2 Standard Edition SDK (Software Development Kit).
+To run Velocity, the Java 2 Standard Edition RTE (Run Time Environment)
+is required (or you can use the SDK, of course).
+</p>
+                                                <p>
+Velocity also is dependent upon a few packages for general functionality.  They
+are included in the <code>build/lib</code> directory for convenience, but
+the default build target (see above) does not include them.  If you use the
+default build target, you must add the dependencies to your classpath.
+</p>
+                                                <ul>
+<li>
+  <a href="http://jakarta.apache.org/commons/">
+  <b>Jakarta Commons Collections</b></a> - required.
+</li>
+<li>
+  <a href="http://jakarta.apache.org/avalon/logkit/index.html">
+  <b>Jakarta Avalon Logkit</b></a> - optional, but very common.
+  Needed if using the default file-based logging in Velocity.
+</li>
+<li>
+  <a href="http://jakarta.apache.org/oro/index.html"><b>Jakarta ORO</b></a>
+   - optional.  Needed when using the
+   <code>org.apache.velocity.convert.WebMacro</code> template conversion
+   utility.
+ </li>
+</ul>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Resources"><strong>Resources</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+There are quite a few resources and examples available to the programmer, and we
+recommend that you look at our examples, documentation and even the source code.
+Some great sources are :
+</p>
+                                                <ul>
+  <li>
+     The user and developer community : join us via the
+     <a href="http://jakarta.apache.org/getinvolved/mail.html">mail-lists</a>.
+  </li>
+  <li>
+     Mail-list archives : <a href="http://www.mail-archive.com">
+    http://www.mail-archive.com</a> is a good one.  Type 'velocity' into the search
+    box to see both our -user and -dev archives.
+  </li>
+  <li>
+    source code : <code>src/java/...</code> : all the source code to the
+    Velocity project
+  </li>
+  <li>
+    application example 1 : <code>examples/app_example1</code> : a simple
+    example showing how to use Velocity in an application program.
+  </li>
+  <li>
+    application example 2 : <code>examples/app_example2</code> : a simple
+    example showing how to use Velocity in an application program using the
+    Velocity application utility class.
+  </li>
+  <li>
+    servlet example : <code>examples/servlet_example1</code> : a simple example
+    showing how to use Velocity in a servlet.
+  </li>
+  <li>
+    logger example : <code>examples/logger_example</code> : a simple example
+    showing how to create a custom logging class and register it with
+    Velocity to receive all log messages.
+  </li>
+  <li>
+    XML example : <code>examples/xmlapp_example</code> : a simple example
+    showing how to use JDOM to read and access XML document data from
+    within a Velocity template.  It also includes a demonstration of
+    a recursive Velocimacro that walks the document tree.
+  </li>
+ <li>
+    event example : <code>examples/event_example</code> : An example that
+    demonstrates the use of the event handling API in Velocity 1.1
+  </li>
+  <li>
+    Anakia application : <code>examples/anakia</code> : example application
+    showing how to use Velocity for creating stylesheet renderings of xml data
+  </li>
+  <li>
+    Forumdemo web app : <code>examples/forumdemo</code> : working example of a
+    simple servlet-based forum application
+  </li>
+  <li>
+    documentation : <code>docs</code> : all the generated documentation for the
+    Velocity project in html
+  </li>
+  <li>
+    API documentation : <code>docs/api</code> : the generated Javadoc
+    documentation for the Velocity project
+  </li>
+  <li>
+    templates : <code>test/templates</code> : a large collection of template
+    examples in our testbed directory, these are a great source of useage
+    examples of VTL, the Velocity Template Language
+  </li>
+  <li>
+    context example : <code>examples/context_example</code> : two examples
+    showing how the Velocity context can be extended. For advanced users.
+  </li>
+</ul>
+                                                <p>
+All directory references above are relative to the distribution root directory.
+</p>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="How Velocity Works"><strong>How Velocity Works</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+<a name="The Fundamental Pattern"><strong>'The Fundamental Pattern'</strong></a>
+</p>
+                                                <p>
+When using Velocity in an application program or in a servlet
+(or anywhere, actually), you will generally do the following :
+</p>
+                                                <ol>
+<li>Initialize Velocity. This applies to both usage patterns for Velocity,
+    the Singleton as well as the 'separate runtime instance' (see more on this
+    below), and you only do this once.</li>
+<li>Create a Context object (more on what that is later).</li>
+<li>Add your data objects to the Context.</li>
+<li>Choose a template.</li>
+<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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+import java.io.StringWriter;
+import org.apache.velocity.VelocityContext;
+import org.apache.velocity.Template;
+import org.apache.velocity.app.Velocity;
+import org.apache.velocity.exception.ResourceNotFoundException;
+import org.apache.velocity.exception.ParseErrorException;
+import org.apache.velocity.exception.MethodInvocationException;
+
+Velocity.init();
+
+VelocityContext context = new VelocityContext();
+
+context.put( &quot;name&quot;, new String(&quot;Velocity&quot;) );
+
+Template template = null;
+
+try
+{
+   template = Velocity.getTemplate(&quot;mytemplate.vm&quot;);
+}
+catch( ResourceNotFoundException rnfe )
+{
+   // couldn't find the template
+}
+catch( ParseErrorException pee )
+{
+  // syntax error : problem parsing the template
+}
+catch( MethodInvocationException mie )
+{
+  // something invoked in the template
+  // threw an exception
+}
+catch( Exception e )
+{}
+
+StringWriter sw = new StringWriter();
+
+template.merge( context, sw );
+
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+That's the basic pattern. It is very simple, isn't it?  This is generally what
+happens when you use Velocity to render a template. You probably won't be
+writing code exactly like this - we provide a few tools to help make it even
+easier than this for both servlet and application programmers.
+Later on in this guide, we will talk about using Velocity in both servlets
+as well as general applications, and we discuss the tools we provide to make
+things easier. In each case, though, the above sequence is what is happening
+either explicitly, or behind the scenes.
+</p>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="To Singleton Or Not To Singleton..."><strong>To Singleton Or Not To Singleton...</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+As of Velocity 1.2 and later, developers now 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>
+                                                <p>
+<a name="Singleton"><strong>Singleton Model</strong></a>
+</p>
+                                                <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 it's 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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+
+import org.apache.velocity.app.Velocity;
+import org.apache.velocity.Template;
+
+...
+
+/*
+ *  Configure the engine - as an example, we are using
+ *  ourselves as the logger - see logging examples
+ */
+
+Velocity.setProperty( Velocity.RUNTIME_LOG_LOGSYSTEM, this);
+
+/*
+ *  now initialize the engine
+ */
+
+Velocity.init();
+
+...
+
+Template t = Velocity.getTemplate(&quot;foo.vm&quot;);
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+Please note that the Singleton model is used in the
+<code>org.apache.velocity.servlet.VelocityServlet</code> base class,
+a utility class provided with the distribution to make writing servlets
+easier.  While extending this class is the most common and convenient
+way to write servlets using Velocity, you are free to not use this
+class if you needs require something different.
+</p>
+                                                <p>
+<a name="Separate"><strong>Separate Instance</strong></a>
+</p>
+                                                <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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+
+import org.apache.velocity.app.VelocityEngine;
+import org.apache.velocity.Template;
+
+...
+
+/*
+ *  create a new instance of the engine
+ */
+
+VelocityEngine ve = new VelocityEngine();
+
+/*
+ *  configure the engine.  In this case, we are using
+ *  ourselves as a logger (see logging examples..)
+ */
+
+ve.setProperty( VelocityEngine.RUNTIME_LOG_LOGSYSTEM, this);
+
+/*
+ *  initialize the engine
+ */
+
+ve.init();
+
+...
+
+Template t = ve.getTemplate(&quot;foo.vm&quot;);
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+As you can see, this is very simple and straightforward.  Except for some simple
+syntax changes, using Velocity as a singleton or as separate instances requires
+no changes to the high-level structure of your application or templates.
+</p>
+                                                <p>
+As a programmer, the classes you should use to interact with the Velocity
+internals are the <code>org.apache.velocity.app.Velocity</code> class if
+using the singleton model, or <code>org.apache.velocity.app.VelocityEngine</code>
+if using the non-singleton model ('separate instance').
+</p>
+                                                <p>
+At no time should an application use the internal <code>Runtime, RuntimeConstants,
+RuntimeSingleton or RuntimeInstance</code> classes in the
+<code>org.apache.velocity.runtime</code> package, as these are intended for
+internal use only and may change over time.  As mentioned above,
+the classes you should use
+are located in the <code>org.apache.velocity.app</code> package, and are the
+<code>Velocity</code> and <code>VelocityEngine</code> classes.  If anything is
+missing or needed from those classes, do not hesitate to suggest changes - these
+classes are intended for the application developer.
+</p>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="The Context"><strong>The Context</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <a name="The Basics"><strong>The Basics</strong></a>
+                                                <p>
+The concept of the 'context' is central to Velocity, and is a common technique
+for moving a container of data around between parts of a system. The idea is
+that the context is a 'carrier' of data between the Java layer (or you the
+programmer) and the template layer ( or the designer ). You as the programmer
+will gather objects of various types, whatever your application calls for, and
+place them in the context.  To the designer, these objects, and their methods
+and properties, will become accessable via template elements called
+<a href="vtl-reference-guide.html"> references</a>. Generally, you will work
+with the designer to determine the data needs for the application. In a sense,
+this will become an 'API'  as you produce a data set for the designer to access
+in the template.  Therefore, in this phase of  the development process it is
+worth devoting some time and careful analysis.
+</p>
+                                                <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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+public Object put(String key, Object value);
+public Object get(String key);
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+Please note that like a Hashtable, the value must be derived from
+java.lang.Object, and must not be null. Fundamental types like int or float must
+be wrapped in the appropriate wrapper classes.
+</p>
+                                                <p>
+That's really all there is to basic context operations. For more information,
+see the API documentation included in the distribution.
+</p>
+                                                <p>
+<a name="Support for Iterative Objects for #foreach()"><strong>Support for Iterative Objects for
+#foreach()</strong></a>
+</p>
+                                                <p>
+As a programmer, you have great freedom in the objects that you put into the
+context.  But as with most freedoms, this one comes with a little bit of
+responsibility, so understand what Velocity supports, and any issues that may
+arise.  Velocity supports serveral types of collection types  suitable for use
+in the VTL <code>#foreach()</code> directive.
+</p>
+                                                <ul>
+
+<li> <code>Object [] </code>  Regular object array, not much needs to be said
+here. Velocity will internally wrap your array in a class that provides an
+Iterator interface,  but that shouldn't concern you as the programmer, or the
+template author.
+</li>
+
+<li> <code>java.util.Collection</code>  Velocity will use the
+<code>iterator()</code> method to get an Iterator to use in the loop,
+so if you are implementing a Collection interface on your object, please
+ensure that <code>iterator()</code> returns a working  Iterator.
+</li>
+
+<li> <code>java.util.Map </code> Here, Velocity depends upon the
+<code>values()</code> method of the interface to get a <code>Collection</code>
+interface, on which <code>iterator()</code> is called to retrieve an Iterator
+for the loop.
+</li>
+
+<li> <code>java.util.Iterator</code> USE WITH CAUTION : This is currently
+supported only provisionally - the issue of concern is the
+'non-resettablity' of the Iterator.  If a 'naked' Iterator is placed into
+the context, and used in more than one #foreach(), subsequent #foreach()
+blocks after the first will fail, as the Iterator doesn't reset.
+</li>
+
+<li> <code>java.util.Enumeration</code> USE WITH CAUTION : Like
+<code>java.util.Iterator</code>, this is currently
+supported only provisionally - the issue of concern is the
+'non-resettablity' of the Enumeration.  If a 'naked' Enumeration
+is placed into the context, and used in more than one #foreach(),
+subsequent #foreach() blocks after the first will fail,
+as the Enumeration doesn't reset.
+</li>
+
+</ul>
+                                                <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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+Vector v = new Vector();
+v.addElement(&quot;Hello&quot;);
+v.addElement(&quot;There&quot;);
+
+context.put(&quot;words&quot;, v.iterator() );
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+where the Iterator itself is placed into the context. Instead, if you
+simply did:
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+context.put(&quot;words&quot;, v );
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+then all would be fine: Velocity would figure out that Vector implement
+Collection (via List), and therefore will find the <code>iterator()</code>
+method, and use that to get a 'fresh' Iterator for its use each time
+it needs to.  With just a plain Iterator (the first snippet above...),
+once velocity has used it in a <code>#foreach()</code>, Velocity has
+no way of getting a new one to use for the next <code>#foreach()</code>
+it is used in.  The result is no output from any subsequent
+<code>#foreach()</code> blocks using that reference.
+</p>
+                                                <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>
+                                                <a name="Context Chaining"><strong>Context Chaining</strong></a>
+                                                <p>
+An innovative feature of Velocity's context design is the concept
+of <i>context chaining</i>. Also sometimes referred to as
+<i>context wrapping</i>, 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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+VelocityContext context1 = new VelocityContext();
+
+context1.put(&quot;name&quot;,&quot;Velocity&quot;);
+context1.put(&quot;project&quot;, &quot;Jakarta&quot;);
+context1.put(&quot;duplicate&quot;, &quot;I am in context1&quot;);
+
+VelocityContext context2 = new VelocityContext( context1 );
+
+context2.put(&quot;lang&quot;, &quot;Java&quot; );
+context2.put(&quot;duplicate&quot;, &quot;I am in context2&quot;);
+
+template.merge( context2, writer );
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+In the code above, we have set up context2 such that it <i>chains</i>
+context1.  This means that in the template, you can access any of
+the items that were put into either of the two VelocityContext objects,
+as long as there is no duplication of the keys used to add objects.
+If that is the case, as it is above for the key 'duplicate', the object
+stored in the nearest context in the chain will be available.  In this
+example above, the object returned would
+be the string "I am in context2".
+</p>
+                                                <p>
+Note that this duplication, or 'covering', of a context item does not in
+any way harm or alter the covered object.  So in the example above, the
+string "I am in context1" is alive and well, still accessable via
+context1.get("duplicate").  But in the example above, the value of the
+reference '$duplicate' in the template would be 'I am in context2',
+and the template has no access to the covered string 'I am in context1'.
+</p>
+                                                <p>
+Note also that you have to be careful when you are relying on the template
+to add information to a context that you will examine later after the
+rendering.  The changes to the context via <code>#set()</code> statements
+in a template will affect only the outer context.  So make sure that you
+don't discard the outer context, expecting the data from the template to
+have been placed onto the inner one.
+</p>
+                                                <p>
+This feature has many uses, the most common so far is providing layered
+data access and toolsets.
+</p>
+                                                <p>
+As mentioned before, the Velocity context mechanism is also extendable,
+but beyond the current scope of this guide. If you are interested,
+please see the classes in the package <code>org.apache.velocity.context</code>
+to see how the provided contexts are put together.  Futher, there are a few
+examples in the <code>examples/context_example</code> directory in the
+distribution which show alternate implementations, including [a goofy] one
+that uses a database as the backing storage.
+</p>
+                                                <p>
+Please note that these examples are unsupported and are there for
+demonstration/educational purposes only.
+</p>
+                                                <a name="Objects Created in the Template"><strong>Objects Created in the
+Template</strong></a>
+                                                <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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+#set($myarr = [&quot;a&quot;,&quot;b&quot;,&quot;c&quot;] )
+$foo.bar( $myarr )
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </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 align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+#set($myarr = [&quot;a&quot;,&quot;b&quot;,&quot;c&quot;] )
+#set( $foo = 1 )
+#set( $bar = &quot;bar&quot;)
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+Dealing with these cases if very straighforward, as there are just a few
+things to know:
+</p>
+                                                <ul>
+    <li>
+    The VTL RangeOperator  [ 1..10 ]  and  ObjectArray ["a","b"] are
+    <code>java.util.ArrayList</code> objects when placed in the context
+    or passed to methods.   Therefore, your methods that are designed to
+    accept arrays created in the template should be written with this
+    in mind.
+    </li>
+    <li>
+    Numbers will be Integers in the context, and strings will be, of course, Strings.
+    </li>
+    <li>
+    Velocity will properly 'narrow' args to method calls, so calling
+    <code>setFoo( int i )</code> with an int placed into the
+    context via <code>#set()</code> will work fine.
+    </li>
+  </ul>
+                                                <a name="Other Context Issues"><strong>Other Context Issues</strong></a>
+                                                <p>
+One of the features provided by the VelocityContext
+(or any Context derived from AbstractContext) is
+node specific introspection caching.  Generally, you as a the developer
+don't need to worry about this when using the VelocityContext
+as your context.  However, there is currently one
+known usage pattern where you must be aware of this feature.
+</p>
+                                                <p>
+The VelocityContext will accumulate intropection information about the
+syntax nodes in a template as it visits those nodes.  So, in the following
+situation:
+</p>
+                                                <ul>
+<li>
+  You are iterating over the same template using the same VelocityContext
+  object.
+</li>
+<li>
+Template caching is off.
+</li>
+<li>
+You request the Template from getTemplate() on each iteration.
+</li>
+</ul>
+                                                <p>
+It is possible that your VelocityContext will appear to 'leak' memory
+(it is really just gathering more introspection information.)  What
+happens is that it accumulates template node introspection information
+for each template it visits, and as template caching is off, it appears
+to the VelocityContext that it is visiting a new template each time.
+Hence it gathers more introspection information and grows. It is highly
+recommended that you do one or more of the following :
+</p>
+                                                <ul>
+<li>Create a new VelocityContext for each excursion
+down through the template render process.   This will prevent the accumulation
+of introspection cache data.  For the case where you want to reuse the
+VelocityContext because it's populated with data or objects,
+ you can simply wrap the populated
+VelocityContext in another, and the 'outer' one will accumulate the
+introspection information, which you will just discard.  Ex.
+<code>VelocityContext useThis = new VelocityContext( populatedVC );</code>
+This works because the outer context will store the introspection
+cache data, and get any requested data from the inner context (as it is empty.)
+Be careful though - if your template places data into the context and it's
+expected that it will be used in the subsequent iterations, you will need to do
+one of the other fixes, as any template #set() statements will be stored in
+the outermost context. See the discussion in
+<a href="developer-guide.html#Context Chaining">Context chaining</a> for more
+information.
+</li>
+
+<li>
+Turn on template caching.  This will prevent the template from being re-parsed
+on each iteration, resulting the the VelocityContext being able to not only
+avoid adding to the introspection cache information, but be able to use it
+resulting in a performance improvement.
+</li>
+
+<li>
+Reuse the Template object for the duration of the loop iterations.
+Then you won't be forcing Velocity, if the cache is turned off, to
+reread and reparse the same template over and over, so the VelocityContext
+won't gather new introspection information each time.
+</li>
+</ul>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Using Velocity In Servlets"><strong>Using Velocity In Servlets</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <a name="Servlet Programming"><strong>Servlet Programming</strong></a>
+                                                <p>
+The most common use of Velocity is in the area of Java Servlet programming
+for the WWW.   There are many reasons why Velocity is well suited for this
+task, one of the primary ones is Velocity's enforcement of the
+separation of the presentation (or view) layer from the
+code layer.  There are many resources on this subject, including
+<a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">
+this</a>.
+</p>
+                                                <p>
+The basic technique of using Velocity in a servlet environment is very simple.
+In a nutshell, all you must do is extend the provided VelocityServlet base class
+and implement a single method, <code>handleRequest()</code>.  That's really all that is
+required to use Velocity in your servlet development.
+</p>
+                                                <p>
+As of Velocity 1.1, there are two <code>handleRequest()</code> methods :
+
+<br />
+<br />
+
+<i><code>public Template handleRequest( Context )</code></i>
+
+<blockquote>
+  This is the older of the two methods.  This method requires that you
+  return a valid Template object.  If not valid, or <code>null</code>,
+  this is considered an error condition, and will result in the <a href="developer-guide.html#error()"><code>error()</code></a> error
+  handling method being called.  You may override the
+  <code>error()</code> if you wish.  If returning a <code>null</code> is
+  something you expect to do (for example, you will want to redirect
+  requests) it is recommended that you use the newer method, listed
+  next.
+</blockquote>
+  <br />
+
+<i><code>public Template handleRequest( HttpServletRequest, HttpServletResponse, Context )</code></i>
+
+<blockquote>
+   This is the newer of the two <code>handleRequest()</code> methods,
+   implemented in version 1.1. The difference with this method is that
+   the <code>HttpServletRequest</code> and
+   <code>HttpServletResponse</code> objects are passed to you as
+   arguments to the method, as well as in the <code>Context</code>.  The
+   other difference is that this method can return <code>null</code> to
+   indicate that all processing has been handled by the method, and that
+   Velocity should do nothing further than call
+   <a href="developer-guide.html#requestCleanup()"><code>requestCleanup()</code></a>.
+   This is extremely useful is you wish to redirect the request, for
+   example.
+</blockquote>
+
+As always, please refer to the Javadoc API documentation for the definitive and
+latest notes.
+</p>
+                                                <p>
+The following code is similar to the SampleServlet.java class included
+in the distribution in the examples directory.
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+public class SampleServlet extends VelocityServlet
+{
+    public Template handleRequest( HttpServletRequest request,
+                                   HttpServletResponse response,
+                                   Context context )
+    {
+
+        String p1 = &quot;Jakarta&quot;;
+        String p2 = &quot;Velocity&quot;;
+
+        Vector vec = new Vector();
+        vec.addElement( p1 );
+        vec.addElement( p2 );
+
+        context.put(&quot;list&quot;, vec );
+
+        Template template = null;
+
+        try
+        {
+            template =  getTemplate(&quot;sample.vm&quot;);
+        }
+        catch( ResourceNotFoundException rnfe )
+        {
+          // couldn't find the template
+        }
+        catch( ParseErrorException pee )
+        {
+          // syntax error : problem parsing the template
+        }
+        catch( Exception e )
+        {}
+
+        return template;
+    }
+}
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+Look familiar?  With the exception of creating the context object, which is
+done for you by the VelocityServlet base class, and  the  merge() step
+which is also done for you by the VelocityServlet base class, it's identical
+to the basic code pattern we mentioned at the beginning of this guide.
+We take the context, add our application data, and return a template.
+</p>
+                                                <p>
+The default <code>Context</code> object that is passed into the
+<code>handleRequest()</code> methods contains both the current
+<code>HttpServletRequest</code> and <code>HttpServletResponse</code>
+objects.  They are placed in the context using the the constants
+<code>VelocityServlet.REQUEST</code> (value = 'req') and
+<code>VelocityServlet.RESPONSE</code> (value = 'res')
+respectively.  To access and use these objects in your Java code :
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+public Template handleRequest(  Context context )
+{
+    HttpServletRequest request =  (HttpServletRequest) context.get( REQUEST );
+    HttpServletResponse response =  (HttpServletResponse) context.get( RESPONSE );
+
+   ...
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+and in your templates:
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+#set($name = $req.getParameter('name') )
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+For more advanced uses,  the VelocityServlet base class allows you to override
+parts of the handling of the request processing.  The following methods may
+be overridden :
+<br />
+<br />
+
+<i><code> Properties loadConfiguration( ServletConfig )</code></i>
+<blockquote>
+  Allows you to override the normal configuration mechanism and add or
+  alter the configuation properties.  This is useful for overriding or
+  augmenting template and log paths, to set the absolute path into the
+  webapp root at runtime.
+</blockquote>
+
+<i><a name="createContext()">
+<code>Context createContext(HttpServletRequest, HttpServletResponse )</code></a></i>
+<blockquote>
+  Allows you to create the Context object yourself. This allows more advanced
+  techniques, such as chaining or pre-loading with tools or data.  The default
+  implementation simply returns a VelocityContext object with the request
+  and response objects placed inside.  The request and response objects are
+  wrapped in simple wrapper classes to avoid introspection problems that may
+  occurr in some servlet container implementations.  You can use the request
+  and repsponse objects normally, accessing methods of either from the
+  template.  Just note that they aren't specifically javax.servlet.XXXX
+  classes, if that is important to you.
+</blockquote>
+
+<i><code>void setContentType( HttpServletRequest,HttpServletResponse )</code></i>
+<blockquote>
+  Allows you to examine the request and set the content type yourself,
+  depending on the request or client.  The default implementation sets
+  the content type to be that either specified in the
+  velocity.properties, if any, or the default, "text/html" if not
+  specified in the properties.
+</blockquote>
+
+<i><code>void mergeTemplate( Template, Context, HttpServletResponse )</code></i>
+<blockquote>
+  Allows you to produce the output stream.  The VelocityServlet uses a
+  pool of very efficient Writer classes, so this would usually be
+  overridden in special situations.
+</blockquote>
+
+<i><a name="requestCleanup()"><code>void requestCleanup( HttpServletRequest,
+  HttpServletResponse , Context )</code></a></i>
+<blockquote>
+  Allows you to do any cleanup or resource reclamation at the end of the
+  request processing.  The default does nothing.
+</blockquote>
+
+<i><a name="error()"><code>protected void error( HttpServletRequest,
+  HttpServletResponse, Exception )</code></a></i>
+<blockquote>
+  Error handler that is called an exception occurrs in request
+  processing. Default implementation will send a simple HTML message
+  with stacktrace and exception information back to the user.  Override
+  for custom client messages and more advanced problem handling.
+</blockquote>
+
+For further information, please see the Javadoc API documentation.
+</p>
+                                                <a name="Deployment"><strong>Deployment</strong></a>
+                                                <p>
+When you deploy your Velocity-based servlets, you will certainly want to
+ensure that your properties file is used to configure the Velocity runtime.
+Under Tomcat, one way to accomplish this is by placing your velocity.properties
+file into the root directory of your web app (webapps/appname ) and then
+add the following to your WEB-INF/web.xml file :
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+&lt;servlet&gt;
+  &lt;servlet-name&gt;MyServlet&lt;/servlet-name&gt;
+  &lt;servlet-class&gt;com.foo.bar.MyServlet&lt;/servlet-class&gt;
+  &lt;init-param&gt;
+      &lt;param-name&gt;properties&lt;/param-name&gt;
+      &lt;param-value&gt;/velocity.properties&lt;/param-value&gt;
+  &lt;/init-param&gt;
+&lt;/servlet&gt;
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+Assuming all is right, this will ensure that when MyServlet is loaded,
+it will use the velocity.properties file to initialize itself
+rather than relying on it's internal defaults.
+</p>
+                                                <p>
+Note that Velocity uses a singleton model for it's central core Runtime
+class, so it is a very good idea to put the velocity-XX.jar
+into the WEB-INF/lib directory in all web applications that use
+Velocity to ensure that the web app classloader is
+managing your Runtime instance, rather than putting it in the CLASSPATH
+or the top level lib directory of the servlet runner.
+</p>
+                                                <p>
+This deployment method will ensure that different web applications will
+not be subject to Velocity configuration conflicts.
+</p>
+                            </blockquote>
+        </p>
+      </td></tr>
+      <tr><td><br/></td></tr>
+    </table>
+                                                <table border="0" cellspacing="0" cellpadding="2" width="100%">
+      <tr><td bgcolor="#525D76">
+        <font color="#ffffff" face="arial,helvetica,sanserif">
+          <a name="Using Velocity In General Applications"><strong>Using Velocity In General Applications</strong></a>
+        </font>
+      </td></tr>
+      <tr><td>
+        <blockquote>
+                                    <p>
+As Velocity was designed to be a general-use tool, it is just as useful in
+general application programs as it is servlets. In general, you can use the
+same programming pattern discussed at the beginning of this guide, but there
+are a few utility methods provided for application use, just like we provide
+the VelocityServlet base class for ease of use in servlet programming.
+The only new responsibility you have as the application programmer is to
+initialize the Velocity runtime engine, but that is easy.
+</p>
+                                                <a name="The Velocity Helper Class"><strong>The Velocity Helper Class</strong></a>
+                                                <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 :
+</p>
+                                                <ul>
+
+<li><code>setProperty( String key, Object o )</code><br />
+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.
+</li>
+
+<li><code>Object getProperty( String key )</code><br />
+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.
+</li>
+
+<li><code>init()</code><br />
+Initializes the runtime with the default properties provided in the
+distribution.(These are listed below in the section pertaining to
+properties.)
+</li>
+
+<li><code>init( Properties p )</code><br /> Initialize the runtime with the
+properties contained in the <code>java.util.Properties</code> object passed
+as an argument.
+</li>
+
+<li><code>init( String filename )</code><br /> initilizes the runtime
+using the properties found in the properties file filename
+</li>
+
+</ul>
+                                                <p>
+Note that in each case, the default properties will be used as a base
+configuration, and any additional properties specified by the application
+will replace individual defaults.  Any default properties not overwritten
+will remain in effect.  This has the benefit that only the properties
+you are interested in changing need to be specified, rather
+than a complete set.
+</p>
+                                                <p>
+Another thing to note is that the <code>init()</code> calls may be called
+more than once without harm in an application.  However, the first call to any
+of the <code>init()</code> functions will configure the engine with the
+configuration properties set at that point, and any further configuration
+changes or <code>init()</code> calls will be ignored.
+</p>
+                                                <p>
+The most common approaches to initializing Velocity will be something like :
+</p>
+                                                <ol>
+<li> Setup the configuration values you wish to set in a file in the same
+format as org/apache/velocity/runtime/defaults/velocity.properties
+(the default set),  or in a <code>java.util.Properties</code>, and then
+call either <code>init( filename )</code> or <code>init( Properties )</code>
+</li>
+
+<li> Set the configuration values individually using <code>setProperty()</code>
+and then call <code>init()</code>.  This method is generally used by more advanced
+applications that already have their own configuration management system -
+this allows the application so configure Velocity based upon values it generates
+at runtime, for example.
+</li>
+</ol>
+                                                <p>
+Once the runtime is initialized, you can do with it what you wish.. This mostly
+revolves around rendering templates into an output stream, and the Velocity
+utility class allows you to do this easily.  Currently, here are the methods
+and a brief description of what they do :
+</p>
+                                                <ul>
+  <li>
+     <code> evaluate( Context context,  Writer out, String logTag,
+     String instring )</code><br />
+     <code>evaluate( Context context, Writer writer, String logTag,
+     InputStream instream )</code><br />
+     These methods will render the input, in either the form of String or
+     InputStream to an output Writer, using a Context that you provide.
+     This is a very convenienient method to use for token replacement of
+     strings, or if you keep 'templates' of VTL-containing content in a
+     place like a database or other non-file storage, or simply generate such
+     dynamically.
+  </li>
+
+  <li>
+    <code>invokeVelocimacro( String vmName, String namespace, String params[],
+    Context context, Writer writer )</code><br />
+    Allows direct access to Velocimacros.  This can also be accomplished
+    via the <code>evaluate()</code> method above  if you wish.  Here you
+    simply name the vm you wish to be called, create an array of args to the VM,
+    a Context of data, and Writer for the output.  Note that the VM args
+    must be the 'keys' of the data objects in the Context, rather than
+    literal data to be used as the arg.  This will probably change.
+  </li>
+
+  <li>
+    <code>mergeTemplate( String templateName, Context context, Writer writer )
+    </code><br />
+    Convenient access to the normal template handling and rendering services
+    of Velocity.  This method will take care of getting and rendering the
+    template.  It will take advantage of loading the template according
+    to the properties setting for the file resource loader, and therefore
+    provides the advantage of file and parsed template caching that Velocity
+    offers.  This is the most efficient way to access templates,
+    and is recommended unless you have special needs.
+  </li>
+
+  <li>
+    <code> boolean templateExists( String name ) </code><br />
+    Determines if a template <code>name</code> is able to be found by
+    the currently configured resource loaders.
+  </li>
+</ul>
+                                                <p>
+Once we know about these basic helpers, it is easy to write Java program
+that uses Velocity.  Here it is:
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+import java.io.StringWriter;
+import org.apache.velocity.app.Velocity;
+import org.apache.velocity.VelocityContext;
+
+public class Example2
+{
+    public static void main( String args[] )
+    {
+        /* first, we init the runtime engine.  Defaults are fine. */
+
+        Velocity.init();
+
+        /* lets make a Context and put data into it */
+
+        VelocityContext context = new VelocityContext();
+
+        context.put(&quot;name&quot;, &quot;Velocity&quot;);
+        context.put(&quot;project&quot;, &quot;Jakarta&quot;);
+
+        /* lets render a template */
+
+        StringWriter w = new StringWriter();
+
+        Velocity.mergeTemplate(&quot;testtemplate.vm&quot;, context, w );
+        System.out.println(&quot; template : &quot; + w );
+
+        /* lets make our own string to render */
+
+        String s = &quot;We are using $project $name to render this.&quot;;
+        w = new StringWriter();
+        Velocity.evaluate( context, w, &quot;mystring&quot;, s );
+        System.out.println(&quot; string : &quot; + w );
+    }
+}
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+When we run this program, and have the template <code> testtemplate.vm</code>
+in the same directory as our program (because we used the default
+configuration properties, and the defaul place to load templates
+from is the current directory...), our output should be :
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+template : Hi!  This Velocity from the Jakarta project.
+
+string : We are using Jakarta Velocity to render this.
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+where the template we used, testtemplate.vm, is
+</p>
+                                                    <div align="left">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre>
+Hi!  This $name from the $project project.
+</pre></td>
+      <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+    </div>
+                                                <p>
+That's all there is to it!  Note that we didn't have to use both
+<code>mergeTemplate()</code> and <code>evaluate()</code> in our
+program.  They are both included there for demonstration purposes.
+You will probably use only one of the methods, but depending
+on you application requirements,  you are free to do what you wish.
+</p>
+                                                <p>
+This appears to be a little different from the 'fundamental pattern'
+that was mentioned at the beginning of this guide, but it really is the
+same thing.  First, you are making a context and filling it with
+the data needed.  Where this examples differs is that in the part of
+the above example where <code>mergeTemplate()</code> is used,
+<code>mergeTemplate()</code> is doing the work of getting the template
+and merging it for you, using the lower-level calls in the Runtime class.
+In the second example, you are making your template dynamically via the
+String, so that is analgous to the 'choose template' part of the process,
+and the <code>evaluate()</code> method does the merging for you using
+lower level calls.
+</p>
+                                                <p>
+So the example above sticks to the same simply pattern of using the Velocity
+template engine, but the utility functions do some of
+the repeated drudge work, or allow you other options for your
+template content other than template files.
+</p>
+                                                <a name="Exceptions"><strong>Exceptions</strong></a>
+                                                <p>
+There are three exceptions that Velocity will throw during the parse / merge cycle.
+This are additional to the exceptions that will come from IO problems, etc.
+They are found in the package <code>org.apache.velocity.exception</code> and are:
+</p>
+                                                <ol>
+<li>
+<code>ResourceNotFoundException</code><br />
+Thrown when the resource managment system cannot find a resource (template) that
+was requested.
+</li>
+
+<li>
+<code>ParseErrorException</code><br />
+Thrown when a VTL syntax error is found when parsing a resource (template).
+</li>
+
+<li>
+<code>MethodInvocationException</code><br />
+Thrown when a method of object in the context thrown an exception during
+render time.  This exception wraps the thrown exception and propogates it
+to the application.  This allows you to handle problems in your own objects
+at runtime.
+</li>
+</ol>
+                                                <p>
+In each case, a message is put into the runtime log.  For more information,
+see the Javadoc API documentation.
+</p>
+                                                <a name="Miscellaneous Details"><strong>Miscellaneous Details</strong></a>
+                                                <p>
+While the above example used the default properties, setting your own
+properties is very simple. All you have to do is make a properties file
+somewhere and pass the name of that file to the <code>init(String)</code>
+method of the Velocity utility class, or make a
+<code>java.util.Properties</code> object, add the desired properties and
+values, and pass that to the <code>init(Properties)</code> method.
+The latter method is convenient, because you can either fill it directly
+from a separate properties file via the <code>load()</code>  method, or even

[... 1931 lines stripped ...]


Mime
View raw message