geirm 01/05/18 08:15:25
Modified: xdocs changes.xml install.xml developer-guide.xml
docs changes.html install.html developer-guide.html
Log:
update, additions and enhancements..
Revision Changes Path
1.39 +17 -1 jakarta-velocity/xdocs/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/changes.xml,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -r1.38 -r1.39
--- changes.xml 2001/05/16 21:01:42 1.38
+++ changes.xml 2001/05/18 15:15:07 1.39
@@ -79,7 +79,7 @@
Tomcat and setup a webapp. (gmj)
</li>
<li>
- Removed the .close() and .flush() of the output stream in VelocityServlet
+ Removed the .close() of the output stream in VelocityServlet
and symmetrized VelocityWriter recycle. (gmj)
</li>
<li>
@@ -88,6 +88,22 @@
(Which came from Velocity and was renamed.) Should result in no changes
other than deprecation of Configuration and one deprecated method in
o.a.v.app.Velocity. (gmj)
+ </li>
+ <li>
+ Removed build/build.sh and build/build.bat and build/lib/ant*.jar to
+ move to explicit Ant-based build. (jss)
+ </li>
+ <li>
+ Changed JarResourceLoader to use normal 'path' configuration key
+ and added jar test to MultiLoaderTestCase. (gmj)
+ </li>
+ <li>
+ Updated the regexp in the WM conversion tool. (dlr)
+ </li>
+ <li>
+ Added EventHandler test case and example, and
+ removed NullReferenceEventHandler
+ as redundant. (gmj)
</li>
</ul>
</subsection>
1.15 +18 -4 jakarta-velocity/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/install.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- install.xml 2001/05/16 21:01:44 1.14
+++ install.xml 2001/05/18 15:15:09 1.15
@@ -23,7 +23,9 @@
href="http://jakarta.apache.org/getinvolved/cvsindex.html";>CVS</a> or
from the <a
href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/";>nightly
-builds</a>.
+builds</a>. However, you will need to install Ant, an excellent
+Java-based build tool. Ant is also a Jakarta project, and can be
+found <a href="http://jakarta.apache.org.ant/";>here</a>.
</p>
<p>
@@ -48,11 +50,12 @@
<section name="Building">
<p>
-To make building Velocity easy and consistant, we have provided scripts
-to build Velocity for both Unix and Windows. We use a Jakarta project
+To make building Velocity easy and consistant, we require a Jakarta project
called <a href="http://jakarta.apache.org/ant/";>Ant</a> version 1.3 or
higher to perform the build process. We assume that you have followed
-Ant's installation instructions and have it properly installed.
+Ant's installation instructions and have it properly installed. It's not
+difficult, and I think that you will find it an excellent addition to
+your programmer's toolbox.
</p>
<p>
@@ -81,6 +84,17 @@
version number. Be sure to update your classpath to include Velocity's
<filename>.jar</filename> file.
</p>
+
+<p>
+Note that to build any of the specific build targets, as detailed in
+the <a href="developers-guide.html">developers guide</a>, simply add
+the target name to the command line. For example, to build the Javadoc
+API documentation :
+</p>
+
+<source><![CDATA[
+ant javadocs
+]]></source>
<p>
Velocity should build 'out of the box', independent of your classpath.
1.42 +49 -31 jakarta-velocity/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- developer-guide.xml 2001/05/16 23:08:18 1.41
+++ developer-guide.xml 2001/05/18 15:15:10 1.42
@@ -752,7 +752,8 @@
<i><code>public Template handleRequest( HttpServletRequest, HttpServletResponse,
Context )</code></i>
<blockquote>
- This is the newer of the two <code>handleRequest()</code> methods.
+ 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
@@ -1283,38 +1284,55 @@
The EventCartridge is a class in which you register your event handlers, and then
the
EventCartridge acts as the delivery agent from which the Velocity engine will
access the event handlers at merge time if needed.
-Currently, there are 4 events that can be handled, and all are found in the
+Currently, there are 3 events that can be handled, and all are found in the
<code>org.apache.velocity.context</code> package. [note : they don't belong there ]
+</p>
-<ol>
-<li>
- Null #set() : when a #set() results in a null assignment, this is normally
- logged. The <code>NullSetEventHandler</code> allows you to 'veto' the
- logging of this condition.
-</li>
+<p>
+<i><code>org.apache.velocity.context.NullSetEventHandler</code></i>
-<li>
- Reference Insertion : a <code>ReferenceInsertionEventHandler</code> allows the
- developer to intercept each write of a reference ($foo) value to the output
- stream and modify that output.
-</li>
+<blockquote>
+When a #set() results in a null assignment, this is normally
+logged. The <code>NullSetEventHandler</code> allows you to 'veto' the
+logging of this condition.
+<br/>
+<pre>
+public interface NullSetEventHandler extends EventHandler
+{
+ public boolean nullSetLogMessage( String reference );
+}
+</pre>
+</blockquote>
-<li>
- Null Reference : When a reference is null, normally this results in a literal
- representation of the reference going to the output. The
- <code>NullReferenceEventHandler</code> is called with the reference literal,
- and allows you to modify the output to the stream.
-</li>
+<i><code>org.apache.velocity.context.ReferenceInsertionEventHandler</code></i>
+<blockquote>
+A <code>ReferenceInsertionEventHandler</code> allows the
+developer to intercept each write of a reference ($foo) value to the output
+stream and modify that output.
+<pre>
+public interface ReferenceInsertionEventHandler extends EventHandler
+{
+ public Object referenceInsert( String reference, Object value );
+}
+</pre>
+</blockquote>
-<li>
- Method Exception : When a user-supplied method throws an exception, the
- <code>MethodExceptionEventHandler</code> is invoked with the Class, method name
- and thrown Exception. The handler can either return a valid Object to be used
+<i><code>org.apache.velocity.context.MethodExceptionEventHandler</code></i>
+<blockquote>
+When a user-supplied method throws an exception, the
+<code>MethodExceptionEventHandler</code> is invoked with the Class, method name
+and thrown Exception. The handler can either return a valid Object to be used
as the return value of the method call, or throw the passed-in or new Exception,
- which will be wrapped and propogated to the user as a
- <code>MethodInvocationException</code>
-</li>
-</ol>
+which will be wrapped and propogated to the user as a
+<code>MethodInvocationException</code>
+<pre>
+public interface MethodExceptionEventHandler extends EventHandler
+{
+ public Object methodException( Class claz, String method, Exception e )
+ throws Exception;
+}
+</pre>
+</blockquote>
</p>
<strong>Using the EventCartridge</strong>
@@ -1332,12 +1350,11 @@
import org.apache.velocity.context.ReferenceInsertionEventHandler;
import org.apache.velocity.context.MethodExceptionEventHandler;
import org.apache.velocity.context.NullSetEventHandler;
-import org.apache.velocity.context.NullReferenceEventHandler;
...
public class Test implements ReferenceInsertionEventHandler,
- NullSetEventHandler,NullReferenceEventHandler,
+ NullSetEventHandler,
MethodExceptionEventHandler
{
...
@@ -1997,7 +2014,7 @@
<a name="encoding"></a>
<p>
-Velocity allows you to specify the character encoding of your
+As of version 1.1, Velocity allows you to specify the character encoding of your
template resources on a template by template basis. The normal resource
API's have been extended to take the encoding as an argument :
</p>
@@ -2023,7 +2040,8 @@
<p>
The value for the <i>encoding</i> argument is the conventional encoding
specification
-supported by your JVM, for example "UTF-8" or "ISO-8859-1".
+supported by your JVM, for example "UTF-8" or "ISO-8859-1". For the official names
+for character sets, see <a
href="http://www.iana.org/assignments/character-sets";>here</a>.
</p>
<p>
1.38 +17 -1 jakarta-velocity/docs/changes.html
Index: changes.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/changes.html,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -r1.37 -r1.38
--- changes.html 2001/05/16 21:01:31 1.37
+++ changes.html 2001/05/18 15:15:17 1.38
@@ -181,7 +181,7 @@
Tomcat and setup a webapp. (gmj)
</li>
<li>
- Removed the .close() and .flush() of the output stream in VelocityServlet
+ Removed the .close() of the output stream in VelocityServlet
and symmetrized VelocityWriter recycle. (gmj)
</li>
<li>
@@ -190,6 +190,22 @@
(Which came from Velocity and was renamed.) Should result in no changes
other than deprecation of Configuration and one deprecated method in
o.a.v.app.Velocity. (gmj)
+ </li>
+ <li>
+ Removed build/build.sh and build/build.bat and build/lib/ant*.jar to
+ move to explicit Ant-based build. (jss)
+ </li>
+ <li>
+ Changed JarResourceLoader to use normal 'path' configuration key
+ and added jar test to MultiLoaderTestCase. (gmj)
+ </li>
+ <li>
+ Updated the regexp in the WM conversion tool. (dlr)
+ </li>
+ <li>
+ Added EventHandler test case and example, and
+ removed NullReferenceEventHandler
+ as redundant. (gmj)
</li>
</ul>
</blockquote>
1.29 +34 -4 jakarta-velocity/docs/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/install.html,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- install.html 2001/05/16 21:01:34 1.28
+++ install.html 2001/05/18 15:15:18 1.29
@@ -117,7 +117,9 @@
Everything required to build Velocity comes with the distribution, which
can be obtained from <a
href="http://jakarta.apache.org/getinvolved/cvsindex.html";>CVS</a> or
from the <a
href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/";>nightly
-builds</a>.
+builds</a>. However, you will need to install Ant, an excellent
+Java-based build tool. Ant is also a Jakarta project, and can be
+found <a href="http://jakarta.apache.org.ant/";>here</a>.
</p>
<p>
The directory tree of the distribution looks like :
@@ -164,11 +166,12 @@
<tr><td>
<blockquote>
<p>
-To make building Velocity easy and consistant, we have provided scripts
-to build Velocity for both Unix and Windows. We use a Jakarta project
+To make building Velocity easy and consistant, we require a Jakarta project
called <a href="http://jakarta.apache.org/ant/";>Ant</a> version 1.3 or
higher to perform the build process. We assume that you have followed
-Ant's installation instructions and have it properly installed.
+Ant's installation instructions and have it properly installed. It's not
+difficult, and I think that you will find it an excellent addition to
+your programmer's toolbox.
</p>
<p>
In each case below, it is assumed that you were successful in getting
@@ -211,6 +214,33 @@
version number. Be sure to update your classpath to include Velocity's
<filename>.jar</filename> file.
</p>
+ <p>
+Note that to build any of the specific build targets, as detailed in
+the <a href="developers-guide.html">developers guide</a>, simply add
+the target name to the command line. For example, to build the Javadoc
+API documentation :
+</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>
+ant javadocs
+</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>
Velocity should build 'out of the box', independent of your classpath.
If you get an error building Velocity, try a different nightly build (as
1.58 +49 -32 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -r1.57 -r1.58
--- developer-guide.html 2001/05/16 23:08:25 1.57
+++ developer-guide.html 2001/05/18 15:15:19 1.58
@@ -952,7 +952,8 @@
<i><code>public Template handleRequest( HttpServletRequest, HttpServletResponse,
Context )</code></i>
<blockquote>
- This is the newer of the two <code>handleRequest()</code> methods.
+ 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
@@ -1613,38 +1614,54 @@
The EventCartridge is a class in which you register your event handlers, and then
the
EventCartridge acts as the delivery agent from which the Velocity engine will
access the event handlers at merge time if needed.
-Currently, there are 4 events that can be handled, and all are found in the
+Currently, there are 3 events that can be handled, and all are found in the
<code>org.apache.velocity.context</code> package. [note : they don't belong there ]
-
-<ol>
-<li>
- Null #set() : when a #set() results in a null assignment, this is normally
- logged. The <code>NullSetEventHandler</code> allows you to 'veto' the
- logging of this condition.
-</li>
+</p>
+ <p>
+<i><code>org.apache.velocity.context.NullSetEventHandler</code></i>
-<li>
- Reference Insertion : a <code>ReferenceInsertionEventHandler</code> allows the
- developer to intercept each write of a reference ($foo) value to the output
- stream and modify that output.
-</li>
+<blockquote>
+When a #set() results in a null assignment, this is normally
+logged. The <code>NullSetEventHandler</code> allows you to 'veto' the
+logging of this condition.
+<br />
+<pre>
+public interface NullSetEventHandler extends EventHandler
+{
+ public boolean nullSetLogMessage( String reference );
+}
+</pre>
+</blockquote>
-<li>
- Null Reference : When a reference is null, normally this results in a literal
- representation of the reference going to the output. The
- <code>NullReferenceEventHandler</code> is called with the reference literal,
- and allows you to modify the output to the stream.
-</li>
+<i><code>org.apache.velocity.context.ReferenceInsertionEventHandler</code></i>
+<blockquote>
+A <code>ReferenceInsertionEventHandler</code> allows the
+developer to intercept each write of a reference ($foo) value to the output
+stream and modify that output.
+<pre>
+public interface ReferenceInsertionEventHandler extends EventHandler
+{
+ public Object referenceInsert( String reference, Object value );
+}
+</pre>
+</blockquote>
-<li>
- Method Exception : When a user-supplied method throws an exception, the
- <code>MethodExceptionEventHandler</code> is invoked with the Class, method name
- and thrown Exception. The handler can either return a valid Object to be used
+<i><code>org.apache.velocity.context.MethodExceptionEventHandler</code></i>
+<blockquote>
+When a user-supplied method throws an exception, the
+<code>MethodExceptionEventHandler</code> is invoked with the Class, method name
+and thrown Exception. The handler can either return a valid Object to be used
as the return value of the method call, or throw the passed-in or new Exception,
- which will be wrapped and propogated to the user as a
- <code>MethodInvocationException</code>
-</li>
-</ol>
+which will be wrapped and propogated to the user as a
+<code>MethodInvocationException</code>
+<pre>
+public interface MethodExceptionEventHandler extends EventHandler
+{
+ public Object methodException( Class claz, String method, Exception e )
+ throws Exception;
+}
+</pre>
+</blockquote>
</p>
<strong>Using the
EventCartridge</strong>
<p>
@@ -1668,12 +1685,11 @@
import org.apache.velocity.context.ReferenceInsertionEventHandler;
import org.apache.velocity.context.MethodExceptionEventHandler;
import org.apache.velocity.context.NullSetEventHandler;
-import org.apache.velocity.context.NullReferenceEventHandler;
...
public class Test implements ReferenceInsertionEventHandler,
- NullSetEventHandler,NullReferenceEventHandler,
+ NullSetEventHandler,
MethodExceptionEventHandler
{
...
@@ -2452,7 +2468,7 @@
<blockquote>
<a name="encoding" />
<p>
-Velocity allows you to specify the character encoding of your
+As of version 1.1, Velocity allows you to specify the character encoding of your
template resources on a template by template basis. The normal resource
API's have been extended to take the encoding as an argument :
</p>
@@ -2475,7 +2491,8 @@
</p>
<p>
The value for the <i>encoding</i> argument is the conventional encoding
specification
-supported by your JVM, for example "UTF-8" or "ISO-8859-1".
+supported by your JVM, for example "UTF-8" or "ISO-8859-1". For the official names
+for character sets, see <a
href="http://www.iana.org/assignments/character-sets";>here</a>.
</p>
<p>
Note that this applies only to the encoding of the template itself - the output
