You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by ta...@apache.org on 2010/06/03 18:44:58 UTC
svn commit: r951064 [2/5] - in
/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity:
VelocityUsersGuide.pdf developer-guide.html site.css user-guide.html
velocity.html vtl-reference-guide.html
Modified: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html
URL: http://svn.apache.org/viewvc/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html?rev=951064&r1=951063&r2=951064&view=diff
==============================================================================
--- click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html (original)
+++ click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/velocity/developer-guide.html Thu Jun 3 16:44:58 2010
@@ -1,3758 +1,2873 @@
-<!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">
- <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 <build target></code> where <build target>
- 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( "name", new String("Velocity") );
-
-Template template = null;
-
-try
-{
- template = Velocity.getTemplate("mytemplate.vm");
-}
-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("foo.vm");
-</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("foo.vm");
-</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("Hello");
-v.addElement("There");
-
-context.put("words", 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("words", 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("name","Velocity");
-context1.put("project", "Jakarta");
-context1.put("duplicate", "I am in context1");
-
-VelocityContext context2 = new VelocityContext( context1 );
-
-context2.put("lang", "Java" );
-context2.put("duplicate", "I am in context2");
-
-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 = ["a","b","c"] )
-$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 = ["a","b","c"] )
-#set( $foo = 1 )
-#set( $bar = "bar")
-</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 = "Jakarta";
- String p2 = "Velocity";
-
- Vector vec = new Vector();
- vec.addElement( p1 );
- vec.addElement( p2 );
-
- context.put("list", vec );
-
- Template template = null;
-
- try
- {
- template = getTemplate("sample.vm");
- }
- 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>
-<servlet>
- <servlet-name>MyServlet</servlet-name>
- <servlet-class>com.foo.bar.MyServlet</servlet-class>
- <init-param>
- <param-name>properties</param-name>
- <param-value>/velocity.properties</param-value>
- </init-param>
-</servlet>
-</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("name", "Velocity");
- context.put("project", "Jakarta");
-
- /* lets render a template */
-
- StringWriter w = new StringWriter();
-
- Velocity.mergeTemplate("testtemplate.vm", context, w );
- System.out.println(" template : " + w );
-
- /* lets make our own string to render */
-
- String s = "We are using $project $name to render this.";
- w = new StringWriter();
- Velocity.evaluate( context, w, "mystring", s );
- System.out.println(" string : " + 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
[... 4804 lines stripped ...]