geirm 01/09/26 04:45:01
Modified: xdocs developer-guide.xml
docs developer-guide.html
Log:
Added some updates and enhancement to singleton vs runtime section,
added some clarification on the ClasspathResourceLoader as suggested
on user list, etc.
Revision Changes Path
1.57 +63 -11 jakarta-velocity/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
retrieving revision 1.56
retrieving revision 1.57
diff -u -r1.56 -r1.57
--- developer-guide.xml 2001/09/19 11:55:53 1.56
+++ developer-guide.xml 2001/09/26 11:45:00 1.57
@@ -371,7 +371,9 @@
</p>
<ol>
-<li>Initialize Velocity. (You only do this once.)</li>
+<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>
@@ -379,7 +381,9 @@
</ol>
<p>
-In code, this looks like
+In code, using the singleton pattern via the
+<code>org.apache.velocity.app.Velocity</code> class,
+this looks like
</p>
<source><![CDATA[
@@ -387,6 +391,9 @@
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();
@@ -408,6 +415,11 @@
{
// syntax error : problem parsing the template
}
+catch( MethodInvocationException mie )
+{
+ // something invoked in the template
+ // threw an exception
+}
catch( Exception e )
{}
@@ -436,11 +448,10 @@
<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 - they are
-provided to make Velocity easier to integrated into your Java application.
+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>
@@ -462,8 +473,18 @@
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();
...
@@ -472,12 +493,22 @@
]]></source>
<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. This
+ 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>
@@ -491,9 +522,24 @@
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();
...
@@ -510,7 +556,7 @@
<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 Singlton model, or <code>org.apache.velocity.app.VelocityEngine</code>
+using the singleton model, or <code>org.apache.velocity.app.VelocityEngine</code>
if using the non-singleton model ('separate instance').
</p>
<p>
@@ -1937,6 +1983,7 @@
as well as the
<a href="developer-guide.html#Velocity Configuration Keys and Values">configuration
keys and values.</a>
</li>
+
</ul>
<p>
@@ -2054,14 +2101,19 @@
you use the standard JAR URL syntax of <code>java.net.JarURLConnection</code>.
</li>
<li>
- <b>ClasspathResourceLoader :</b> This loader gets resources from the classloader.
While the
+ <b>ClasspathResourceLoader :</b> This loader gets resources from the classloader.
+ In general, this means that the ClasspathResourceLoader will load
+ templates placed in the classpath (in jars, for example)
+ While the
classpath is a source of great pain and suffering in general, it is a very useful
- mechanism when working on a Servlet Spec 2.2 compliant servler runner.
+ mechanism when working on a Servlet Spec 2.2 (or newer) compliant servlet runner.
<a href="http://jakarta.apache.org/tomcat/";>Tomcat</a>
is an example of such. To use this loader effectively, all you must do is
jar your templates, and put that jar into the WEB-INF/lib directory of your
webapp. There are no configuration options to worry about, nor is the absolute
vs.
relative path an issue, as it is with Jar and File resource loaders.
+ Again, please note that the ClasspathResourceLoader is not only for use with a
+ servlet container, but can be used in any application context.
</li>
<li>
1.79 +62 -10 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -r1.78 -r1.79
--- developer-guide.html 2001/09/21 10:32:23 1.78
+++ developer-guide.html 2001/09/26 11:45:01 1.79
@@ -501,14 +501,18 @@
(or anywhere, actually), you will generally do the following :
</p>
<ol>
-<li>Initialize Velocity. (You only do this once.)</li>
+<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, this looks like
+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">
@@ -524,6 +528,9 @@
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();
@@ -545,6 +552,11 @@
{
// syntax error : problem parsing the template
}
+catch( MethodInvocationException mie )
+{
+ // something invoked in the template
+ // threw an exception
+}
catch( Exception e )
{}
@@ -588,8 +600,8 @@
<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 - they are
-provided to make Velocity easier to integrated into your Java application.
+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>
@@ -620,8 +632,18 @@
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();
...
@@ -638,11 +660,20 @@
</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. This
+ 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>
@@ -664,9 +695,24 @@
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();
...
@@ -690,7 +736,7 @@
<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 Singlton model, or <code>org.apache.velocity.app.VelocityEngine</code>
+using the singleton model, or <code>org.apache.velocity.app.VelocityEngine</code>
if using the non-singleton model ('separate instance').
</p>
<p>
@@ -2339,6 +2385,7 @@
as well as the
<a href="developer-guide.html#Velocity Configuration Keys and Values">configuration
keys and values.</a>
</li>
+
</ul>
<p>
Making a custom logger class if very simple. The code below is a
@@ -2475,14 +2522,19 @@
you use the standard JAR URL syntax of <code>java.net.JarURLConnection</code>.
</li>
<li>
- <b>ClasspathResourceLoader :</b> This loader gets resources from the classloader.
While the
+ <b>ClasspathResourceLoader :</b> This loader gets resources from the classloader.
+ In general, this means that the ClasspathResourceLoader will load
+ templates placed in the classpath (in jars, for example)
+ While the
classpath is a source of great pain and suffering in general, it is a very useful
- mechanism when working on a Servlet Spec 2.2 compliant servler runner.
+ mechanism when working on a Servlet Spec 2.2 (or newer) compliant servlet runner.
<a href="http://jakarta.apache.org/tomcat/";>Tomcat</a>
is an example of such. To use this loader effectively, all you must do is
jar your templates, and put that jar into the WEB-INF/lib directory of your
webapp. There are no configuration options to worry about, nor is the absolute
vs.
relative path an issue, as it is with Jar and File resource loaders.
+ Again, please note that the ClasspathResourceLoader is not only for use with a
+ servlet container, but can be used in any application context.
</li>
<li>
