You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by si...@apache.org on 2002/04/02 18:46:32 UTC
cvs commit: jakarta-velocity-tools/xdocs index.xml menue.xml vellibrary-menue.xml vellibrary.xml site.dvsl site.dvsl_print site.dvsl_web
sidler 02/04/02 08:46:32
Modified: . README.txt
struts README.txt build.xml
struts/examples/struts index.html
struts/examples/struts/WEB-INF toolbox.xml web.xml
struts/examples/struts/doc examples.html
struts/examples/struts/examples/context_tools
mathtool-demo.txt mathtool-demo.vm
struts/examples/struts/examples/struts_app2 tool-demo.txt
tool-demo.vm
struts/examples/struts/examples/struts_app3 logon.vm
logon_vm.txt
struts/src/java/org/apache/velocity/tools/struts
ErrorsTool.java FormTool.java LinkTool.java
MessageTool.java StrutsUtils.java
struts/xdocs index.xml tools.xml
view README.txt build.xml
view/src/java/org/apache/velocity/tools/view/context
ChainedContext.java ToolboxContext.java
ViewContext.java
view/src/java/org/apache/velocity/tools/view/servlet
VelocityViewServlet.java
xdocs site.dvsl
Added: . build.xml
lib jdbc2_0-stdext.jar servlet.jar struts.jar xalan.jar
struts/examples/struts/WEB-INF VM_global_library.vm
velocity.properties
struts/examples/struts/WEB-INF/lib
velocity-tools-library-0.1.jar
velocity-tools-struts-0.7.jar
velocity-tools-view-0.4.jar
struts/lib velocity-tools-view-0.4.jar
struts/src/java/org/apache/velocity/tools/struts
package.html
struts/xdocs ErrorsTool.xml FormTool.xml LinkTool.xml
MessageTool.xml menue.xml quotes.txt userguide.xml
view/src/java/org/apache/velocity/tools/view/context
package.html
view/src/java/org/apache/velocity/tools/view/servlet
ServletContextToolLogger.java
ServletToolboxManager.java package.html
view/src/java/org/apache/velocity/tools/view/tools
ContextContextTool.java ContextToolLogger.java
LogEnabledContextTool.java
LogEnabledContextToolImpl.java
ServletContextTool.java ThreadSafeContextTool.java
package.html
view/xdocs velservlet-menue.xml velservlet.xml
xdocs index.xml menue.xml vellibrary-menue.xml
vellibrary.xml
Removed: struts/examples/struts/WEB-INF/lib
velocity-tools-view-0.3.jar
struts/lib velocity-tools-view-0.3.jar
struts/src/java/org/apache/velocity/tools/struts
MathTool.java ServletContextTool.java
ToolLoaderTool.java
struts/xdocs tool-ErrorsTool.xml tool-FormTool.xml
tool-LinkTool.xml tool-MessageTool.xml
view/docs index.html
view/src/java/org/apache/velocity/tools/view/tools
ContextTool.java ToolboxManager.java
view/xdocs index.xml project.xml
xdocs site.dvsl_print site.dvsl_web
Log:
Redesigned view and struts packages. Added a lot of documentation.
Upgraded to latest version of various third party software packages.
Revision Changes Path
1.4 +33 -7 jakarta-velocity-tools/README.txt
Index: README.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/README.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- README.txt 12 Mar 2002 11:41:44 -0000 1.3
+++ README.txt 2 Apr 2002 16:46:29 -0000 1.4
@@ -1,5 +1,8 @@
-What is Here
-============
+R E A D M E
+===========
+
+Contents
+--------
view : A general-purpose servlet for rendering Velocity templates.
There is no controller functionality - it's akin to the
@@ -7,10 +10,33 @@
for more information.
struts : Tools specific to integrating Velocity and Struts. See
- struts/README.txt for more information. There are serveral
- nice application examples included. Uses the view package.
- See struts/README.txt for more information.
+ struts/README.txt for more information. There are several
+ nice application examples included.
+
+tools : A collection of general purpose context tools. See
+ tools/REAMDE.txt for more information.
+
+
+
+Documentation
+-------------
+
+There is overview documentation and documentation for the different
+components. To build the documentation follow these steps:
+
+> ant docs
+> ant javadocs
+> ant javadocs-vellibrary
+
+> cd view
+> ant docs
+> ant javadocs-velservlet
+
+> cd ../struts
+> ant docs
+
+> cd ../tools
+> ant docs
-tools : General purpose context tools. Can be used with 'view' and
- 'struts' of course. To be added soon.
+then, point your browser at docs/index.html
1.1 jakarta-velocity-tools/build.xml
Index: build.xml
===================================================================
<project name="velocity-tools" default="all" basedir=".">
<!-- ========== Initialize Properties ===================================== -->
<property file="build/build.properties"/> <!-- Component local -->
<property file="../build.properties"/> <!-- Commons local -->
<property file="${user.home}/.build.properties"/> <!-- User local -->
<!-- ========== External Dependencies ===================================== -->
<!-- the local repository -->
<property name="project.repository" value="./lib" />
<!-- ========== Component Declarations ==================================== -->
<!-- The name of this component -->
<property name="project.name" value="velocity-tools" />
<!-- The title of this component -->
<property name="project.title" value="VelTools Documentation"/>
<!-- The current version number of this component -->
<property name="project.version" value="0.1"/>
<!-- The current version number of this component -->
<property name="project.date" value="27-Mar-2002"/>
<!-- The base directory for compilation targets -->
<property name="build.home" value="${basedir}"/>
<!-- The base directory for distribution targets -->
<property name="dist.home" value="dist"/>
<!-- The docs source directory -->
<property name="docs.src" value="xdocs"/>
<!-- The docs destination directory -->
<property name="docs.dest" value="docs"/>
<!-- The docs source directory -->
<property name="struts.docs.src" value="struts/xdocs"/>
<!-- The docs source directory -->
<property name="tools.docs.src" value="tools/xdocs"/>
<!-- ========== Compiler Defaults ========================================= -->
<!-- Construct compile classpath -->
<path id="classpath">
<fileset dir="${project.repository}">
<include name="**/*.jar"/>
</fileset>
</path>
<!-- ========== Executable Targets ======================================== -->
<!-- ================================================================== -->
<!-- I N I T -->
<!-- ================================================================== -->
<target name="init">
<!-- Initialize and evaluate conditionals -->
<echo message="-------- ${project.name} ${project.version} --------"/>
<filter token="name" value="${project.name}"/>
<filter token="version" value="${project.version}"/>
</target>
<!-- ================================================================== -->
<!-- P R E P A R E -->
<!-- ================================================================== -->
<target name="prepare" depends="init">
<!-- Prepare build directory -->
<mkdir dir="${docs.dest}/javadoc"/>
<mkdir dir="${docs.dest}/javadoc-vellibrary"/>
</target>
<!-- ================================================================== -->
<!-- S T A T I C -->
<!-- ================================================================== -->
<target name="static" depends="prepare">
<!-- Copy static files to build directory -->
<tstamp/>
</target>
<!-- ================================================================== -->
<!-- C L E A N -->
<!-- ================================================================== -->
<target name="clean"
description="Clean build and distribution directories">
<delete>
<fileset dir="${docs.dest}" includes="**/*.html"/>
</delete>
<delete dir="${docs.dest}/javadoc"/>
<delete dir="${docs.dest}/javadoc-vellibrary"/>
<delete>
<fileset dir="${basedir}" includes="**/*.bak"/>
</delete>
</target>
<!-- ================================================================== -->
<!-- A L L -->
<!-- ================================================================== -->
<target name="all" depends="clean, docs,javadocs"
description="Clean and compile all components"/>
<!-- ================================================================== -->
<!-- J A V A D O C S -->
<!-- ================================================================== -->
<target name="javadocs" depends="static"
description="Create Javadoc documentation">
<!-- Construct compile classpath -->
<path id="sourcepath">
<pathelement path="view/src/java/"/>
<pathelement path="struts/src/java/"/>
<pathelement path="tools/src/java/"/>
</path>
<javadoc sourcepathref="sourcepath"
destdir="${docs.dest}/javadoc"
author="true"
private="true"
version="true"
doctitle="<h1>${project.title}</h1>"
windowtitle="${project.title} (Version ${project.version})"
bottom="Copyright (c) 2002 Apache Software Foundation" >
<package name="org.apache.velocity.tools.*"/>
<classpath refid="classpath"/>
</javadoc>
</target>
<!-- ================================================================== -->
<!-- J A V A D O C S V E L L I B R A R Y -->
<!-- ================================================================== -->
<target name="javadocs-vellibrary" depends="static"
description="Create Javadoc documentation for VelLibrary subproject, only public members">
<!-- Construct compile classpath -->
<path id="sourcepath">
<pathelement path="view/src/java/"/>
<pathelement path="struts/src/java/"/>
<pathelement path="tools/src/java/"/>
</path>
<javadoc sourcepathref="sourcepath"
destdir="${docs.dest}/javadoc-vellibrary"
author="true"
public="true"
version="true"
doctitle="<h1>${project.title}</h1>"
windowtitle="${project.title} (Version ${project.version})"
bottom="Copyright (c) 2002 Apache Software Foundation" >
<package name="org.apache.velocity.tools.tools"/>
<package name="org.apache.velocity.tools.struts"/>
<package name="org.apache.velocity.tools.view.tools"/>
<package name="org.apache.velocity.tools.view.context"/>
<group title="Context Tools" packages="org.apache.velocity.tools.tools:org.apache.velocity.tools.struts"/>
<group title="Context Tools Infrastructure" packages="org.apache.velocity.tools.view.tools:org.apache.velocity.tools.view.context"/>
<classpath refid="classpath"/>
</javadoc>
</target>
<!-- ================================================================== -->
<!-- D O C S -->
<!-- ================================================================== -->
<target name="docs"
description="Generate documentation into ${docs.dest}">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
<classpath>
<path refid="classpath"/>
</classpath>
</taskdef>
<dvsl
basedir="${docs.src}"
destdir="${docs.dest}/"
toolboxfile="xdocs/toolbox.props"
extension=".html"
style="xdocs/site.dvsl"
excludes="*menue.xml"
includes="**/*.xml"
/>
<replace dir="${docs.dest}">
<replacefilter token="@@@version@@@" value="${project.version}"/>
<replacefilter token="@@@date@@@" value="${project.date}"/>
</replace>
</target>
</project>
1.1 jakarta-velocity-tools/lib/jdbc2_0-stdext.jar
<<Binary file>>
1.1 jakarta-velocity-tools/lib/servlet.jar
<<Binary file>>
1.1 jakarta-velocity-tools/lib/struts.jar
<<Binary file>>
1.1 jakarta-velocity-tools/lib/xalan.jar
<<Binary file>>
1.4 +4 -4 jakarta-velocity-tools/struts/README.txt
Index: README.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/README.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- README.txt 12 Mar 2002 11:36:47 -0000 1.3
+++ README.txt 2 Apr 2002 16:46:29 -0000 1.4
@@ -1,5 +1,5 @@
-Struts
-======
+R E A D M E
+===========
This part of jakarta-velocity-tools is focused on Struts-Velocity
integration using the VelocityViewServlet and other tools found
@@ -23,7 +23,7 @@
This compiles the package, generates a jar file in the same directory
and sets up the examples.
-The directory docs contains reference documentation for the included
+The directory 'docs' contains reference documentation for the included
context tools. More documentation will be added shortly. For now the
best way to get a feel for the Struts Velocity integration is to look
at the included examples.
@@ -50,7 +50,7 @@
o Change to directory examples/struts
o Use ant to build a deployable version: > ant war
-This will generate a velstruts.war file in directory examples.
+This will generate a velstruts.war file in directory 'examples'.
Deploy this .war file to the webapps directory of your servlet
runner and restart. Now point a web browser at:
1.4 +21 -21 jakarta-velocity-tools/struts/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/build.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- build.xml 12 Mar 2002 11:36:47 -0000 1.3
+++ build.xml 2 Apr 2002 16:46:29 -0000 1.4
@@ -1,4 +1,5 @@
-<project name="velocity-view" default="all" basedir=".">
+
+<project name="velocity-tools-struts" default="all" basedir=".">
<!-- ========== Initialize Properties ===================================== -->
@@ -22,10 +23,10 @@
<property name="project.title" value=""/>
<!-- The current version number of this component -->
- <property name="project.version" value="0.6"/>
+ <property name="project.version" value="0.7"/>
<!-- The current version number of this component -->
- <property name="project.date" value="05-Mar-2002"/>
+ <property name="project.date" value="29-Mar-2002"/>
<!-- The base directory for compilation targets -->
<property name="build.home" value="target"/>
@@ -76,8 +77,8 @@
<!-- ================================================================== -->
<!-- I N I T -->
<!-- ================================================================== -->
- <target name="init"
- description="Initialize and evaluate conditionals">
+ <target name="init">
+ <!-- Initialize and evaluate conditionals -->
<echo message="-------- ${project.name} ${project.version} --------"/>
<filter token="name" value="${project.name}"/>
<filter token="version" value="${project.version}"/>
@@ -86,8 +87,8 @@
<!-- ================================================================== -->
<!-- P R E P A R E -->
<!-- ================================================================== -->
- <target name="prepare" depends="init"
- description="Prepare build directory">
+ <target name="prepare" depends="init">
+ <!-- Prepare build directory -->
<mkdir dir="${build.home}"/>
<mkdir dir="${build.home}/classes"/>
<mkdir dir="${build.home}/conf"/>
@@ -97,8 +98,8 @@
<!-- ================================================================== -->
<!-- S T A T I C -->
<!-- ================================================================== -->
- <target name="static" depends="prepare"
- description="Copy static files to build directory">
+ <target name="static" depends="prepare">
+ <!-- Copy static files to build directory -->
<tstamp/>
<copy todir="${build.home}/conf" filtering="on">
<fileset dir="${conf.home}" includes="*.MF"/>
@@ -164,7 +165,7 @@
destdir="${build.home}/javadoc"
packagenames="org.apache.velocity.tools.struts.*"
author="true"
- private="true"
+ public="true"
version="true"
doctitle="<h1>${project.title}</h1>"
windowtitle="${project.title} (Version ${project.version})"
@@ -179,7 +180,8 @@
<!-- ================================================================== -->
<!-- J A R -->
<!-- ================================================================== -->
- <target name="jar" depends="compile">
+ <target name="jar" depends="compile"
+ description="Package class as jar file into ${builddir}">
<jar jarfile="${project.name}-${project.version}.jar"
basedir="${build.home}/classes"
manifest="${conf.home}/MANIFEST.MF"/>
@@ -189,7 +191,8 @@
<!-- ================================================================== -->
<!-- D O C S -->
<!-- ================================================================== -->
- <target name="docs">
+ <target name="docs"
+ description="Generate documentation into ${docs.dest}">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
@@ -205,7 +208,7 @@
toolboxfile="../xdocs/toolbox.props"
extension=".html"
style="../xdocs/site.dvsl"
- excludes="**/project.xml,**/tools.xml"
+ excludes="*menue.xml"
includes="**/*.xml"
/>
@@ -247,14 +250,11 @@
<fileset dir="${build.home}/javadoc"/>
</copy>
- <!-- Copy reference documentation -->
+<!-- Copy reference documentation
<copy todir="${examples.home}/struts/doc/">
- <fileset dir="${docs.dest}" includes="tool-*"/>
+ <fileset dir="${docs.dest}" includes="*.html"/>
</copy>
- <copy todir="${examples.home}/struts/doc/">
- <fileset dir="${docs.dest}" includes="index.html"/>
- </copy>
-
+-->
</target>
@@ -309,7 +309,7 @@
<!-- I N S T A L L J A R -->
<!-- ================================================================== -->
<target name="install-jar" depends="jar"
- description="--> Installs .jar file in ${lib.repo}">
+ description="Installs .jar file in ${lib.repo}">
<copy todir="${lib.repo}" filtering="no">
<fileset dir="${basedir}">
<include name="${project.name}-${project.version}.jar"/>
@@ -322,7 +322,7 @@
<!-- D E P L O Y J A R -->
<!-- ================================================================== -->
<target name="deploy-jar" depends="compile, jar"
- description="Deploy jar to example applications">
+ description="Deploy jar to example applications">
<delete>
<fileset dir="${examples.home}/struts/WEB-INF/lib" includes="${project.name}-*.jar"/>
1.6 +30 -44 jakarta-velocity-tools/struts/examples/struts/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/index.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.html 12 Mar 2002 11:36:47 -0000 1.5
+++ index.html 2 Apr 2002 16:46:29 -0000 1.6
@@ -10,19 +10,19 @@
<td>
<h2><font color="#FFFFFF"><img src="doc/img/spacer.gif" width="520" height="1"><br>
Velocity for Struts</font></h2>
- <font color="#FFFFFF">Version 0.6, March 5. 2002</font></td>
+ <font color="#FFFFFF">Version 0.7, April 2. 2002</font></td>
<td align="right"> </td>
</tr>
</table>
-<p>This is a web application to demonstrate the integration of Velocity with Struts.
- It contains basic documentation and serveral example applications.</p>
+<p>This is an example web application demonstrating the integration of the
+<a href="http://jakarta.apache.org/struts/">Struts web application framework</a>
+with the <a href="http://jakarta.apache.org/velocity">Velocity template engine</a>.
+</p>
-<p>This includes version 0.6 of Velocity for Struts. The API has been completely
- redesigned and is now more complete and more systematic. Reference documentation
- for the included context tools has been added.</p>
-<h5><b>Highlights</b></h5>
+
+<h5>Highlights</h5>
<ul>
<li>Velocity is now becoming an alternative view technology for Struts-based
Web applications.</li>
@@ -32,54 +32,40 @@
</ul>
+<h5>Status</h5>
+<p>The API has been redesigned completely and is now more complete and more
+systematic. An early draft of several documentation pages is
+now available.</p>
-<h5><b>Overview</b></h5>
-<ul>
- <li><b><a href="doc/examples.html">Example Applications</a></b><br>
- Five small example application have been included. Look at example 2 for a
- demonstration of the Velocity context tools for Struts. JSP versions of
- some of the examples have been included to allow a direct comparison of
- the two view technologies.</li>
-</ul>
+<p>This is an unrealeased work in progress. New versions will be announced
+on the Velocity mailing list and home page.</p>
-<ul>
- <li><b><a href="doc/index.html">Reference Documentation</a></b><br>
- This is the reference documentation of the context tools.
- <ul>
- <li><a href="doc/tool-MessageTool.html">MessageTool</a> - handles internationalized messages</li>
- <li><a href="doc/tool-ErrorsTool.html">ErrorsTool</a> - handles error messages</li>
- <li><a href="doc/tool-FormTool.html">FormTool</a> - provides support for form handling</li>
- <li><a href="doc/tool-LinkTool.html">LinkTool</a> - works with URIs</li>
- </ul>
- </li>
-</ul>
-<ul>
- <li><b><a href="doc/javadoc/index.html">JavaDoc</a></b><br></li>
-</ul>
-
-<h5><b>To Do</b></h5>
-<ul>
- <li>add documentation: overview, user guide, quick reference guide</li>
- <li>make documentation printable</li>
- <li>add ActionMessagesTool</li>
- <li>rework the current logging concept for context tools</li>
- <li>setup test cases</li>
- <li>add capability to config Velocity</li>
- <li>put together a binary distribution with examples and a blank application</li>
- <li>remove Velocity's [INFO] logging for each template<li>
-</ul>
+<h5>Application Examples</h5>
+<p>Five small <a href="doc/examples.html">application examples</a> have
+been included. Look at example 2 for a demonstration of the Velocity
+context tools for Struts. JSP versions of some of the examples have
+been included to allow a direct comparison of the two view technologies.
+</p>
+
+<h5>Documentation</h5>
+<p>An early draft of the <a href="http://www.teamup.com/jakarta-velocity-tools/struts/docs/index.html">
+documentation</a> is available online. This is a work in progress but I
+guess it is better than no documentation at all.</p>
+
+
+
<h5>Tested Configuration</h5>
<ul>
- <li>Tomcat 4.01, Resin 2.0.5</li>
+ <li>Tomcat 4.01, Resin 2.1.0</li>
<li>Netscape 4.7, MS Explorer 5.5</li>
- <li>Java 2 Version 1.3.1, Standard Editon, with Java Hot Spot Client VM</li>
- <li>Ant 1.4</li>
+ <li>Java 2 Version 1.3.1, Standard Editon, with Java Hot Spot Server VM</li>
+ <li>Ant 1.4.1</li>
<li>Jakarta Struts 1.0.2 Binary Library Distribution </li>
<li>Jakarta Velocity 1.3 dev with dependencies</li>
<li>Jakarta Servlet API 4 (same as distributed with Tomcat 4)
1.3 +17 -29 jakarta-velocity-tools/struts/examples/struts/WEB-INF/toolbox.xml
Index: toolbox.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/WEB-INF/toolbox.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- toolbox.xml 12 Mar 2002 11:36:47 -0000 1.2
+++ toolbox.xml 2 Apr 2002 16:46:29 -0000 1.3
@@ -1,36 +1,24 @@
<?xml version="1.0"?>
<toolbox>
-
- <tools>
-
- <object>
- <contextkey>toolLoader</contextkey>
- <class>org.apache.velocity.tools.struts.ToolLoaderTool</class>
- </object>
-
- <object>
- <contextkey>link</contextkey>
+ <tool>
+ <key>toolLoader</key>
+ <class>org.apache.velocity.tools.tools.ToolLoader</class>
+ </tool>
+ <tool>
+ <key>link</key>
<class>org.apache.velocity.tools.struts.LinkTool</class>
- </object>
-
- <object>
- <contextkey>msg</contextkey>
+ </tool>
+ <tool>
+ <key>msg</key>
<class>org.apache.velocity.tools.struts.MessageTool</class>
- </object>
-
- <object>
- <contextkey>errors</contextkey>
+ </tool>
+ <tool>
+ <key>errors</key>
<class>org.apache.velocity.tools.struts.ErrorsTool</class>
- </object>
-
- <object>
- <contextkey>form</contextkey>
+ </tool>
+ <tool>
+ <key>form</key>
<class>org.apache.velocity.tools.struts.FormTool</class>
- </object>
-
-
- </tools>
-
-</toolbox>
-
+ </tool>
+</toolbox>
\ No newline at end of file
1.3 +5 -0 jakarta-velocity-tools/struts/examples/struts/WEB-INF/web.xml
Index: web.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/WEB-INF/web.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- web.xml 9 Jan 2002 11:25:42 -0000 1.2
+++ web.xml 2 Apr 2002 16:46:29 -0000 1.3
@@ -58,6 +58,11 @@
<param-value>/WEB-INF/toolbox.xml</param-value>
</init-param>
+ <init-param>
+ <param-name>velocity.properties</param-name>
+ <param-value>/WEB-INF/velocity.properties</param-value>
+ </init-param>
+
<load-on-startup>10</load-on-startup>
</servlet>
1.1 jakarta-velocity-tools/struts/examples/struts/WEB-INF/VM_global_library.vm
Index: VM_global_library.vm
===================================================================
## Display all queued Struts errors
#macro (errorMarkup)
#if ($errors.exist() )
<ul>
#foreach ($e in $errors.all )
$e
#end
</ul>
#end
#end
## Display all queued Struts errors for a particular property
#macro (errorMarkupForProperty $property)
#if ($errors.exist($property) )
<ul>
#foreach ($er in $errors.get($property))
$er
#end
</ul>
#end
#end
1.1 jakarta-velocity-tools/struts/examples/struts/WEB-INF/velocity.properties
Index: velocity.properties
===================================================================
#----------------------------------------------------------------------------
# These are the default properties for the
# Velocity Runtime. These values are used when
# Runtime.init() is called, and when Runtime.init(properties)
# fails to find the specificed properties file.
#----------------------------------------------------------------------------
#----------------------------------------------------------------------------
# R U N T I M E L O G
#----------------------------------------------------------------------------
# Velocity uses the Servlet APIs logging facilites.
#----------------------------------------------------------------------------
# This controls if Runtime.error(), info() and warn() messages include the
# whole stack trace. The last property controls whether invalid references
# are logged.
#----------------------------------------------------------------------------
runtime.log.error.stacktrace = false
runtime.log.warn.stacktrace = false
runtime.log.info.stacktrace = false
runtime.log.invalid.reference = true
#----------------------------------------------------------------------------
# T E M P L A T E E N C O D I N G
#----------------------------------------------------------------------------
input.encoding=ISO-8859-1
output.encoding=ISO-8859-1
#----------------------------------------------------------------------------
# F O R E A C H P R O P E R T I E S
#----------------------------------------------------------------------------
# These properties control how the counter is accessed in the #foreach
# directive. By default the reference $velocityCount will be available
# in the body of the #foreach directive. The default starting value
# for this reference is 1.
#----------------------------------------------------------------------------
directive.foreach.counter.name = velocityCount
directive.foreach.counter.initial.value = 1
#----------------------------------------------------------------------------
# I N C L U D E P R O P E R T I E S
#----------------------------------------------------------------------------
# These are the properties that governed the way #include'd content
# is governed.
#----------------------------------------------------------------------------
directive.include.output.errormsg.start = <!-- include error :
directive.include.output.errormsg.end = see error log -->
#----------------------------------------------------------------------------
# P A R S E P R O P E R T I E S
#----------------------------------------------------------------------------
directive.parse.max.depth = 10
#----------------------------------------------------------------------------
# VELOCIMACRO PROPERTIES
#----------------------------------------------------------------------------
# global : name of default global library. It is expected to be in the regular
# template path. You may remove it (either the file or this property) if
# you wish with no harm.
#----------------------------------------------------------------------------
velocimacro.library = /WEB-INF/VM_global_library.vm
velocimacro.permissions.allow.inline = true
velocimacro.permissions.allow.inline.to.replace.global = false
velocimacro.permissions.allow.inline.local.scope = false
velocimacro.context.localscope = false
#----------------------------------------------------------------------------
# INTERPOLATION
#----------------------------------------------------------------------------
# turn off and on interpolation of references and directives in string
# literals. ON by default :)
#----------------------------------------------------------------------------
runtime.interpolate.string.literals = true
#----------------------------------------------------------------------------
# RESOURCE MANAGEMENT
#----------------------------------------------------------------------------
# Allows alternative ResourceManager and ResourceCache implementations
# to be plugged in.
#----------------------------------------------------------------------------
resource.manager.class = org.apache.velocity.runtime.resource.ResourceManagerImpl
resource.manager.cache.class = org.apache.velocity.runtime.resource.ResourceCacheImpl
1.1 jakarta-velocity-tools/struts/examples/struts/WEB-INF/lib/velocity-tools-library-0.1.jar
<<Binary file>>
1.1 jakarta-velocity-tools/struts/examples/struts/WEB-INF/lib/velocity-tools-struts-0.7.jar
<<Binary file>>
1.1 jakarta-velocity-tools/struts/examples/struts/WEB-INF/lib/velocity-tools-view-0.4.jar
<<Binary file>>
1.2 +1 -1 jakarta-velocity-tools/struts/examples/struts/doc/examples.html
Index: examples.html
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/doc/examples.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- examples.html 12 Mar 2002 11:36:48 -0000 1.1
+++ examples.html 2 Apr 2002 16:46:30 -0000 1.2
@@ -10,7 +10,7 @@
<td>
<h2><font color="#FFFFFF"><img src="img/spacer.gif" width="520" height="1"><br>
Velocity for Struts</font></h2>
- <font color="#FFFFFF">March 5. 2002</font></td>
+ <font color="#FFFFFF">April 2. 2002</font></td>
<td align="right"> </td>
</tr>
</table>
1.4 +4 -11 jakarta-velocity-tools/struts/examples/struts/examples/context_tools/mathtool-demo.txt
Index: mathtool-demo.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/context_tools/mathtool-demo.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mathtool-demo.txt 11 Jan 2002 11:20:21 -0000 1.3
+++ mathtool-demo.txt 2 Apr 2002 16:46:30 -0000 1.4
@@ -1,6 +1,5 @@
<html>
<head>
- <title>$get.message("title")</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
@@ -9,17 +8,14 @@
<h2>MathTool Demo (Velocity)</h2>
First, load the MathTool context tool into the context with key "math":<br>
- <code>\$toolLoader.load("math", "org.apache.velocity.contrib.struts.MathTool")</code><br><br>
-
- $toolLoader.load("math", "org.apache.velocity.contrib.struts.MathTool")
+ <code>$toolLoader.load("math", "org.apache.velocity.tools.tools.MathTool")</code><br><br>
+
+ $toolLoader.load("math", "org.apache.velocity.tools.tools.MathTool")
- Functions provided by MathTool:<br>
+ Some of the functions provided by MathTool:<br>
<table border="1" cellspacing="0" cellpadding="4">
<tr>
- <td>\$math.pi()</td><td>$math.pi()</td>
- </tr>
- <tr>
<td>\$math.min(345, 765)</td><td>$math.min(345, 765)</td>
</tr>
<tr>
@@ -33,9 +29,6 @@
</tr>
<tr>
<td>\$math.abs(-123)</td><td>$math.abs(-123)</td>
- </tr>
- <tr>
- <td>\$math.mod(19, 4)</td><td>$math.mod(19, 4)</td>
</tr>
</table>
1.4 +3 -10 jakarta-velocity-tools/struts/examples/struts/examples/context_tools/mathtool-demo.vm
Index: mathtool-demo.vm
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/context_tools/mathtool-demo.vm,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mathtool-demo.vm 11 Jan 2002 11:20:21 -0000 1.3
+++ mathtool-demo.vm 2 Apr 2002 16:46:30 -0000 1.4
@@ -1,6 +1,5 @@
<html>
<head>
- <title>$get.message("title")</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
@@ -9,17 +8,14 @@
<h2>MathTool Demo (Velocity)</h2>
First, load the MathTool context tool into the context with key "math":<br>
- <code>\$toolLoader.load("math", "org.apache.velocity.tools.struts..MathTool")</code><br><br>
+ <code>$toolLoader.load("math", "org.apache.velocity.tools.tools.MathTool")</code><br><br>
- $toolLoader.load("math", "org.apache.velocity.tools.struts.MathTool")
+ $toolLoader.load("math", "org.apache.velocity.tools.tools.MathTool")
- Functions provided by MathTool:<br>
+ Some of the functions provided by MathTool:<br>
<table border="1" cellspacing="0" cellpadding="4">
<tr>
- <td>\$math.pi()</td><td>$math.pi()</td>
- </tr>
- <tr>
<td>\$math.min(345, 765)</td><td>$math.min(345, 765)</td>
</tr>
<tr>
@@ -33,9 +29,6 @@
</tr>
<tr>
<td>\$math.abs(-123)</td><td>$math.abs(-123)</td>
- </tr>
- <tr>
- <td>\$math.mod(19, 4)</td><td>$math.mod(19, 4)</td>
</tr>
</table>
1.4 +49 -50 jakarta-velocity-tools/struts/examples/struts/examples/struts_app2/tool-demo.txt
Index: tool-demo.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/struts_app2/tool-demo.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- tool-demo.txt 12 Mar 2002 11:36:49 -0000 1.3
+++ tool-demo.txt 2 Apr 2002 16:46:30 -0000 1.4
@@ -1,14 +1,15 @@
<html>
<head>
- <title>$msg.title</title>
+ <title>Struts App2: Struts Context Tool Demo</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<base href="$link.baseRef">
</head>
<body>
- <h2>$msg.title (Velocity)</h2>
- <p>A demonstration of Struts context tools. Where available, the Velocity
- shorthand notation to method calls is shown as well.</p>
+ <h2>Struts App2: Struts Context Tool Demo</h2>
+ <p>A demonstration of the Velocity context tools provided for Struts support.
+ Where available, the Velocity shorthand notation to method calls is shown
+ as well.</p>
<h3>MessageTool</h3>
@@ -42,6 +43,10 @@
<td>$errors.exist()</td>
</tr>
<tr>
+ <td>\$errors.exist("language")</td>
+ <td>$errors.exist("language")</td>
+ </tr>
+ <tr>
<td>\$errors.getSize()<br>
\$errors.size</td>
<td>$errors.getSize()</td>
@@ -53,61 +58,55 @@
<tr>
<td>\$errors.getAll()<br>
\$errors.all</td>
- <td>$errors.getAll()</td>
+ <td>[This is a String representation of the ArrayList that is returned]<br>
+ $errors.getAll()</td>
</tr>
<tr>
<td>\$errors.get("language")<br>
\$errors.language</td>
- <td>$errors.get("language")</td>
+ <td>[This is a String representation of the ArrayList that is returned]<br>
+ $errors.get("language")</td>
+ </tr>
+ <tr>
+ <td>\$errors.getMsgs()<br>
+ \$errors.msgs</td>
+ <td>$errors.getMsgs()</td>
+ </tr>
+ <tr>
+ <td>\$errors.getMsgs("language")</td>
+ <td>$errors.getMsgs("language")</td>
</tr>
<tr>
<td>A Velocity macro to render all error messages:<br>
<pre><code>#macro (errorMarkup)
- #if ($errors.exist)
- <ul>
- #foreach ($e in $errors.all )
- <li>$e</li>
- #end
- </ul>
+ #if ($errors.exist() )
+ <ul>
+ #foreach ($e in $errors.all )
+ $e
#end
+ </ul>
+ #end
#end</code></pre>
</td>
<td>
- #macro (errorMarkup)
- #if ($errors.exist )
- <ul>
- #foreach ($e in $errors.all )
- <li>$e</li>
- #end
- </ul>
- #end
- #end
#errorMarkup()
</td>
</tr>
<tr>
- <td>A Velocity macro to render error messages specific to a property:<br>
+ <td>A Velocity macro to render error messages specific<br>
+ to a property:<br>
<pre><code>#macro (errorMarkup $property)
- #if ($errors.exist($property))
- <ul>
- #foreach ($er in $errors.get($property) )
- <li>$er</li>
- #end
- </ul>
+ #if ($errors.exist($property))
+ <ul>
+ #foreach ($er in $errors.get($property))
+ $er
#end
+ </ul>
+ #end
#end</code></pre>
</td>
<td>
- #macro (errorMarkup1 $property)
- #if ($errors.exist($property) )
- <ul>
- #foreach ($er in $errors.get($property) )
- <li>$er</li>
- #end
- </ul>
- #end
- #end
- #errorMarkup1("language")
+ #errorMarkupForProperty("language")
</td>
</tr>
@@ -142,8 +141,8 @@
<h3>LinkTool</h3>
<table border="1" cellspacing="0" cellpadding="4">
<tr>
- <td>\$link.setHref("template/login.vm")</td>
- <td>$link.setHref("template/login.vm")</td>
+ <td>\$link.setURI("template/login.vm")</td>
+ <td>$link.setURI("template/login.vm")</td>
</tr>
<tr>
<td>\$link.setAction("demo")</td>
@@ -158,18 +157,18 @@
<td>$link.setAbsolute("examples/index.html")</td>
</tr>
<tr>
- <td>\$link.setHref("index.html").addQueryData("key1", "val 1")</td>
- <td>$link.setHref("index.html").addQueryData("key1", "val 1")</td>
+ <td>\$link.setURI("index.html").addQueryData("key1", "val 1")</td>
+ <td>$link.setURI("index.html").addQueryData("key1", "val 1")</td>
</tr>
<tr>
- <td>\$link.setHref("index.html").addQueryData("key1", "val 1").getHref()<br>
- \$link.setHref("index.html").addQueryData("key1", "val 1").href</td>
- <td>$link.setHref("index.html").addQueryData("key1", "val 1").getHref()</td>
+ <td>\$link.setURI("index.html").addQueryData("key1", "val 1").getURI()<br>
+ \$link.setURI("index.html").addQueryData("key1", "val 1").URI</td>
+ <td>$link.setURI("index.html").addQueryData("key1", "val 1").getURI()</td>
</tr>
<tr>
- <td>\$link.setHref("/index.html").addQueryData("key1", "val 1").getQueryData()<br>
- \$link.setHref("/index.html").addQueryData("key1", "val 1").queryData</td>
- <td>$link.setHref("/index.html").addQueryData("key1", "val 1").getQueryData()</td>
+ <td>\$link.setURI("/index.html").addQueryData("key1", "val 1").getQueryData()<br>
+ \$link.setURI("/index.html").addQueryData("key1", "val 1").queryData</td>
+ <td>$link.setURI("/index.html").addQueryData("key1", "val 1").getQueryData()</td>
</tr>
<tr>
<td>\$link.getContextURL()<br>
@@ -187,8 +186,8 @@
<td>$link.getBaseRef()</td>
</tr>
<tr>
- <td>\$link.setHref("index.vm").toString()</td>
- <td>$link.setHref("index.vm").toString()</td>
+ <td>\$link.setURI("index.vm").toString()</td>
+ <td>$link.setURI("index.vm").toString()</td>
</tr>
</table>
1.4 +1 -19 jakarta-velocity-tools/struts/examples/struts/examples/struts_app2/tool-demo.vm
Index: tool-demo.vm
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/struts_app2/tool-demo.vm,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- tool-demo.vm 12 Mar 2002 11:36:49 -0000 1.3
+++ tool-demo.vm 2 Apr 2002 16:46:30 -0000 1.4
@@ -89,15 +89,6 @@
#end</code></pre>
</td>
<td>
- #macro (errorMarkup)
- #if ($errors.exist() )
- <ul>
- #foreach ($e in $errors.all )
- $e
- #end
- </ul>
- #end
- #end
#errorMarkup()
</td>
</tr>
@@ -115,16 +106,7 @@
#end</code></pre>
</td>
<td>
- #macro (errorMarkup1 $property)
- #if ($errors.exist($property) )
- <ul>
- #foreach ($er in $errors.get($property))
- $er
- #end
- </ul>
- #end
- #end
- #errorMarkup1("language")
+ #errorMarkupForProperty("language")
</td>
</tr>
1.3 +0 -9 jakarta-velocity-tools/struts/examples/struts/examples/struts_app3/logon.vm
Index: logon.vm
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/struts_app3/logon.vm,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- logon.vm 12 Mar 2002 11:36:49 -0000 1.2
+++ logon.vm 2 Apr 2002 16:46:30 -0000 1.3
@@ -6,15 +6,6 @@
<body>
- #macro (errorMarkup)
- #if ($errors.exist )
- <ul>
- #foreach ($e in $errors.all )
- $e
- #end
- </ul>
- #end
- #end
#errorMarkup()
<h3>Sign in, Please! (Velocity Version)</h3>
1.3 +0 -9 jakarta-velocity-tools/struts/examples/struts/examples/struts_app3/logon_vm.txt
Index: logon_vm.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/examples/struts/examples/struts_app3/logon_vm.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- logon_vm.txt 12 Mar 2002 11:36:49 -0000 1.2
+++ logon_vm.txt 2 Apr 2002 16:46:30 -0000 1.3
@@ -6,15 +6,6 @@
<body>
- #macro (errorMarkup)
- #if ($errors.exist )
- <ul>
- #foreach ($e in $errors.all )
- $e
- #end
- </ul>
- #end
- #end
#errorMarkup()
<h3>Sign in, Please! (Velocity Version)</h3>
1.1 jakarta-velocity-tools/struts/lib/velocity-tools-view-0.4.jar
<<Binary file>>
1.3 +50 -31 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/ErrorsTool.java
Index: ErrorsTool.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/ErrorsTool.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ErrorsTool.java 13 Mar 2002 22:08:54 -0000 1.2
+++ ErrorsTool.java 2 Apr 2002 16:46:30 -0000 1.3
@@ -64,33 +64,50 @@
import org.apache.struts.util.MessageResources;
import org.apache.struts.action.*;
+
import org.apache.velocity.tools.view.context.ViewContext;
-import org.apache.velocity.tools.view.tools.ContextTool;
+import org.apache.velocity.tools.view.tools.LogEnabledContextToolImpl;
+import org.apache.velocity.tools.view.tools.ServletContextTool;
/**
- * <p>Context tool to work with the Struts error messages.
- * Extends ServletContextTool to profit from the logging
- * facilities of that class.</p>
+ * <p>Context tool to work with the Struts error messages.</p>
+ *
+ * <p>This class is equipped to be used with a toolbox manager, for example
+ * the ServletToolboxManager included with VelServlet. The class extends
+ * ServletContextToolLogger to profit from the logging facilities of that class.
+ * Furthermore, this class implements interface ServletContextTool, which allows
+ * a toolbox manager to pass the required context information.</p>
*
+ * <p>This class is not thread-safe by design. A new instance is needed for
+ * the processing of every template request.</p>
+ *
+
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
- * @version $Id: ErrorsTool.java,v 1.2 2002/03/13 22:08:54 sidler Exp $
+ * @version $Id: ErrorsTool.java,v 1.3 2002/04/02 16:46:30 sidler Exp $
*
*/
-public class ErrorsTool extends ServletContextTool
+public class ErrorsTool extends LogEnabledContextToolImpl
+ implements ServletContextTool
{
// --------------------------------------------- Properties ---------------
/**
- * A reference to the HtttpServletRequest.
+ * A reference to the ServletContext
+ */
+ protected ServletContext application;
+
+
+ /**
+ * A reference to the HttpServletRequest.
*/
protected HttpServletRequest request;
/**
- * A reference to the HtttpSession.
+ * A reference to the HttpSession.
*/
protected HttpSession session;
@@ -117,16 +134,17 @@
// --------------------------------------------- Constructors -------------
/**
- * Returns a factory. Use method {@link #init(ViewContext context)} to
- * obtain instances of this class.
+ * Returns a factory for instances of this class. Use method
+ * {@link #getInstance(ViewContext context)} to obtain instances
+ * of this class. Do not use instance obtained from this method
+ * in templates. They are not properly initialized.
*/
public ErrorsTool()
- {
- }
+ {}
/**
- * For internal use only! Use method {@link #init(ViewContext context)}
+ * For internal use only! Use method {@link #getInstance(ViewContext context)}
* to obtain instances of the tool.
*/
private ErrorsTool(ViewContext context)
@@ -142,27 +160,26 @@
- // --------------------------------------------- ContextTool Interface ----
+ // ----------------------------------- Interface ServletContextTool -------
/**
- * A new tool object will be instantiated per-request by calling
- * this method. A ContextTool is effectively a factory used to
- * create objects for use in templates. Some tools may simply return
- * themselves from this method others may instantiate new objects
- * to hold the per-request state.
+ * Returns an initialized instance of this context tool.
*/
- public Object init(ViewContext context)
+ public Object getInstance(ViewContext context)
{
return new ErrorsTool(context);
}
-
+
/**
- * Perform any cleanup needed. This method is called after the template
- * has been processed.
+ * <p>Returns the default life cycle for this tool. This is
+ * {@link ServletContextTool#REQUEST}. Do not overwrite this
+ * per toolbox configuration. No alternative life cycles are
+ * supported by this tool</p>
*/
- public void destroy(Object o)
+ public String getDefaultLifecycle()
{
+ return ServletContextTool.REQUEST;
}
@@ -185,9 +202,9 @@
/**
* <p>Returns true if there are action errors queued for the specified
- * property, otherwise <code>false</code>.</p>
+ * category of errors, otherwise <code>false</code>.</p>
*
- * @param property The category of errors to check for.
+ * @param property the category of errors to check for
*/
public boolean exist(String property)
{
@@ -195,7 +212,6 @@
{
return false;
}
-
return (errors.size(property) > 0);
}
@@ -246,10 +262,12 @@
/**
* Returns the set of localized error messages as an
* <code>java.util.ArrayList</code> of <code> java.lang.String</code>
- * for all errors queued of the specified property or <code>null</code>
- * if no error are queued for the specified property. If the message
+ * for all errors queued of the specified category or <code>null</code>
+ * if no error are queued for the specified category. If the message
* resources don't contain an error message for a particular error key,
* the key itself is used as error message.
+ *
+ * @param property the category of errors to operate on
*/
public ArrayList get(String property)
{
@@ -295,7 +313,7 @@
else
{
// if error message cannot be found for a key, return key instead
- log(WARNING, "Message for key " + errormsg.getKey() + " could not be found in message resources.");
+ log(WARN, "Message for key " + errormsg.getKey() + " could not be found in message resources.");
list.add(errormsg.getKey());
}
}
@@ -320,13 +338,14 @@
/**
- * <p>Renders the queued error messages of a particual property as a list.
+ * <p>Renders the queued error messages of a particual category as a list.
* This method expects the message keys <code>errors.header</code> and
* <code>errors.footer</code> in the message resources. The value of the
* former is rendered before the list of error messages and the value of
* the latter is rendered after the error messages.</p>
*
* @param property the category of errors to render
+ *
* @return The formatted error messages. If no error messages are queued,
* an empty string is returned.
*/
1.3 +35 -22 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/FormTool.java
Index: FormTool.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/FormTool.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- FormTool.java 13 Mar 2002 22:08:54 -0000 1.2
+++ FormTool.java 2 Apr 2002 16:46:30 -0000 1.3
@@ -62,23 +62,34 @@
import org.apache.struts.action.*;
import org.apache.velocity.tools.view.context.ViewContext;
-import org.apache.velocity.tools.view.tools.ContextTool;
+import org.apache.velocity.tools.view.tools.LogEnabledContextToolImpl;
+import org.apache.velocity.tools.view.tools.ServletContextTool;
/**
- * <p>Context tool to work with forms in Struts. Extends ServletContextTool
- * to profit from the logging facilities of that class.</p>
+ * <p>Context tool to work with HTML forms in Struts.</p>
+ *
+ * <p>This class is equipped to be used with a toolbox manager, for example
+ * the ServletToolboxManager included with VelServlet. The class extends
+ * ServletContextToolLogger to profit from the logging facilities of that class.
+ * Furthermore, this class implements interface ServletContextTool, which allows
+ * a toolbox manager to pass the required context information.</p>
+ *
+ * <p>This class is not thread-safe by design. A new instance is needed for
+ * the processing of every template request.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
- * @version $Id: FormTool.java,v 1.2 2002/03/13 22:08:54 sidler Exp $
+ * @version $Id: FormTool.java,v 1.3 2002/04/02 16:46:30 sidler Exp $
*
*/
-public class FormTool extends ServletContextTool
+public class FormTool extends LogEnabledContextToolImpl
+ implements ServletContextTool
{
- // --------------------------------------------- Private Properties -------
+ // --------------------------------------------- Properties ---------------
+
/**
* A reference to the HtttpServletRequest.
*/
@@ -95,8 +106,10 @@
// --------------------------------------------- Constructors -------------
/**
- * Returns a factory. Use method {@link #init(ViewContext context)} to
- * obtain instances of this class.
+ * Returns a factory for instances of this class. Use method
+ * {@link #getInstance(ViewContext context)} to obtain instances
+ * of this class. Do not use instance obtained from this method
+ * in templates. They are not properly initialized.
*/
public FormTool()
{
@@ -104,39 +117,37 @@
/**
- * For internal use only! Use method {@link #init(ViewContext context)}
+ * For internal use only! Use method {@link #getInstance(ViewContext context)}
* to obtain instances of the tool.
*/
private FormTool(ViewContext context)
{
this.request = context.getRequest();
this.session = request.getSession(false);
- this.application = context.getServletContext();
}
- // --------------------------------------------- ContextTool Interface ----
+ // ----------------------------------- Interface ServletContextTool -------
/**
- * A new tool object will be instantiated per-request by calling
- * this method. A context tool is effectively a factory used to
- * create objects for use in templates. Some tools may simply return
- * themselves from this method others may instantiate new objects
- * to hold the per-request state.
+ * Returns an initialized instance of this context tool.
*/
- public Object init(ViewContext context)
+ public Object getInstance(ViewContext context)
{
return new FormTool(context);
}
/**
- * Perform any cleanup needed. This method is called after the template
- * has been processed.
+ * <p>Returns the default life cycle for this tool. This is
+ * {@link ServletContextTool#REQUEST}. Do not overwrite this
+ * per toolbox configuration. No alternative life cycles are
+ * supported by this tool</p>
*/
- public void destroy(Object o)
+ public String getDefaultLifecycle()
{
+ return ServletContextTool.REQUEST;
}
@@ -171,8 +182,10 @@
/**
* <p>Returns the query parameter name under which a cancel button press
- * must be reported if form validation is to be skipped. This is the value
- * of <code>org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY</code></p>
+ * must be reported if form validation is to be skipped.</p>
+ *
+ * <p>This is the value of
+ * <code>org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY</code></p>
*/
public String getCancelName()
{
1.3 +73 -37 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/LinkTool.java
Index: LinkTool.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/LinkTool.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- LinkTool.java 13 Mar 2002 22:08:54 -0000 1.2
+++ LinkTool.java 2 Apr 2002 16:46:30 -0000 1.3
@@ -66,24 +66,39 @@
import org.apache.struts.action.*;
import org.apache.velocity.tools.view.context.ViewContext;
-import org.apache.velocity.tools.view.tools.ContextTool;
+import org.apache.velocity.tools.view.tools.LogEnabledContextToolImpl;
+import org.apache.velocity.tools.view.tools.ServletContextTool;
/**
- * <p>Context tool to work with URI links in Struts. Extends
- * ServletContextTool to profit from the logging facilities of
- * that class.</p>
+ * <p>Context tool to work with URI links in Struts.</p>
+ *
+ * <p>This class is equipped to be used with a toolbox manager, for example
+ * the ServletToolboxManager included with VelServlet. The class extends
+ * ServletContextToolLogger to profit from the logging facilities of that class.
+ * Furthermore, this class implements interface ServletContextTool, which allows
+ * a toolbox manager to pass the required context information.</p>
+ *
+ * <p>This class is not thread-safe by design. A new instance is needed for
+ * the processing of every template request.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
* @author <a href="mailto:nathan@esha.com">Nathan Bubna</a>
*
- * @version $Id: LinkTool.java,v 1.2 2002/03/13 22:08:54 sidler Exp $
+ * @version $Id: LinkTool.java,v 1.3 2002/04/02 16:46:30 sidler Exp $
*
*/
-public class LinkTool extends ServletContextTool
+public class LinkTool extends LogEnabledContextToolImpl
+ implements ServletContextTool
{
- // --------------------------------------------- Private Properties -------
+ // --------------------------------------------- Properties ---------------
+
+ /**
+ * A reference to the ServletContext
+ */
+ protected ServletContext application;
+
/**
* A reference to the HtttpServletRequest.
@@ -112,8 +127,10 @@
// --------------------------------------------- Constructors -------------
/**
- * Returns a factory. Use method {@link #init(ViewContext context)} to
- * obtain instances of this class.
+ * Returns a factory for instances of this class. Use method
+ * {@link #getInstance(ViewContext context)} to obtain instances
+ * of this class. Do not use instance obtained from this method
+ * in templates. They are not properly initialized.
*/
public LinkTool()
{
@@ -127,8 +144,8 @@
/**
- * For internal use only! Use method {@link #init(ViewContext context)}
- * to obtain instances of the tool.
+ * For internal use only! Use method {@link #getInstance(ViewContext context)}
+ * to obtain instances of this tool.
*/
private LinkTool(ViewContext context)
{
@@ -143,7 +160,10 @@
/**
* For internal use.
*
- * Copies 'that' LinkTool into this one and adds the new query data
+ * Copies 'that' LinkTool into this one and adds the new query data.
+ *
+ * @param that a reference to a link tool
+ * @param pair the query parameter to add
*/
private LinkTool(LinkTool that, QueryPair pair)
{
@@ -167,7 +187,10 @@
/**
* For internal use.
*
- * Copies 'that' LinkTool into this one and sets the new URI
+ * Copies 'that' LinkTool into this one and sets the new URI.
+ *
+ * @param that a reference to a link tool
+ * @param uri uri string
*/
private LinkTool(LinkTool that, String uri)
{
@@ -181,37 +204,36 @@
-
- // --------------------------------------------- ContextTool Interface ----
+ // ----------------------------------- Interface ServletContextTool -------
/**
- * A new tool object will be instantiated per-request by calling
- * this method. A ContextTool is effectively a factory used to
- * create objects for use in templates. Some tools may simply return
- * themselves from this method others may instantiate new objects
- * to hold the per-request state.
+ * Returns an initialized instance of this context tool.
*/
- public Object init(ViewContext context)
+ public Object getInstance(ViewContext context)
{
return new LinkTool(context);
}
-
-
+
+
/**
- * Perform any cleanup needed. This method is called after the template
- * has been processed.
+ * <p>Returns the default life cycle for this tool. This is
+ * {@link ServletContextTool#REQUEST}. Do not overwrite this
+ * per toolbox configuration. No alternative life cycles are
+ * supported by this tool</p>
*/
- public void destroy(Object o)
+ public String getDefaultLifecycle()
{
+ return ServletContextTool.REQUEST;
}
+
-
+
// --------------------------------------------- View Helpers -------------
/**
- * <p>Returns a copy of this link with the given URI reference.
+ * <p>Returns a copy of the link with the given URI reference set.
* No conversions are applied to the given URI reference. The URI
* reference can be absolute, server-relative, relative and may
* contain query parameters. This method will overwrite any
@@ -224,6 +246,7 @@
* or setForward() instead.</p>
*
* @param uri URI reference to set
+ *
* @return a new instance of LinkTool
*/
public LinkTool setURI(String uri)
@@ -233,29 +256,32 @@
/**
- * <p>Returns a copy of this link with the given action name
+ * <p>Returns a copy of the link with the given action name
* converted into a server-relative URI reference. This method
* does not check if the specified action really is defined.
* This method will overwrite any previous URI reference settings
* but will copy the query string.</p>
*
* @param action an action path as defined in struts-config.xml
+ *
* @return a new instance of LinkTool
*/
public LinkTool setAction(String action)
{
- return new LinkTool(this, StrutsUtils.getActionMappingURL(application, request, action));
+ return new LinkTool(this,
+ StrutsUtils.getActionMappingURL(application, request, action));
}
/**
- * <p>Returns a copy of this link with the given global forward name
+ * <p>Returns a copy of the link with the given global forward name
* converted into a server-relative URI reference. If the parameter
* does not map to an existing global forward name, <code>null</code>
* is returned. This method will overwrite any previous URI reference
* settings but will copy the query string.</p>
*
* @param forward a global forward name as defined in struts-config.xml
+ *
* @return a new instance of LinkTool
*/
public LinkTool setForward(String forward)
@@ -264,7 +290,7 @@
if (mapping == null)
{
- log(WARNING, "In method setForward(" + forward + "): Parameter does not map to a valid forward.");
+ log(WARN, "In method setForward(" + forward + "): Parameter does not map to a valid forward.");
return null;
}
@@ -282,7 +308,7 @@
/**
- * <p>Returns a copy of this link with the specified context-relative
+ * <p>Returns a copy of the link with the specified context-relative
* URI reference converted to a server-relative URI reference. This
* method will overwrite any previous URI reference settings but will
* copy the query string.</p>
@@ -294,6 +320,7 @@
*
* @param uri A context-relative URI reference. A context-relative URI
* is a URI that is relative to the root of this web application.
+ *
* @return a new instance of LinkTool
*/
public LinkTool setAbsolute(String uri)
@@ -316,6 +343,7 @@
*
* @param key key of new query parameter
* @param value value of new query parameter
+ *
* @return a new instance of LinkTool
*/
public LinkTool addQueryData(String key, Object value)
@@ -361,7 +389,7 @@
/**
- * <p>Returns the URI that addresses this web application, e.g.
+ * <p>Returns the URI that addresses this web application. E.g.
* <code>http://myserver.net/myapp</code>. This string does not end
* with a "/". Note! This will not represent any URI reference or
* query data set for this LinkTool.</p>
@@ -467,13 +495,22 @@
private final String key;
private final Object value;
+
+ /**
+ * Construct a new query pair.
+ *
+ * @param key query pair
+ * @param value query value
+ */
public QueryPair(String key, Object value)
{
this.key = key;
this.value = value;
}
-
+ /**
+ * Return the URL-encoded query string.
+ */
public String toString()
{
StringBuffer out = new StringBuffer();
@@ -485,6 +522,5 @@
}
-
-
+
}
1.2 +47 -20 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/MessageTool.java
Index: MessageTool.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/MessageTool.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- MessageTool.java 12 Mar 2002 11:36:49 -0000 1.1
+++ MessageTool.java 2 Apr 2002 16:46:30 -0000 1.2
@@ -65,23 +65,38 @@
import org.apache.struts.action.*;
import org.apache.velocity.tools.view.context.ViewContext;
-import org.apache.velocity.tools.view.tools.ContextTool;
+import org.apache.velocity.tools.view.tools.LogEnabledContextToolImpl;
+import org.apache.velocity.tools.view.tools.ServletContextTool;
/**
- * <p>Context tool to work with the Struts message resources.
- * Extends ServletContextTool to profit from the logging
- * facilities of that class.</p>
+ * <p>Context tool that provides methods to render Struts message resources.</p>
+ *
+ * <p>This class is equipped to be used with a toolbox manager, for example
+ * the ServletToolboxManager included with VelServlet. The class extends
+ * ServletContextToolLogger to profit from the logging facilities of that class.
+ * Furthermore, this class implements interface ServletContextTool, which allows
+ * a toolbox manager to pass the required context information.</p>
+ *
+ * <p>This class is not thread-safe by design. A new instance is needed for
+ * the processing of every template request.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
- * @version $Id: MessageTool.java,v 1.1 2002/03/12 11:36:49 sidler Exp $
+ * @version $Id: MessageTool.java,v 1.2 2002/04/02 16:46:30 sidler Exp $
*
*/
-public class MessageTool extends ServletContextTool
+public class MessageTool extends LogEnabledContextToolImpl
+ implements ServletContextTool
{
- // --------------------------------------------- Private Properties -------
+ // --------------------------------------------- Properties -------
+
+ /**
+ * A reference to the ServletContext
+ */
+ protected ServletContext application;
+
/**
* A reference to the HttpServletRequest.
@@ -111,8 +126,10 @@
// --------------------------------------------- Constructors -------------
/**
- * Returns a factory. Use method {@link #init(ViewContext context)} to
- * obtain instances of this class.
+ * Returns a factory for instances of this class. Use method
+ * {@link #getInstance(ViewContext context)} to obtain instances
+ * of this class. Do not use instance obtained from this method
+ * in templates. They are not properly initialized.
*/
public MessageTool()
{
@@ -120,8 +137,10 @@
/**
- * For internal use only! Use method {@link #init(ViewContext context)}
+ * For internal use only! Use method {@link #getInstance(ViewContext context)}
* to obtain instances of the tool.
+ *
+ * @param context the Velocity context
*/
private MessageTool(ViewContext context)
{
@@ -135,27 +154,26 @@
- // --------------------------------------------- ContextTool Interface ----
+ // ----------------------------------- Interface ServletContextTool -------
/**
- * A new tool object will be instantiated per-request by calling
- * this method. A context tool is effectively a factory used to
- * create objects for use in templates. Some tools may simply return
- * themselves from this method others may instantiate new objects
- * to hold the per-request state.
+ * Returns an initialized instance of this context tool.
*/
- public Object init(ViewContext context)
+ public Object getInstance(ViewContext context)
{
return new MessageTool(context);
}
/**
- * Perform any cleanup needed. This method is called after the template
- * has been processed.
+ * <p>Returns the default life cycle for this tool. This is
+ * {@link ServletContextTool#REQUEST}. Do not overwrite this
+ * per toolbox configuration. No alternative life cycles are
+ * supported by this tool</p>
*/
- public void destroy(Object o)
+ public String getDefaultLifecycle()
{
+ return ServletContextTool.REQUEST;
}
@@ -168,6 +186,7 @@
* message.
*
* @param key message key
+ *
* @return the localized message for the specified key or
* <code>null</code> if no such message exists
*/
@@ -190,6 +209,7 @@
*
* @param key message key
* @param args replacement parameters for this message
+ *
* @return the localized message for the specified key or
* <code>null</code> if no such message exists
*/
@@ -217,6 +237,12 @@
* Same as {@link #get(String key, Object[] args)}, but takes a
* <code>java.util.ArrayList</code> instead of an array. This is
* more Velocity compatible.
+ *
+ * @param key message key
+ * @param args replacement parameters for this message
+ *
+ * @return the localized message for the specified key or
+ * <code>null</code> if no such message exists
*/
public String get(String key, ArrayList args)
{
@@ -229,6 +255,7 @@
* for the user's locale.
*
* @param key message key
+ *
* @return <code>true</code> if a message strings exists,
* <code>false</code> otherwise
*/
1.2 +92 -53 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/StrutsUtils.java
Index: StrutsUtils.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/StrutsUtils.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- StrutsUtils.java 12 Mar 2002 11:36:49 -0000 1.1
+++ StrutsUtils.java 2 Apr 2002 16:46:30 -0000 1.2
@@ -3,7 +3,7 @@
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -55,29 +55,29 @@
*
*/
-
package org.apache.velocity.tools.struts;
import java.util.Locale;
import java.util.Iterator;
+
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;
+
import javax.sql.DataSource;
import org.apache.struts.upload.MultipartRequestWrapper;
import org.apache.struts.util.MessageResources;
-import org.apache.struts.action.*; // expediancy
+import org.apache.struts.action.*;
/**
- * <p>A utility class to expose the Struts shared resources,
- * which are be stored in the application, session, or
- * request contexts, as appropriate. All methods are static.</p>
+ * <p>A package-internal utility class to expose the Struts shared
+ * resources. All methods are static.</p>
*
* <p>This class is provided for use by Velocity context tools
* that need access to Struts resources. By having all Struts-
@@ -90,19 +90,20 @@
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>, based
* on code by <a href="mailto:ted@husted.org">Ted Husted</a>
*
- * @version $Revision: 1.1 $
+ * @version $Revision: 1.2 $
*/
-public class StrutsUtils
+class StrutsUtils
{
-// ------------------------------------------------ Application Context
+// ------------------------------------- Struts ServletContext Resources ------
/**
- * Returns the <strong>default</strong> configured data source
- * (which must implement <code>javax.sql.DataSource</code>) or
- * <code>null</code> if not found.
+ * Returns the default configured data source (which must implement
+ * <code>javax.sql.DataSource</code>) or <code>null</code> if not found.
+ *
+ * @param application the servlet context
*/
- public static DataSource getDataSource(ServletContext application)
+ static DataSource getDataSource(ServletContext application)
{
if (application==null)
{
@@ -115,7 +116,7 @@
/* This method depends of features that are available in Struts 1.1+ only
- public static ActionMessages getActionMessages(ServletContext application)
+ static ActionMessages getActionMessages(ServletContext application)
{
if (application==null)
return null;
@@ -128,8 +129,10 @@
/**
* Returns the <code>org.apache.struts.action.ActionFormBeans</code>
* collection for this application or <code>null</code> if not found.
+ *
+ * @param application the servlet context
*/
- public static ActionFormBeans getActionFormBeans(ServletContext application)
+ static ActionFormBeans getActionFormBeans(ServletContext application)
{
if (application==null)
{
@@ -146,8 +149,9 @@
* logical name or <code>null</code> if not found.
*
* @param name logical name of the requested form bean definition
+ * @param application the servlet context
*/
- public static ActionFormBean getFormBean(String name, ServletContext application)
+ static ActionFormBean getFormBean(String name, ServletContext application)
{
ActionFormBeans formBeans = getActionFormBeans(application);
@@ -163,8 +167,10 @@
/**
* Returns the <code>org.apache.struts.action.ActionForwards</code>
* collection for this application or <code>null</code> if not found.
+ *
+ * @param application the servlet context
*/
- public static ActionForwards getActionForwards(ServletContext application)
+ static ActionForwards getActionForwards(ServletContext application)
{
if (application==null)
{
@@ -181,9 +187,9 @@
* or <code>null</code> if not found.
*
* @param name Logical name of the requested forwarding
+ * @param appplication the servlet context
*/
- public static ActionForward getActionForward(String name,
- ServletContext application)
+ static ActionForward getActionForward(String name, ServletContext application)
{
ActionForwards forwards = getActionForwards(application);
@@ -199,8 +205,10 @@
/**
* Returns the <code>org.apache.struts.action.ActionMappings</code>
* collection for this application or <code>null</code> if not found.
+ *
+ * @param application the servlet context
*/
- public static ActionMappings getActionMappings(ServletContext application)
+ static ActionMappings getActionMappings(ServletContext application)
{
if (application==null)
{
@@ -217,9 +225,9 @@
* or <code>null</code> if not found.
*
* @param path Request path for which a mapping is requested
+ * @param application the servlet context
*/
- public static ActionMapping getActionMapping(String path,
- ServletContext application)
+ static ActionMapping getActionMapping(String path, ServletContext application)
{
ActionMappings mappings = getActionMappings(application);
@@ -235,8 +243,10 @@
/**
* Returns the message resources for this application or <code>null</code>
* if not found.
+ *
+ * @param application the servlet context
*/
- public static MessageResources getMessageResources(ServletContext application)
+ static MessageResources getMessageResources(ServletContext application)
{
if (application==null)
{
@@ -253,8 +263,10 @@
* <code>null</code> if not found. The servlet mapping is
* either a path-mapped pattern (<code>/action/*</code>) or an
* extension mapped pattern (<code>*.do</code>).
+ *
+ * @param application the servlet context
*/
- public static String getServletMapping(ServletContext application)
+ static String getServletMapping(ServletContext application)
{
if (application==null)
{
@@ -266,16 +278,19 @@
}
-// ---------------------------------------------------- Session Context
+// -------------------------------------------- Struts Session Resources ------
/**
* Returns the <code>java.util.Locale</code> for the user. If a
* locale object is not found in the user's session, the system
* default locale is returned.
+ *
+ * @param request the servlet request
+ * @param session the HTTP session
*/
- public static Locale getLocale(HttpServletRequest request,
- HttpSession session)
+ static Locale getLocale(HttpServletRequest request,
+ HttpSession session)
{
Locale locale = null;
@@ -296,8 +311,10 @@
/**
* Returns the transaction token stored in this session or
* <code>null</code> if not used.
+ *
+ * @param session the HTTP session
*/
- public static String getToken(HttpSession session)
+ static String getToken(HttpSession session)
{
if (session==null)
{
@@ -308,14 +325,16 @@
}
-// ---------------------------------------------------- Request Context
+// -------------------------------------------- Struts Request Resources ------
/**
* Returns the <code>org.apache.struts.action.ActionErrors</code>
* object for this request or <code>null</code> if none exists.
+ *
+ * @param request the servlet request
*/
- public static ActionErrors getActionErrors(HttpServletRequest request)
+ static ActionErrors getActionErrors(HttpServletRequest request)
{
if (request==null)
{
@@ -330,8 +349,10 @@
* Returns the runtime Exception that may have been thrown by a
* Struts view tool or compatible presentation extension, and
* placed in the request. Returns <code>null</code> if none found.
+ *
+ * @param request the servlet request
*/
- public static Throwable getException(HttpServletRequest request)
+ static Throwable getException(HttpServletRequest request)
{
if (request==null)
{
@@ -346,8 +367,10 @@
/**
* Returns the multipart object for this request or <code>null</code>
* if none exists.
+ *
+ * @param request the servlet request
*/
- public static MultipartRequestWrapper getMultipartRequestWrapper(HttpServletRequest request)
+ static MultipartRequestWrapper getMultipartRequestWrapper(HttpServletRequest request)
{
if (request==null)
{
@@ -359,11 +382,13 @@
}
- /**
+ /**
* Returns the <code>org.apache.struts.ActionMapping</code> instance
* for this request or <code>null</code> if none exists.
+ *
+ * @param request the servlet request
*/
- public static ActionMapping getMapping(HttpServletRequest request)
+ static ActionMapping getMapping(HttpServletRequest request)
{
if (request==null)
{
@@ -378,9 +403,12 @@
/**
* Returns the <code>ActionForm</code> bean associated with
* this request of <code>null</code> if none exists.
+ *
+ * @param request the servlet request
+ * @param session the HTTP session
*/
- public static ActionForm getActionForm(HttpServletRequest request,
- HttpSession session)
+ static ActionForm getActionForm(HttpServletRequest request,
+ HttpSession session)
{
// Is there a mapping associated with this request?
ActionMapping mapping = (ActionMapping)request.getAttribute(Action.MAPPING_KEY);
@@ -410,13 +438,13 @@
}
-// ---------------------------------------------------- Struts Static Fields --
+// -------------------------------------------- Important Struts Constants ----
/**
* Returns the query parameter name under which a cancel button press
* must be reported if form validation is to be skipped.
*/
- public static String getCancelName()
+ static String getCancelName()
{
return org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY;
}
@@ -426,14 +454,14 @@
* Returns the query parameter name under which a transaction token
* must be reported.
*/
- public static String getTokenName()
+ static String getTokenName()
{
return org.apache.struts.taglib.html.Constants.TOKEN_KEY;
}
-// ------------------------------------------------ Utilities -----------------
+// ------------------------------------------------------------- Utilities ----
/**
@@ -446,8 +474,10 @@
* <li>If the resulting value does not start with a slash, then a
* slash is prepended.</li>
* </ul>
+ *
+ * @param action the name of an action as per struts-config.xml
*/
- public static String getActionMappingName(String action)
+ static String getActionMappingName(String action)
{
String value = action;
@@ -480,10 +510,14 @@
/**
* Returns the form action converted into a server-relative URI
* reference.
- */
- public static String getActionMappingURL(ServletContext application,
- HttpServletRequest request,
- String action)
+ *
+ * @param application the servlet context
+ * @param request the servlet request
+ * @param action the name of an action as per struts-config.xml
+ */
+ static String getActionMappingURL(ServletContext application,
+ HttpServletRequest request,
+ String action)
{
StringBuffer value = new StringBuffer(request.getContextPath());
@@ -537,18 +571,23 @@
/**
- * Returns a formatted error message. The value of message resource
+ * Returns a formatted error message. The error message is assembled from
+ * the following three pieces: First, value of message resource
* "errors.header" is prepended. Then, the list of error messages is
- * rendered. The value of message resource "errors.footer" is appended.
+ * rendered. Finally, the value of message resource "errors.footer" is appended.
+ *
+ * @param property the category of errors to markup and return
+ * @param request the servlet request
+ * @param session the HTTP session
+ * @param application the servlet context
*
- * @param property Property name
- * @return The formatted error message. If no error messages are queued,
+ * @returns The formatted error message. If no error messages are queued,
* an empty string is returned.
*/
- public static String errorMarkup(String property,
- HttpServletRequest request,
- HttpSession session,
- ServletContext application)
+ static String errorMarkup(String property,
+ HttpServletRequest request,
+ HttpSession session,
+ ServletContext application)
{
ActionErrors errors = getActionErrors(request);
if (errors == null)
1.1 jakarta-velocity-tools/struts/src/java/org/apache/velocity/tools/struts/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
These are Javadoc package comments.
-->
</head>
<body bgcolor="white">
Provides four context tools that integrate Velocity with the Jakarta
Struts framework.
<!--
##### THIS IS THE TEMPLATE FOR THE PACKAGE DOC COMMENTS. #####
##### TYPE YOUR PACKAGE COMMENTS HERE. BEGIN WITH A #####
##### ONE-SENTENCE SUMMARY STARTING WITH A VERB LIKE: #####
Provides for....
-->
<h2>Package Specification</h2>
<!--
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
-->
<h2>Related Documentation</h2>
<!--
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
<!-- Put @see and @since tags down here. -->
</body>
</html>
1.2 +72 -39 jakarta-velocity-tools/struts/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/xdocs/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 12 Mar 2002 11:36:49 -0000 1.1
+++ index.xml 2 Apr 2002 16:46:30 -0000 1.2
@@ -3,57 +3,90 @@
<document>
<properties>
- <title>Velocity for Struts</title>
+ <title>Project VelStruts</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
- <projectfile>xdocs/tools.xml</projectfile>
+ <projectfile>xdocs/menue.xml</projectfile>
</properties>
<body>
- <section name="Velocity for Struts - Reference Documentation">
+ <section name="Welcome to the VelStruts Project">
- <p>
- Velocity for Struts includes four context tools that provide access
- to Struts resources from within Velocity templates. This page is the
- starting point to the reference documentation for the context tools.
- Primary audience are the template designers.</p>
-
- <p>
- Velocity for Struts currently supports the follwing four tools:
- </p>
-
- <p>
- <strong><a href="tool-MessageTool.html">MessageTool</a></strong><br />
- Provides access to the Struts message resources for internationalized output.
- </p>
-
- <p>
- <strong><a href="tool-ErrorsTool.html">ErrorsTool</a></strong><br />
- Provides methods to work with Struts error messages.
- </p>
-
- <p>
- <strong><a href="tool-FormTool.html">FormTool</a></strong><br />
- Provides miscellaneous methods to work with forms and form beans in the context
- of Struts applications.
- </p>
-
- <p>
- <strong><a href="tool-LinkTool.html">LinkTool</a></strong><br />
- Provides methods to work with URIs.
- </p>
-
- <p>
- <strong>ActionMessagesTool</strong><br/>
- Provides methods to work with Struts action messages, a new feature in the
- upcoming 1.1. release. Will be added shortly.
- </p>
+ <p>VelStruts is a subproject of Velocity that aims to integrate Velocity
+ with the <a href="http://jakarta.apache.org/struts/">Jakarta Struts</a> Web application framework.</p>
+ <p>Struts is one of a growing number of <a href="http://jakarta.apache.org/velocity/powered.html#Frameworks%20that%20support%20Velocity">web application frameworks</a> that offer Velocity as a view layer technology. The integration with Struts offers now to Struts developers an alternative to JSP, the default view technology supported by Struts.</p>
+ <p>There are many different reasons why people are choosing to use Velocity as their view layer technology. The main advantages of Velocity compared to other view technologies are:</p>
+
+ <ul>
+ <li>Velocity enforces a clear separation of the view aspects of an application from the model and control aspects. This leads to clean application designs and a clear separation of the work of view designers and server developers.</li>
+ <li>The <a href="http://jakarta.apache.org/velocity/vtl-reference-guide.html">Velocity Template Language</a> (VTL) is a simple and easy to learn scripting language. With less than ten language directives, most people are up and running within a day.</li>
+ <li>Velocity is easy to extend with so called <i>Context Tools</i>. Context tools are easier to develop than customer tag libraries in JSP. Any class with public methods can serve as a context tool.</li>
+ <li>Velocity really shines when it comes to access to application data from within the templates. It handles access to objects and their methods very much like in scripting languages such as JavaScript and will feel familiar to template designers.</li>
+ <li>Velocity is an interpreted language. This leads to a simple development cycle. Template error can easily be localized and debugged.</li>
+ <li>Many users of Velocity have reported that the performance of Velocity is comparable if not sligthly better than JSP.</li>
+ <li>Last but not least, Velocity is backed by a very active and supportive community of users and developers.</li>
+ </ul>
+
+ <p>Velocity's capabilities reach well beyond the realm of web sites; it can generate SQL and PostScript and XML from templates. It can be used either as a standalone utility for generating source code and reports, or as an integrated component of other systems. To find out more about Velocity, please consult the <a href="http://jakarta.apache.org/velocity">Velocity Home Page</a>.</p>
+
+ <p>This is a work in progress. Frequent updates are expected. Please consult the <a href="#Download">Download section</a> for the current status of the project.</p>
+
+ </section>
+
+
+
+ <section name="Documentation">
+
+ <p>To get started using Velocity for Strust applications, we recommend that you first read this document. It gives an overview of the available documentation and points you to examples and the downloadable software.</p>
+
+ <p>If you are new to Velocity, it will be helpful to become somewhat familiar with Velocity before you continue:</p>
+
+ <ul>
+ <li><a href="http://jakarta.apache.org/velocity/">Velocity Home Page</a></li>
+ <li><a href="http://jakarta.apache.org/velocity/user-guide.html">Velocity User Guide</a></li>
+ <li><a href="http://jakarta.apache.org/velocity/vtl-reference-guide.html">Velocity Template Language Reference Guide</a></li>
+ </ul>
+
+ <p>To start working with Velocity and Struts we recommend that you download and try out the examples, browse the user's guide and the reference documentation.</p>
+
+ <ul>
+ <li><a href="#">Examples</a></li>
+ <li><a href="userguide.html">Velocity for Struts User's Guide</a></li>
+ <li><a href="index.html">Velocity for Struts Reference Documentation</a></li>
+ </ul>
+ <p>If this documentation does not answer all your questions, we would like to hear back from you. Post your question to the <a href="http://jakarta.apache.org/site/mail.html">Velocity users' mailing list</a>.</p>
</section>
+ <section name="Download">
+ <p>Velocity for Struts is currently in a pre-release phase. A release will be made as soon as the API is mature, the software stable and documentation is available. Available for download are several small example applications and the snapshop of the current source code from the CVS archive.</p>
+
+ <p><strong>Example Applications</strong></p>
+ <p>We have compiled several small example applications that demonstrate the use of Velocity as a view technology for Struts. These examples are delivered as a ready to run web application archive (.war) file. It includes the sources of all the examples but not the source of the Velocity servlet itself. These examples can serve as the starting point for your own experiments with Velocity for Struts.</p>
+
+ <p><a href="velstruts.war">Download Examples</a> (1.2 MB) [TODO: Where can be put the examples?]</p>
+
+ <p>Move the file into the <source>webapps</source> directory of a Tomcat server installation (or the corresponding directory of other servlet runners) and restart the server. The examples can now be accessed with a web browser on http://server:port/velstruts/. There are known issues with WebLogic 6.2. Please read the included README file if you are using such a server.</p>
+
+ <p><strong>Source Code</strong></p>
+ <p>The source code is currently only available via CVS in the
+<a href="http://cvs.apache.org/viewcvs/jakarta-velocity-tools/"> jakarta-velocity-tools</a> repository. You may it access it <a href="http://cvs.apache.org/viewcvs/jakarta-velocity-tools/">
+online</a> or with a <a href="http://jakarta.apache.org/getinvolved/cvsindex.html">cvs client</a>.</p>
+
+
+ <p>We would like to encourage interested developers to try and evaluate the software and give us feedback. We do not recommend to build production systems based on this software at this stage as the API may still change.</p>
+
+ </section>
+
+
+ <section name="License">
+
+ <p>This software is licensed under the <a href="http://jakarta.apache.org/velocity/license.html">Apache Software License</a></p>
+
+ </section>
</body>
</document>
1.2 +53 -12 jakarta-velocity-tools/struts/xdocs/tools.xml
Index: tools.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/struts/xdocs/tools.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tools.xml 12 Mar 2002 12:07:18 -0000 1.1
+++ tools.xml 2 Apr 2002 16:46:30 -0000 1.2
@@ -1,18 +1,59 @@
<?xml version="1.0"?>
-<project href="http://jakarta.apache.org/velocity">
+<document>
- <title>Struts</title>
- <logo href="http://jakarta.apache.org/velocity/images/logo.gif"> < :) /></logo>
+ <properties>
+ <title>Velocity for Struts</title>
+ <author email="sidler@apache.org">Gabriel Sidler</author>
+ <projectfile>../xdocs/vellibrary-menue.xml</projectfile>
+ </properties>
- <body>
+ <body>
- <menu name="Velocity for Struts" href="index.html">
- <item name="MessageTool" href="/tool-MessageTool.html"/>
- <item name="ErrorsTool" href="/tool-ErrorsTool.html"/>
- <item name="FormTool" href="/tool-FormTool.html"/>
- <item name="LinkTool" href="/tool-LinkTool.html"/>
- </menu>
+ <section name="VelStruts - Reference Documentation">
+
+ <p>
+ VelStruts includes four context tools that provide access
+ to Struts resources from within Velocity templates. This page is the
+ starting point to the reference documentation for the context tools.
+ Primary audience are the template designers.</p>
+
+ <p>
+ Velocity for Struts currently supports the follwing four tools:
+ </p>
+
+ <p>
+ <strong><a href="tool-MessageTool.html">MessageTool</a></strong><br />
+ Provides access to the Struts message resources for internationalized output.
+ </p>
+
+ <p>
+ <strong><a href="tool-ErrorsTool.html">ErrorsTool</a></strong><br />
+ Provides methods to work with Struts error messages.
+ </p>
+
+ <p>
+ <strong><a href="tool-FormTool.html">FormTool</a></strong><br />
+ Provides miscellaneous methods to work with forms and form beans in the context
+ of Struts applications.
+ </p>
+
+ <p>
+ <strong><a href="tool-LinkTool.html">LinkTool</a></strong><br />
+ Provides methods to work with URIs.
+ </p>
+
+ <p>
+ <strong>ActionMessagesTool</strong><br/>
+ Provides methods to work with Struts action messages, a new feature in the
+ upcoming 1.1. release. Will be added shortly.
+ </p>
+
+
+
+ </section>
+
+
+ </body>
+</document>
- </body>
-</project>
\ No newline at end of file
1.1 jakarta-velocity-tools/struts/xdocs/ErrorsTool.xml
Index: ErrorsTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>ErrorsTool</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="ErrorsTool Reference Documentation">
<p>
This tool deals with Struts error messages. Errors may stem from the validation
of a submitted form or from the processing of a request. If there are errors,
they are made available to the view to render. A few important aspects about errors
are:</p>
<ul>
<li>Error message strings are looked up in the message resources. Support
for internationalized messages is provided.</li>
<li>Error messages can have up to five replacement parameters.</li>
<li>Errors have an attribute <code>property</code> that describes the category of
error. This allows the view designer to place error messages precisely where an
error occurred. For example, errors that apply to the entire page can be rendered
at the top of the page, errors that apply to a specific input field can be rendered
next to this input field. Several methods of this tool provide a parameter
<code>property</code> that allows to select a specific category of errors to operate
on. Without the <code>property</code> parameter, methods operate on all error messages.</li>
</ul>
<p>See the Struts User's Guide, section
<a href="http://jakarta.apache.org/struts/userGuide/building_view.html">Building View Components</a>
for more information on this topic.</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-struts-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.struts.ErrorsTool</clazz>
<name>$errors</name>
<author email="sidler@teamup.com">Gabriel Sidler</author>
<config-example><tool>
<key>errors</key>
<class>org.apache.velocity.tools.struts.ErrorsTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="exist()">
<method name="exist()">
<abstract>
Returns true if there are errors queued, otherwise false.
</abstract>
<signature>
boolean exist()
</signature>
<signature>
boolean exist(String property)
</signature>
<parameters>
<parameter name="property">
The category of errors to check for.
</parameter>
</parameters>
<returns>
<code>true</code> if there error message queued. <code>false</code> otherwise.
</returns>
<description>
<p>Calling <code>exist()</code> without the <code>property</code> parameter checks for error messages of
any category. The <code>property</code> parameter can be used to limit the check to
error message of a specific category.</p>
<sourcecode>$errors.exist()
$errors.exist("password")
</sourcecode>
</description>
</method>
</section>
<section name="getSize()">
<method name="getSize()">
<abstract>
Returns the number of error messages queued.
</abstract>
<signature>
int getSize()
</signature>
<signature>
int getSize(String property)
</signature>
<parameters>
<parameter name="property">
The category of errors to operate on.
</parameter>
</parameters>
<returns>
The number of error messages.
</returns>
<description>
<p>Calling <code>getSize()</code> without the <code>property</code> parameter returns the total
number of queued error messages. The <code>property</code> parameter can be used to
obtain the number of queued error messages for a specific category.</p>
<sourcecode>$errors.getSize()
$errors.size
$errors.getSize("password")</sourcecode>
</description>
</method>
</section>
<section name="getAll()">
<method name="getAll()">
<abstract>
Returns a list of localized error messages for all errors queued.
</abstract>
<signature>
HashMap getAll()
</signature>
<returns>
If the message resources are lacking an error message for a
particular message key, the key itself is used as error message
and an error is logged.
</returns>
<description>
<p>The following example shows a macro to render the error messages:</p>
<sourcecode>#macro (errorMarkup)
#if ($errors.exist)
<ul>
#foreach ($e in $errors.all )
<li>$e</li>
#end
</ul>
#end
#end</sourcecode>
<p>This produces output similar to the following:</p>
<sourcecode><ul>
<li>The field Expiration Date is required.</li>
<li>The provided number is not a valid credit card number</li>
</ul></sourcecode>
</description>
</method>
</section>
<section name="get()">
<method name="get()">
<abstract>
Returns a list of localized error messages for a particular category
of errors.
</abstract>
<signature>
ArrayList get(String property)
</signature>
<parameters>
<parameter name="property">
The category of errors to return.
</parameter>
</parameters>
<returns>
A <code>java.util.ArrayList</code> of <code>java.lang.String</code>.
If no error messages exist for the specified category,
<code>null</code> is returned.
If the message resources are lacking an error message for a
particular message key, the key itself is used as error message
and an error is logged.
</returns>
<description>
<p>The following example shows a macro to render the error messages for a
particular category of errors:</p>
<sourcecode>#macro (errorMarkup $property)
#if ($errors.exist($property))
<ul>
#foreach ($er in $errors.get($property) )
<li>$er</li>
#end
</ul>
#end
#end</sourcecode>
<p>This produces output similar to the following:</p>
<sourcecode><ul>
<li>The field Expiration Date is required.</li>
<li>The provided number is not a valid credit card number</li>
</ul></sourcecode>
</description>
</method>
</section>
<section name="getMsgs()">
<method name="getMsgs()">
<abstract>
Renders the queued errors messages.
</abstract>
<signature>
String getMsgs()
</signature>
<signature>
String getMsgs(String property)
</signature>
<parameters>
<parameter name="property">
The category of errors messages to render.
</parameter>
</parameters>
<returns>
The formatted error messages. If no errors are queued, an
empty <code>String</code> is returned.
</returns>
<description>
<p>This method renders the queued error messages as a list. If the method
is called without a parameter, all queued errors are rendered. With the
parameter <code>property</code> the list of rendered messages can be
limited to a specific category of errors. Error message texts
are looked up in the message resources. If a message text
cannot be found, the message key will be displayed instead.</p>
<p>The method expects a message header and a message footer
to be defined in the message resources. The corresponding
message keys are <code>errors.header</code> and
<code>errors.footer</code>.</p>
<p>Assuming that the message resources contain the following
definitions:</p>
<sourcecode>errors.header=Please correct the following errors:<ul>
errors.footer=</ul>
error01=<li>The field Expiration Date is required.</li>
error02=<li>The input is not a valid credit card number.</li>
...</sourcecode>
<p>an error message would be rendered as follows:</p>
<sourcecode>Please correct the following errors before proceeding:<ul>
<li>The field Expiration Date is required.</li>
<li>The input is not a valid credit card number.</li>
</ul></sourcecode>
</description>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/struts/xdocs/FormTool.xml
Index: FormTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>FormTool</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="FormTool Reference Documentation">
<p>Struts has support to parse incoming HTTP requests and populate a Java bean
with the submitted request parameters. The same Java bean is used to populate
forms with initial values. Additionally, a hook allows the application developer
to include automatic form validation code.</p>
<p>FormTool provides miscellaneous methods to work with forms and form bean in
the context of Struts applications.</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-struts-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.struts.FormTool</clazz>
<name>$form</name>
<author email="sidler@teamup.com">Gabriel Sidler</author>
<config-example><tool>
<key>form</key>
<class>org.apache.velocity.tools.struts.FormTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="getBean()">
<method name="getBean()">
<abstract>
Retrieve and return the form bean associated with this request.
</abstract>
<signature>
ActionForm getBean()
</signature>
<returns>
The <code>ActionForm</code> associated with this request/session or
<code>null</code> if there is no form bean associated with this mapping.
</returns>
<description>
<p>This is a convenience method. The form bean is automatically
available in the Velocity context under the name defined in the
Struts configuration.</p>
<p>If the form bean is used repeatedly, it is recommended to create a
local variable referencing the bean rather than calling getBean()
multiple times.</p>
<sourcecode>## Populating an input field with a default value
<input type="text" name="username" value="$form.getBean().username">
## The same can be written as
<input type="text" name="username" value="$form.bean.username">
## For repeated use create a local reference
#set ($defaults = $form.bean)
<input type="text" name="username" value="$defaults.username">
## Accessing the form using the form name defined in struts-config.xml
## Velocity searches the request and session attributes for loginForm
<input type="text" name="username" value="$loginForm.username"></sourcecode>
</description>
</method>
</section>
<section name="getCancelName()">
<method name="getCancelName()">
<abstract>
Returns the query parameter name under which a cancel button press
must be reported if form validation is to be skipped.
</abstract>
<signature>
int getCancelName()
</signature>
<returns>
The value of <code>org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY</code>
</returns>
<description>
<p>If a request contains a request parameter with key equal to the return value
of this method, then automatic form validation is skipped. A typical application
case is to use this magic string for the name attribute of a cancel button in a form.
If this button is pressed, automatic form validation is skipped. If automatic form
validation is not used, this magic string is irrelevant.</p>
<sourcecode>## A cancel button
<input type="submit" name="$form.getCancelName()" value="Cancel">
## Can also be written as
<input type="submit" name="$form.cancelName()" value="Cancel"></sourcecode>
<p>This produces the following output:</p>
<sourcecode><input type="submit" name="org.apache.struts.taglib.html.CANCEL" value="Cancel"></sourcecode>
</description>
</method>
</section>
<section name="getToken()">
<method name="getToken()">
<abstract>
Retrieves and returns the transaction control token for this session.
</abstract>
<signature>
String getToken()
</signature>
<returns>
The token <code>String</code> or <code>null</code> if no token exists.
</returns>
<see>
Method <a href="#getTokenName()"><code>getTokenName()</code></a> for examples.
</see>
</method>
</section>
<section name="getTokenName()">
<method name="getTokenName()">
<abstract>
Returns the query parameter name under which a transaction token
must be reported.
</abstract>
<signature>
int getTokenName()
</signature>
<returns>
The value of <code>org.apache.struts.taglib.html.Constants.TOKEN_KEY</code>
</returns>
<see>
<a href="http://jakarta.apache.org/struts/api/org/apache/struts/action/Action.html">
JavaDoc of class <code>org.apache.struts.action.Action</code></a> for more information on the
transaction token mechanism (I don't know of any better documentation of this Struts
feature).
</see>
<description>
<sourcecode>## A hidden form field with the transaction token
<input type="hidden" name="$form.getTokenName()" value="$form.getToken()">
## Can also be written as
<input type="hidden" name="$form.tokenName()" value="$form.token()"></sourcecode>
<p>This produces output similar to:</p>
<sourcecode><input type="hidden" name="org.apache.struts.taglib.html.TOKEN"
value="84c29b4dea56ecf69524ef6b965c5e80"></sourcecode>
</description>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/struts/xdocs/LinkTool.xml
Index: LinkTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>LinkTool</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="LinkTool Reference Documentation">
<p>The LinkTool provides methods to work with URIs:</p>
<ul>
<li>translate logical names (Struts forwards, actions ) to URI references</li>
<li>construct and encode query strings</li>
<li>retrieve server, port and path info for the current request</li>
</ul>
<p>The LinkTool is somewhat special in that many of its methods return
a new instance of LinkTool. This facilitates greatly the repeated use
of the LinkTool in Velocity and leads to an elegant syntax.</p>
<p>I've been struggling a bit to find the right terminology for the things
that this tool works with. Based on document
<a href="http://www.w3.org/Architecture/Terms">http://www.w3.org/Architecture/Terms</a>,
I have used:</p>
<dl>
<dt>URI</dt>
<dd>To refer to the full, absolute address of web resources, e.g. static documents
or abstract resources like dynamically generated content.
Example: <code>http://myserver.org/myapp/templates/index.html</code></dd>
<dt>URI Reference</dt>
<dd>To refer to partial and relative URIs that reference a URI. Example:
<code>templates/index.html</code>. </dd>
<dt>URL</dt>
<dd>Not used here.</dd>
</dl>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-struts-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.struts.LinkTool</clazz>
<name>$link</name>
<author email="sidler@teamup.com">Gabriel Sidler</author>
<author email="nathan@esha.com">Nathan Bubna</author>
<config-example><tool>
<key>link</key>
<class>org.apache.velocity.tools.struts.LinkTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="setURI()">
<method name="setURI()">
<abstract>
Returns a copy of this LinkTool instance with the given URI reference.
</abstract>
<signature>
LinkTool setURI(String uri)
</signature>
<parameters>
<parameter name="uri">
URI reference to set. The URI reference can be absolute
(<code>http://www.mydomain.com/myapp/templates/index.html</code>),
server-relative (<code>/myapp/templates/index.html</code>),
relative (<code>templates/index.html</code>)
and may contain query strings (<code>templates/index.html?key1=value1&key2=value2</code>).
</parameter>
</parameters>
<returns>
A new instance of <code>LinkTool</code>.
</returns>
<description>
<p>No conversions are applied to the given URI reference. This method will
overwrite any previously set URI reference but will copy query
data set with method <code>setQueryData()</code>.</p>
<p>Note: It is Struts' recommended practice to link to
actions or forwards, but not directly to templates as this
bypassed the Struts controller. Consider using setAction()
or setForward() instead.</p>
</description>
<sourcecode>## a relative reference
$link.setURI("index.html").addQueryData("key1","val 1")
## a server-relative reference
$link.setURI("/myapp/index.vm").addQueryData("key1","val 1")
## an absolute reference
$link.setURI("http://myserver.org/myapp/index.vm")
.addQueryData("key1", "val 1")
## a reference with a query string
$link.setURI("/myapp/index.vm?key0=val0")
.addQueryData("key1", "val 1")
</sourcecode>
<p>This produces:</p>
<sourcecode>index.vm/key1=val+1
/myapp/index.vm/key1=val+1
http://myserver.org/myapp/index.vm?key1=val+1
/myapp/index.vm?key0=val0&key1=val+1</sourcecode>
</method>
</section>
<section name="setAction()">
<method name="setAction()">
<abstract>
Returns a copy of this LinkTool instance with the given action path
converted into a server-relative URI reference.
</abstract>
<signature>
LinkTool setAction(String action)
</signature>
<parameters>
<parameter name="action">
An action path as defined in struts-config.xml, e.g. <code>/logon</code>.
</parameter>
</parameters>
<returns>
A new instance of <code>LinkTool</code>.
</returns>
<description>
<p>The action name is translated into a server-relative URI reference. The method does
not check if the specified action has been defined. It will overwrite any
previously set URI reference but will copy the query string.</p>
</description>
<sourcecode>## a form tag
<form name="form1" action="$link.setAction("demo")"></sourcecode>
<p>Produces something like:</p>
<sourcecode><form name="form1" action="/myapp/demo.do"></sourcecode>
</method>
</section>
<section name="setForward()">
<method name="setForward()">
<abstract>
Returns a copy of this LinkTool instance with the given global
forward name converted into a server-relative URI reference.
</abstract>
<signature>
LinkTool setForward(String forward)
</signature>
<parameters>
<parameter name="forward">
The name of a global forward as defined in struts-config.xml.
</parameter>
</parameters>
<returns>
A new instance of <code>LinkTool</code> or <code>null</code> if the
parameter does not map to a valid forward.
</returns>
<description>
<p>The global forward name is translated into a server-relative
URI reference. This method will overwrite any previously set URI
reference but will copy the query string.</p>
</description>
<sourcecode>## a forward
<a href="$link.setForward("start").addQueryData("key1","val 1")">
My Link</a></sourcecode>
<p>Produces something like:</p>
<sourcecode><a href="/myapp/templates/index.vm?key=val+1">My Link</a></sourcecode>
</method>
</section>
<section name="setAbsolute()">
<method name="setAbsolute()">
<abstract>
Returns a copy of this LinkTool instance with the specified context-relative
URI reference converted to a server-relative URI reference.
</abstract>
<signature>
LinkTool setAbsolute(String uri)
</signature>
<parameters>
<parameter name="uri">
A context-relative URI reference, i.e. a URI reference that is relative to the URI
used to address this web application.
</parameter>
</parameters>
<returns>
A new instance of <code>LinkTool</code>.
</returns>
<description>
<p>The specified context-relative URI reference is converted to a server-relative URI reference.
This method will overwrite any previously set URI reference but will copy the query string.</p>
<sourcecode>## a context-relative hyperlink
<a href="$link.setAbsolute("templates/index.vm")
.addQueryData("key1","val 1")">My Link</a></sourcecode>
<p>Produces something like:</p>
<sourcecode><a href="/myapp/templates/index.vm?key=val+1">My Link</a></sourcecode>
</description>
</method>
</section>
<section name="addQueryData()">
<method name="addQueryData()">
<abstract>
Adds a key=value pair to the URI reference.
</abstract>
<signature>
LinkTool addQueryData(String key, Object value)
</signature>
<parameters>
<parameter name="key">
Key (name) of query parameter.
</parameter>
<parameter name="value">
Value of the query parameter. The string representation of this object is
added to the query data.
</parameter>
</parameters>
<returns>
A new instance of <code>LinkTool</code>.
</returns>
<description>
<p>Adds a key=value pair to the query data. This returns a new LinkTool
containing both a copy of this LinkTool's query data and the new data.
This makes repeated use in Velocity templates easy. Query data is
URL-encoded before it is appended.</p>
<p>See <a href="#setURI()">method setURI()</a> for examples.</p>
</description>
</method>
</section>
<section name="getURI()">
<method name="getURI()">
<abstract>
Returns the current URI reference.
</abstract>
<signature>
LinkTool getURI()
</signature>
<returns>
Returns the current URI reference as set by one of the methods
setURI(), setAction(), setForward() or setAbsolute(). Any conversions
have been applied. The returned URI reference does not included query data that was
added with method addQueryData().
</returns>
<see>
Method <a href="#getQueryData()"><code>getQueryData()</code></a> to retrieve
query data only. Method <a href="#toString()"><code>toString()</code></a> to
retrieve the URI reference including all query data.
</see>
<description>
<sourcecode>#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
<a href="$l.getURI()">My Link</a></sourcecode>
<p>Produces something like:</p>
<sourcecode><a href="/myapp/templates/index.vm">My Link</a></sourcecode>
</description>
</method>
</section>
<section name="getQueryData()">
<method name="getQueryData()">
<abstract>
Returns this instance's query data.
</abstract>
<signature>
String getQueryData()
</signature>
<returns>
This instance's query data as set by the method
<a href="#setQueryData()"><code>setQueryData()</code></a>. The
returned String is URL-encoded, e.g. "key=value&foo=this+is+encoded".
</returns>
<description>
<sourcecode>#set ($l = $link.setForward("start").addQueryData("key1","val 1"))
$l.getQueryData()</sourcecode>
<p>Produces:</p>
<sourcecode>key1=val+1</sourcecode>
</description>
</method>
</section>
<section name="getContextURI()">
<method name="getContextURI()">
<abstract>
Returns the URI that addresses this web application.
</abstract>
<signature>
String getContextURI()
</signature>
<returns>
Returns the URI reference that addresses this web application, e.g.
"http://myserver.net/myapp". This string does not end with a "/".
</returns>
<description>
<p>Note! This will not represent the URI reference or
query data set for this LinkTool instance.</p>
<sourcecode>$link.getContextURI()</sourcecode>
<p>Produces something like:</p>
<sourcecode>http://myserver.net/myapp</sourcecode>
</description>
</method>
</section>
<section name="getContextPath()">
<method name="getContextPath()">
<abstract>
Returns the context path that addresses this web application.
</abstract>
<signature>
String getContextPath()
</signature>
<returns>
The context path that addresses this web application, e.g.
<code>/myapp"</code>. This string starts with a "/" but does
not end with a "/".
</returns>
<description>
<p> Note! This will not represent the URI reference or query
data set for this LinkTool instance.</p>
<sourcecode>$link.getContextPath()</sourcecode>
<p>Produces something like:</p>
<sourcecode>/myapp</sourcecode>
</description>
</method>
</section>
<section name="getBaseRef()">
<method name="getBaseRef()">
<abstract>
Returns the full URI of this template.
</abstract>
<signature>
String getBaseRef()
</signature>
<returns>
The full URI of this template without any query data.
e.g. <code>http://myserver.net/myapp/templates/View.vm</code>.
</returns>
<description>
<p>Note! The returned String will not represent the URI reference or query
data set for this LinkTool instance. A typical application of this method
is with the HTML base tag.</p>
<sourcecode>## a base tag
<base href="$link.getBaseRef()"></sourcecode>
<p>Produces something like:</p>
<sourcecode><base href="http://myserver.net/myapp/templates/index.vm"></sourcecode>
</description>
</method>
</section>
<section name="toString()">
<method name="toString()">
<abstract>
Returns the full URI that has been constructed.
</abstract>
<signature>
String toString()
</signature>
<returns>
The full URI that has been built with this tool
e.g. <code>/myapp/stuff/View.vm?id=42&type=blue</code>.
</returns>
<description>
<p>Typically it is not necessary to call this method explicitly.
Velocity will call the toString() method automatically to
obtain a representable version of objects.</p>
<sourcecode><a href="$link.setAction("demo").addQueryString("key1", "val 1")">
My Link</a></sourcecode>
<p>Produces something like:</p>
<sourcecode><a href="/myapp/demo.do?key1=val+1">My Link</a></sourcecode>
</description>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/struts/xdocs/MessageTool.xml
Index: MessageTool.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>MessageTool</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>../xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="MessageTool Reference Documentation">
<p>
The MessageTool is used to render internationalized message strings. Source
of the strings are the message resource bundles of the Struts framework. The
following methods operate on these message resources.
</p>
<toolinfo>
<version>@@@version@@@, @@@date@@@</version>
<jar>velocity-tools-struts-@@@version@@@.jar</jar>
<clazz>org.apache.velocity.tools.struts.MessageTool</clazz>
<name>$msg</name>
<author email="sidler@teamup.com">Gabriel Sidler</author>
<config-example><tool>
<key>msg</key>
<class>org.apache.velocity.tools.struts.MessageTool</class>
</tool></config-example>
</toolinfo>
<methods/>
</section>
<section name="get()">
<method name="get()">
<abstract>
Looks up and returns the localized message for the specified key.
</abstract>
<signature>
String get(String key)
</signature>
<signature>
String get(String key, Object args[])
</signature>
<signature>
String get(String key, ArrayList args)
</signature>
<parameters>
<parameter name="key">
Message key.
</parameter>
<parameter name="args">
Replacement parameters for this message. Typically an array of
Strings or an ArrayList of Strings.
</parameter>
</parameters>
<returns>
The localized message for the specified key. Returns null if no
message exists for the key passed.
</returns>
<see>
Struts user's guide on
<a href="http://jakarta.apache.org/struts/userGuide/building_view.html#i18n">
Internationalized Messages</a>.
</see>
<description>
<p>The user's locale is consulted to determine the language of the
message. The second and third signature take a list of up to five
replacement parameters. The second signature is provided for compatibility
with existing applications. The third signature is Velocity-friendlier.</p>
<p>Assuming that the message resource files contain the following messages:</p>
<sourcecode>title=Welcome to Velocity for Struts
test=This message has five replacement parameters: {0}, {1}, {2}, {3}, {4}</sourcecode>
<p>then the following Velocity script:</p>
<sourcecode>$msg.get("title")
$msg.title
$msg.get("test", ["bear", "wolf", "tiger"])</sourcecode>
<p>produces this output:</p>
<sourcecode>Welcome to Velocity for Struts
Welcome to Velocity for Struts
This message has five replacement parameters: bear, wolf, tiger, {3}, {4}</sourcecode>
</description>
</method>
</section>
<section name="exists()">
<method name="exists()">
<abstract>
Checks if a message string for a specified message key exists
for the user's locale.
</abstract>
<signature>
boolean exists(String key)
</signature>
<parameters>
<parameter name="key">
Message key.
</parameter>
</parameters>
<returns>
<code>true</code> if a message string for the specified message
key exists for the user's locale. <code>false</code> otherwise.
</returns>
<description>
<sourcecode>$msg.exists("title")</sourcecode>
</description>
</method>
</section>
<section name="getLocale()">
<method name="getLocale()">
<abstract>
Returns the user's locale. If a locale is not found, the default
locale is returned.
</abstract>
<signature>
Locale getLocale()
</signature>
<returns>
An instance of class <code>java.util.Locale</code>.
</returns>
<description>
<sourcecode>$msg.getLocale()
$msg.locale
$msg.getLocale().getDisplayLanguage()</sourcecode>
<p>produces:</p>
<sourcecode>en
en
English</sourcecode>
<p>The returned object of class <code>Locale</code> is automatically rendered by Velocity by
calling its <code>toString()</code> method. The third example calls method
<code>getDisplayLanguage()</code> of class <code>Locale</code></p>
</description>
</method>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/struts/xdocs/menue.xml
Index: menue.xml
===================================================================
<?xml version="1.0"?>
<project href="http://jakarta.apache.org/velocity">
<title>Math</title>
<logo href="http://jakarta.apache.org/velocity/images/logo.gif"> < :) /></logo>
<body>
<uplink name="VelTools Home" href="docs/index.html" alt="top"/>
<menu name="About VelStruts">
<item name="Overview" href="struts/docs/index.html"/>
<item name="Documentation" href="struts/docs/index.html#Documentation"/>
<item name="Download" href="struts/docs/index.html#Download"/>
<item name="License" href="struts/docs/index.html#License"/>
</menu>
<menu name="VelStruts User Guide">
<item name="Overview" href="struts/docs/userguide.html"/>
<item name="Documentation" href="struts/docs/userguide.html#Documentation"/>
<item name="Model 2 Applications" href="struts/docs/userguide.html#Model 2 Applications"/>
<item name="Velocity Context" href="struts/docs/userguide.html#Velocity Context"/>
<item name="Context Tools" href="struts/docs/userguide.html#Context Tools"/>
<item name="Velocity and JSP" href="struts/docs/userguide.html#Velocity and JSP"/>
<item name="Velocity vs. JSP" href="struts/docs/userguide.html#Velocity vs. JSP"/>
<item name="Velocity Configuration" href="struts/docs/userguide.html#Velocity Configuration"/>
<item name="Velocity Configuration" href="struts/docs/userguide.html#Velocity Configuration"/>
</menu>
<menu name="VelStruts Reference Doc" href="struts/docs/tools.html" target="velLibrary">
<item name="ErrorsTool" href="struts/docs/ErrorsTool.html" target="velLibrary"/>
<item name="FormTool" href="struts/docs/FormTool.html" target="velLibrary"/>
<item name="LinkTool" href="struts/docs/LinkTool.html" target="velLibrary"/>
<item name="MessageTool" href="struts/docs/MessageTool.html" target="velLibrary"/>
</menu>
</body>
</project>
1.1 jakarta-velocity-tools/struts/xdocs/quotes.txt
Index: quotes.txt
===================================================================
From: "Matt Ho" <ma...@xtreme.com>
To: "'Struts Users Mailing List'" <st...@jakarta.apache.org>
Subject: RE: Velocity-Tools / Struts
Date: Tue, 19 Feb 2002 18:57:02 -0800
We've been using Struts/Velocity for some time now and we find it to be
an extremely well matched combination. One of the main advantages of
Velocity is that the syntax is incredibly easy. I can explain it to a
designer who has never seen it before and expect them to be useful
within an hour.
One of the nicest things it enforces is the separation of presentation
layer and business logic. It removes the desire to "fix" problems but
just putting a small change into the JSP via scriptlets. It also makes
the code a _lot_ more readable which also reduces the development time.
> i have been looking at velocity periodically for a few months now, and
> although i understand what it is trying to do (define a clearer
separation
> between controller and view) i felt that its big disadvantage was that
it
> introduced another language/syntax for a developer/designer to learn.
In
> view of this i decided to stay with struts, and occasionally resort to
> using
> java scriptlets in my applications !-)
--
Matt Ho
Principal
Indigo Egg, Inc.
Providing VoiceXML Professional Services
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
1.1 jakarta-velocity-tools/struts/xdocs/userguide.xml
Index: userguide.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Velocity for Struts - User Guide</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>xdocs/menue.xml</projectfile>
</properties>
<body>
<section name="Velocity for Struts User Guide">
<p>
This user guide describes how Struts application are built using Velocity
as the view technologie. Application examples illustrate the different
steps involved in building an application. This guide addresses both,
the frontend designer as well as the backend developer. The section <a href="#Velocity vs. Struts">Velocity vs. JSP</a> is designed to help existing Struts/Velocity users get started with Velocity. This document is not a general introduction to Velocity. If you are new to Velocity, please consult <a href="http://jakarta.apache.org/velocity/getting-started.html">Getting Started</a>.
</p>
<p>
[Issues to be addressed here:
<ul>
<li><strong>Model 2 Application</strong> Concepts, links to relevant reading,
help people think the right way about Velocity/Struts, emphasize that model 1
applications are not possible with Velocity as the view technologie.</li>
<li><strong>Velocity Context</strong> What is it, access to the
request/session and application attributes, how to pass data from model to
view.</li>
<li><strong>Context Tools</strong> How to load context tools, how to access
context tools, the toolbox.</li>
<li><strong>Velocity Configuration</strong> Logging, log details, debugging.</li>
<li><strong>Velocity and JSP</strong> Explain how to develop application with
mixed view technologies.</li>
<li><strong>Velocity vs. JSP</strong> A comparison of the Struts custom JSP tags
with the Velocity tools. This should help JSP developers familiar with the
custom tag libs get started with Velocity as a view technology.</li>
</ul>
]
</p>
</section>
<section name="Documentation">
<p>Before diving into the details of Velocity for Struts, I would like to draw your attention to the available reference documentation that you will need:</p>
<ul>
<li><a href="http://jakarta.apache.org/velocity/user-guide.html">Velocity User's Guide</a></li>
<li><a href="http://jakarta.apache.org/velocity/vtl-reference-guide.html">Velocity Template Language Reference Guide</a></li>
<li><a href=".......struts/docs/index.html">Velocity Context Tools for Struts</a></li>
</ul>
</section>
<section name="Model 2 Architectures">
<p>In the JSP world, the terms <i>Model 1</i> architectures and <i>Model 2</i> architectures were coined to refer to particular ways of designing and building web applications. It is important that you understand the fundamental difference between these two architectural approaches. JSP can be used in applications designed after Model 1 architectures as well as Model 2 architectures. Velocity cannot. It has been designed very consciouly as a view technology for web application architectures based on Model 2.</p>
<p><strong>Model 1 Architectures</strong></p>
<p>In a Model 1 architecture, the JSP page alone is responsible for processing the incoming request and replying back to the client. Using MVC speak, the controller and the view are implemented within the same JSP page. Model 1 architecture are suitable only for very simple application scenarios. In medium size to large projects, the lack of a separation between business logic and view oftentimes leads to difficulties in separating the web designer's works from the server developer's work and causes project management headaches.</p>
<p><strong>Model 2 Architectures</strong></p>
<p>In a Model 2 architecture, the control component, including business logic, data access and request handling, are strictly separated from the view component. The view does not contain any processing logic. It is simply responsible for displaying the data that resulted from processing the request. This may be a static page or more often a dynamic page. Such an approach typically facilitates are clear delineation of the roles and responsibilities of the developers and the web designers. The more complex an application, the greater the benefits of using a Model 2 architecture will be.</p>
<p>The paper <a href="http://www.javaworld.com/javaworld/jw-12-1999/jw-12-ssj-jspmvc.html">Understanding JavaServer Pages Model 2 Architecture</a> provides a more in-depth discussion of Model 1 and Model 2 architectures.</p>
<p><strong>What does this mean?</strong></p>
<p>The Struts framework can support both architectures, but all the facilities it provides are really aimed at making the construction of Model 2 applications easy. Velocity on the other hand cannot be used to build Model 1 architectures. It lacks the libraries to support such a design. I am emphasizing this here because I want to make sure that you have all the relevant facts before you decide on Velocity for your projects. This is especially important for people considering to port existing application built on the Model 1 approach or a mixed Model 1 / Model 2 approach. The good news is, that today for any serious application Model 2 is state of the art and Velocity will support you very well on that route.</p>
</section>
<section name="Building Applications">
<p>This section introduces you to the key concepts of building Struts applications with Velocity as the view technology.</p>
<subsection name="Velocity Template Language">
<p>Velocity is a template engine implemented in Java. Velocity templates typically are HTML pages with embedded scripts (although Velocity has been used for many other application scenarios). Scripts are written in the Velocity Template Language (VTL). Following is a simple example of a HTML view with embedded VTL statements:</p>
<sourcecode>
<HTML>
<BODY>
<h2>Order Confirmation</h2>
<h3>Delivery Adress:</h3><br>
Name: $customer.name<br>
Street: $customer.street<br>
City: $customer.zip $customer.city
<h3>Ordered Items</h3><br>
<table>
#foreach( $item in $order.items )
<tr>
<td>$item.quantity</td>
<td>$item.description</td>
</tr>
#end
</table>
</body>
</html>
</sourcecode>
<p>When processed this will produce output similar to the following.</p>
<sourcecode>
<HTML>
<BODY>
<h2>Order Confirmation</h2>
<h3>Delivery Adress:</h3><br>
Name: Peter Pan<br>
Street: Crain St. 10<br>
City: 60201 Evanston IL
<h3>Ordered Items</h3><br>
<table>
<tr>
<td>1</td>
<td>Hair Dryer, Philips, 1000W, white</td>
</tr>
<tr>
<td>1</td>
<td>Kitchen Mixer, Betty Bossy, 240W, black</td>
</tr>
</table>
</body>
</html>
</sourcecode>
<p>VTL has been designed from the ground up as a simple template scriting language aimed at view designers. With less than ten supported directives it is easy to learn. In fact, most people are up and productive within less than a day.</p>
<p>As opposed to JSP, Velocity does not allow Java scriptlets. Java scriptlets tempt designers to put business logic into the templates and have proven many times to be problematic rather than useful. Using VTL, Java scriptlets can be avoided alltogether.</p>
<p>Please consult the following two documents for an in-depth coverage of VTL:</p>
<ul>
<li><a href="http://jakarta.apache.org/velocity/user-guide.html">Velocity User's Guide</a></li>
<li><a href="http://jakarta.apache.org/velocity/vtl-reference-guide.html">VTL Reference Guide</a></li>
</ul>
<p>To bring Velocity templates really to live, application data needs to be fed. The next section describes how this is done.</p>
</subsection>
<subsection name="Passing Application Data">
<p>The main purpose of Velocity in a web application is typically to merge HTML templates with dynamic application data to generate dynamic views. An essential aspect of Velocity is therefore the mechanism that allows the application controller (in MVC speak) to pass application data to the template.</p>
<p>In this context it is important to understand the relationship between a Struts-based application and the Velocity template engine. Both, a Struts application as well as the Velocity template engine are each a Java Servlet. A request to the Struts application is processed and finally handed over, along with application data, to the Velocity servlet to generate the view. I'd like to add here that the Velocity servlet is not exclusively tied to the Struts application. It can serve requests from web clients directly or any other servlet application as well. Technically, Struts hands over a request to Velocity through method <code>forward</code> of <code>javax.servlet.RequestDispatcher</code>. </p>
<p>Application data is passed from the Struts servlet to the Velocity servlet as attributes of either the servlet request, the servlet session or the servlet context </p>
<p></p>
<p></p>
<p></p>
<p>Since the Struts framework was designed to be used with several different view techhnologies (JSP, template engines, XML/XSL, JSF, etc.) it makes the
has defined an approach that is based on the Servlet API.
</p>
</subsection>
<subsection name="Access to Struts Resources">
<p>asdfadffadsff</p>
</subsection>
</section>
<section name="Context Tools">
</section>
</body>
</document>
1.2 +28 -4 jakarta-velocity-tools/view/README.txt
Index: README.txt
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/README.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README.txt 3 Jan 2002 20:21:28 -0000 1.1
+++ README.txt 2 Apr 2002 16:46:31 -0000 1.2
@@ -1,5 +1,29 @@
-view
-====
+R E A D M E
+===========
-View is a general purpose Velocity template rendering servlet
-with toolbox support.
+This package contains a standalone servlet that can be used for template
+rendering in Web applications. It offers automatic population of
+the Velocity context and automatic, configurable management of context
+tools. Other efforts within this package are the development of a
+toolbox manager and the definition of a set of interfaces for context
+tools, thereby enabling the efficient handling and reuse of context
+tools.
+
+
+Build and JAR
+-------------
+An ant script is provided to build and jar the package.
+
+> ant compile
+> ant jar
+
+
+Documentation
+-------------
+To generate the documentation for this package, follow these steps:
+
+> ant docs
+> ant javadocs
+> ant javadocs-velservlet
+
+Then look for the generated documentation in the 'doc' subdirectory.
1.5 +54 -14 jakarta-velocity-tools/view/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/build.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- build.xml 8 Jan 2002 10:37:06 -0000 1.4
+++ build.xml 2 Apr 2002 16:46:31 -0000 1.5
@@ -22,7 +22,7 @@
<property name="project.title" value=""/>
<!-- The current version number of this component -->
- <property name="project.version" value="0.3"/>
+ <property name="project.version" value="0.4"/>
<!-- The base directory for compilation targets -->
<property name="build.home" value="target"/>
@@ -70,8 +70,7 @@
<!-- ================================================================== -->
<!-- I N I T -->
<!-- ================================================================== -->
- <target name="init"
- description="Initialize and evaluate conditionals">
+ <target name="init">
<echo message="-------- ${project.name} ${project.version} --------"/>
<filter token="name" value="${project.name}"/>
<filter token="version" value="${project.version}"/>
@@ -81,20 +80,19 @@
<!-- ================================================================== -->
<!-- P R E P A R E -->
<!-- ================================================================== -->
- <target name="prepare" depends="init"
- description="Prepare build directory">
+ <target name="prepare" depends="init">
<mkdir dir="${build.home}"/>
<mkdir dir="${build.home}/classes"/>
<mkdir dir="${build.home}/conf"/>
<mkdir dir="${build.home}/javadoc"/>
+ <mkdir dir="${docs.dest}/javadoc-velservlet"/>
</target>
<!-- ================================================================== -->
<!-- S T A T I C -->
<!-- ================================================================== -->
- <target name="static" depends="prepare"
- description="Copy static files to build directory">
+ <target name="static" depends="prepare">
<tstamp/>
<copy todir="${build.home}/conf" filtering="on">
<fileset dir="${conf.home}" includes="*.MF"/>
@@ -105,7 +103,8 @@
<!-- ================================================================== -->
<!-- C O M P I L E -->
<!-- ================================================================== -->
- <target name="compile" depends="static" description="Compile">
+ <target name="compile" depends="static"
+ description="Compile all classes into ${build.home}/classes">
<javac srcdir="${source.home}/java"
destdir="${build.home}/classes"
@@ -129,19 +128,29 @@
description="Clean build and distribution directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
+ <delete>
+ <fileset dir="${docs.dest}" includes="**/*"/>
+ </delete>
+ <delete dir="${docs.dest}/javadoc-velservlet"/>
+ <delete>
+ <fileset dir="${basedir}" includes="**/*.bak"/>
+ </delete>
+
</target>
+
<!-- ================================================================== -->
<!-- A L L -->
<!-- ================================================================== -->
<target name="all" depends="clean,jar, docs, javadocs"
description="Clean and compile all components"/>
+
<!-- ================================================================== -->
<!-- J A V A D O C S -->
<!-- ================================================================== -->
<target name="javadocs" depends="compile"
- description="Create Javadoc documentation">
+ description="Create Javadoc documentation into ${build.home}/javadoc">
<javadoc sourcepath="${source.home}/java"
destdir="${build.home}/javadoc"
packagenames="org.apache.velocity.tools.view.*"
@@ -159,9 +168,38 @@
<!-- ================================================================== -->
+ <!-- J A V A D O C S V E L S E R V L E T -->
+ <!-- ================================================================== -->
+ <target name="javadocs-velservlet" depends="static"
+ description="Create Javadoc documentation specific to VelServlet, only public members">
+
+ <!-- Construct compile classpath -->
+ <path id="sourcepath">
+ <pathelement path="src/java/"/>
+ </path>
+
+ <javadoc sourcepathref="sourcepath"
+ destdir="${docs.dest}/javadoc-velservlet"
+ author="true"
+ public="true"
+ version="true"
+ doctitle="<h1>${project.title}</h1>"
+ windowtitle="${project.title} (Version ${project.version})"
+ bottom="Copyright (c) 2002 Apache Software Foundation" >
+ <package name="org.apache.velocity.tools.view.context"/>
+ <package name="org.apache.velocity.tools.view.servlet"/>
+ <package name="org.apache.velocity.tools.view.tools"/>
+ <classpath refid="classpath"/>
+ </javadoc>
+
+ </target>
+
+
+ <!-- ================================================================== -->
<!-- J A R -->
<!-- ================================================================== -->
- <target name="jar" depends="compile">
+ <target name="jar" depends="compile"
+ description="Package classes as jar into ${builddir}">
<jar jarfile="${project.name}-${project.version}.jar"
basedir="${build.home}/classes"
manifest="${conf.home}/MANIFEST.MF"/>
@@ -171,7 +209,8 @@
<!-- ================================================================== -->
<!-- D O C S -->
<!-- ================================================================== -->
- <target name="docs">
+ <target name="docs"
+ description="Generate documentation into ${docs.dest}">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
@@ -184,19 +223,20 @@
<dvsl
basedir="${docs.src}"
destdir="${docs.dest}/"
- toolbox="../xdocs/toolbox.props"
+ toolboxfile="../xdocs/toolbox.props"
extension=".html"
style="../xdocs/site.dvsl"
- excludes="**/project.xml"
+ excludes="**/*menue.xml"
includes="**/*.xml"
/>
</target>
+
<!-- ================================================================== -->
<!-- I N S T A L L J A R -->
<!-- ================================================================== -->
<target name="install-jar" depends="jar"
- description="--> Installs .jar file in ${lib.repo}">
+ description="Installs .jar file in ${lib.repo}">
<copy todir="${lib.repo}" filtering="no">
<fileset dir="${basedir}">
<include name="${project.name}-${project.version}.jar"/>
1.3 +84 -71 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ChainedContext.java
Index: ChainedContext.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ChainedContext.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ChainedContext.java 9 Jan 2002 11:26:40 -0000 1.2
+++ ChainedContext.java 2 Apr 2002 16:46:31 -0000 1.3
@@ -66,62 +66,68 @@
/**
- * <p>
- * Velocity context implementation that does a few things :
- * <ul>
- * <li>
- * puts the request, response, session, and application objects
- * into the Context for
- * direct access, and keeps them read-only
- * </li>
- * <li>
- * supports a read-only toolbox
- * </li>
- * <li>
- * chains the servlet API scopes <i>request</i>, <i>session</i> and
- * <i>application</i> for auto-search if all else fails.
- * </li>
- * </ul>
+ * <p>Velocity context implementation specific to the Servlet environment.</p>
*
- * This means when accessing an object in the context, and it is not either one
- * of REQUEST, RESPONSE, SESSION or APPLICATIOn or a toolbox rquest, and not
- * an object placed directly into the context (conventional use) then
- * the three servlet scopes are searched. The search order is
- * <i>Velocity context</i>, <i>request scope</i>, <i>session scope</i>
- * and <i>application scope</i>.
- * </p>
+ * <p>It provides the following special features:</p>
+ * <ul>
+ * <li>puts the request, response, session, and servlet context objects
+ * into the Velocity context for direct access, and keeps them
+ * read-only</li>
+ * <li>supports a read-only toolbox of context tools</li>
+ * <li>auto-searches servlet request attributes, session attributes and
+ * servlet context attribues for objects</li>
+ * </ul>
*
- * <p>
- * The purpose of this class is to make
- * it easy for web designer to work with
- * Java servlet based web applications. They do not need to be concerned with
- * the concepts of request, session of application scopes and the live time
- * of objects in these scopes.
- * </p>
+ * <p>The {@link #internalGet(String key)} method implements the following search order
+ * for objects:</p>
+ * <ol>
+ * <li>servlet request, servlet response, servlet session, servlet context</li>
+ * <li>toolbox</li>
+ * <li>local hashtable of objects (traditional use)</li>
+ * <li>servlet request attribues, servlet session attribute, servlet context
+ * attributes</li>
+ * </ol>
+ *
+ * <p>The purpose of this class is to make it easy for web designer to work
+ * with Java servlet based web applications. They do not need to be concerned
+ * with the concepts of request, session or application attributes and the
+ * live time of objects in these scopes.</p>
*
- * <p>
- * Note that objects put into the context are always put into the
- * Velocity context itself, not any of the servlet scopes. In order to put
- * an object into one of the servlet scopes, the request, session or servlet
- * context instances must be put into the Velocity context and then accessed
- * using like any other context variable,
- * for example $request.setAttribute(name, value).
- * </p>
+ * <p>Note that the put() method always puts objects into the local hashtable.
+ * </p>
+ *
+ * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
+ * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
- * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
- * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
-v *
- * @version $Id: ChainedContext.java,v 1.2 2002/01/09 11:26:40 sidler Exp $
+ * @version $Id: ChainedContext.java,v 1.3 2002/04/02 16:46:31 sidler Exp $
*/
public class ChainedContext extends VelocityContext implements ViewContext
{
+
+ /**
+ * A local reference to the current servlet request.
+ */
private HttpServletRequest request;
+
+ /**
+ * A local reference to the current servlet response.
+ */
private HttpServletResponse response;
+
+ /**
+ * A local reference to the servlet session.
+ */
private HttpSession session;
+
+ /**
+ * A local reference to the servlet context.
+ */
private ServletContext application;
+ /**
+ * The toolbox.
+ */
private ToolboxContext toolboxContext = null;
- private String toolboxName = null;
/**
* Key to the HTTP request object.
@@ -143,8 +149,14 @@
*/
public static final String APPLICATION = "application";
- public ChainedContext(Context ctx, HttpServletRequest request,
- HttpServletResponse response, ServletContext application)
+
+ /**
+ * Default constructor.
+ */
+ public ChainedContext(Context ctx,
+ HttpServletRequest request,
+ HttpServletResponse response,
+ ServletContext application)
{
super(null, ctx );
@@ -154,26 +166,30 @@
this.application = application;
}
- public void setToolbox( ToolboxContext box )
+
+ /**
+ * <p>Sets the toolbox of context tools.</p>
+ *
+ * @param box toolbox of context tools
+ */
+ public void setToolbox(ToolboxContext box)
{
toolboxContext = box;
}
+
/**
- * A requested object is searched in the Velocity context and the Servlet API
- * scopes <i>request</i>, <i>session</i> (if exists) and <i>servlet context</i>.
- * The search order is <i>Velocity context</i>, <i>request scope</i>, <i>session scope</i>
- * and <i>servlet context</i>.</p>
+ * <p>Looks up and returns the object with the specified key.</p>
+ *
+ * <p>See the class documentation for more details.</p>
*
- * @param key The key of the object requested.
- * @return The requested object or null if not found.
+ * @param key the key of the object requested
+ *
+ * @return the requested object or null if not found
*/
public Object internalGet( String key )
{
- /*
- * make the 4 Scopes of the Apocalypse Read only
- */
-
+ // make the four scopes of the Apocalypse Read only
if ( key.equals( REQUEST ))
{
return request;
@@ -191,10 +207,7 @@
return application;
}
- /*
- * now the toolbox?
- */
-
+ // search the toolbox
Object o = null;
if ( toolboxContext != null)
@@ -208,16 +221,10 @@
}
- /*
- * try the real impl
- */
-
+ // try the local hashtable
o = super.internalGet( key );
- /*
- * if not, wander down the scopes...
- */
-
+ // if not found, wander down the scopes...
if (o == null)
{
o = request.getAttribute( key );
@@ -236,8 +243,9 @@
return o;
}
- /**
- * <p>Fetch the instance of {@link HttpServletRequest} for this request.</p>
+
+ /**
+ * <p>Returns the current servlet request.</p>
*/
public HttpServletRequest getRequest()
{
@@ -246,16 +254,21 @@
/**
- * <p>Fetch the instance of {@link ServletContext} for this request.</p>
+ * <p>Returns the servlet context.</p>
*/
public ServletContext getServletContext()
{
return application;
}
+
+ /**
+ * <p>Returns a reference to the Velocity context (this object).</p>
+ */
public Context getVelocityContext()
{
return this;
}
+
} // ChainedContext
1.3 +22 -3 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ToolboxContext.java
Index: ToolboxContext.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ToolboxContext.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ToolboxContext.java 9 Jan 2002 11:26:40 -0000 1.2
+++ ToolboxContext.java 2 Apr 2002 16:46:31 -0000 1.3
@@ -59,28 +59,47 @@
import org.apache.velocity.context.Context;
/**
- * Simple read only context. Writes get dropped.
+ * <p>Read-only context used to carry a set of context tools.</p>
*
- * @author<a href="mailto:geirm@apache.org">Geir Magnusson Jr.</a>
+ * <p>Writes get dropped.</p>
*
- * @version $Id: ToolboxContext.java,v 1.2 2002/01/09 11:26:40 sidler Exp $
+ * @author<a href="mailto:sidler@apache.org">Gabriel Sidler</a>
+ * @author<a href="mailto:geirm@apache.org">Geir Magnusson Jr.</a>
+ *
+ * @version $Id: ToolboxContext.java,v 1.3 2002/04/02 16:46:31 sidler Exp $
*/
public class ToolboxContext extends VelocityContext
{
+ /**
+ * The collection of context tools in this toolbox.
+ */
private Map toolbox;
+
+ /**
+ * Default constructor.
+ */
public ToolboxContext( Map tb )
{
toolbox = tb;
}
+
+ /**
+ * Get value for key.
+ */
public Object internalGet( String key )
{
return toolbox.get( key );
}
+
+ /**
+ * Does nothing. Returns <code>null</code> always.
+ */
public Object internalPut( String key, Object value )
{
return null;
}
+
}
1.2 +23 -3 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ViewContext.java
Index: ViewContext.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/ViewContext.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ViewContext.java 3 Jan 2002 20:21:55 -0000 1.1
+++ ViewContext.java 2 Apr 2002 16:46:31 -0000 1.2
@@ -59,20 +59,40 @@
import javax.servlet.http.HttpServletRequest;
import javax.servlet.ServletContext;
+
+/**
+ * <p>Objects implementing this interface are passed to context tools
+ * upon initialization by the
+ *{@link org.apache.velocity.tools.view.servlet.ServletToolboxManager}.</p>
+ *
+ * <p>The interface provides context tools in a servlet environment
+ * access to relevant context information, like servlet request, servlet
+ * context and the velocity context. See
+ * {@link org.apache.velocity.tools.view.tools.ServletContextTool} for an
+ * example.</p>
+ *
+ * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
+ * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
+ *
+ * @version $Id: ViewContext.java,v 1.2 2002/04/02 16:46:31 sidler Exp $
+ */
public interface ViewContext
{
- /**
- * <p>Fetch the instance of {@link HttpServletRequest} for this request.</p>
+ /**
+ * <p>Returns the instance of {@link HttpServletRequest} for this request.</p>
*/
public HttpServletRequest getRequest();
/**
- * <p>Fetch the instance of {@link ServletContext} for this request.</p>
+ * <p>Returns the instance of {@link ServletContext} for this request.</p>
*/
public ServletContext getServletContext();
+ /**
+ * <p>Returns a reference to the current Velocity context.</p>
+ */
public Context getVelocityContext();
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/context/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
These are Javadoc package comments.
-->
</head>
<body bgcolor="white">
Provides special purpose implementations of the VelocityContext class
related to the automatic toolbox management in a servlet environment.
<!--
##### THIS IS THE TEMPLATE FOR THE PACKAGE DOC COMMENTS. #####
##### TYPE YOUR PACKAGE COMMENTS HERE. BEGIN WITH A #####
##### ONE-SENTENCE SUMMARY STARTING WITH A VERB LIKE: #####
Provides for....
-->
<h2>Package Specification</h2>
<!--
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
-->
<h2>Related Documentation</h2>
<!--
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
<!-- Put @see and @since tags down here. -->
</body>
</html>
1.3 +123 -47 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/servlet/VelocityViewServlet.java
Index: VelocityViewServlet.java
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/servlet/VelocityViewServlet.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- VelocityViewServlet.java 4 Jan 2002 03:29:39 -0000 1.2
+++ VelocityViewServlet.java 2 Apr 2002 16:46:31 -0000 1.3
@@ -66,47 +66,87 @@
import java.util.Enumeration;
import java.util.Properties;
import java.util.HashMap;
+import java.util.Properties;
import java.io.IOException;
import java.io.FileNotFoundException;
import java.io.InputStream;
+import org.apache.commons.collections.ExtendedProperties;
+
import org.apache.velocity.servlet.VelocityServlet;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.Template;
import org.apache.velocity.context.Context;
import org.apache.velocity.runtime.RuntimeConstants;
-
import org.apache.velocity.tools.view.context.ToolboxContext;
import org.apache.velocity.tools.view.context.ViewContext;
import org.apache.velocity.tools.view.context.ChainedContext;
-import org.apache.velocity.tools.view.tools.ToolboxManager;
+import org.apache.velocity.tools.view.servlet.ServletToolboxManager;
/**
- * <p>
- * Servlet implementation designed for use in web applications
- * where a controller forwards the request to a rendering servlet
- * such as the JspServlet for JSP based applicaions.
- * </p>
+ * <p>A servlet to process Velocity templates. This is comparable to the
+ * the JspServlet for JSP-based applications.</p>
+ *
+ * <p>The servlet provides the following features:</p>
+ * <ul>
+ * <li>renders Velocity templates</li>
+ * <li>provides support for an auto-loaded, configurable toolbox</li>
+ * <li>provides transparent access to the servlet request attributes,
+ * servlet session attributes and servlet context attributes by
+ * auto-searching them</li>
+ * <li>logs to the logging facility of the servlet API</li>
+ * </ul>
+ *
+ * <p>VelocityViewServlet supports the following configuration parameters
+ * in webl.xml:</p>
+ * <dl>
+ * <dt>toolbox</dt>
+ * <dd>Path and name of the toolbox configuration file. The path must be
+ * relative to the web application root directory. If this parameter is
+ * not found, no toolbox is instantiated.</dd>
+ * <dt>velocity.properties</dt>
+ * <dd>Path and name of the Velocity configuration file. The path must be
+ * relative to the web application root directory. If this parameter
+ * is not present, Velocity is initialized with default settings.</dd>
+ * </dl>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
* @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
*
- * @version $Id: VelocityViewServlet.java,v 1.2 2002/01/04 03:29:39 geirm Exp $
+ * @version $Id: VelocityViewServlet.java,v 1.3 2002/04/02 16:46:31 sidler Exp $
*/
public class VelocityViewServlet extends VelocityServlet
{
+
+ /**
+ * Key used to access the toolbox configuration file path from the
+ * Servlet init parameters.
+ */
public static final String TOOLBOX_PARAM = "toolbox";
- protected ToolboxManager toolboxManager = null;
+
+
+ /**
+ * Key used to access the Velocity configuration file path from the
+ * Servlet init parameters.
+ */
+ public static final String VELOCITY_PROPERTIES = "velocity.properties";
+
/**
- * we want to see if there is a magickey as a context
- * param
+ * A reference to the toolbox manager.
*/
+ protected ServletToolboxManager toolboxManager = null;
+
+ /**
+ * <p>Initializes servlet, toolbox and Velocity template engine.</p>
+ *
+ * @param config servlet configuation
+ */
public void init( ServletConfig config )
throws ServletException
{
@@ -143,7 +183,7 @@
{
Velocity.info("Using toolbox configuration file '" + key +"'");
- toolboxManager = new ToolboxManager();
+ toolboxManager = new ServletToolboxManager(getServletContext());
toolboxManager.load( is );
Velocity.info("Toolbox setup complete.");
@@ -171,35 +211,56 @@
}
}
+
/**
- * do our own init...
+ * Initializes Velocity.
+ *
+ * @param config servlet configuration parameters
*/
protected void initVelocity( ServletConfig config )
throws ServletException
{
+ // Read Velocity configuration
+ ExtendedProperties velProps = new ExtendedProperties();
+ String filename = config.getInitParameter(VELOCITY_PROPERTIES);
+ if ( filename != null )
+ {
+ InputStream is = null;
+ try
+ {
+ // ensure path start with '/'
+ if ( !filename.startsWith("/") )
+ {
+ filename = "/" + filename;
+ }
- /*
- * start with our servletlogger, which logs to the servlet
- * engines log
- */
+ is = getServletContext().getResourceAsStream(filename);
+ if ( is != null)
+ {
+ getServletContext().log("Using configuration file '" + filename +"'");
+ velProps.load(is);
+ getServletContext().log("Configuration file sucessfully read.");
+ }
+ }
+ catch( Exception e )
+ {
+ getServletContext().log("Problem reading Velocity configuration file '" + filename +"' : " + e );
+ }
+ }
+ Velocity.setExtendedProperties(velProps);
+
+ // define servletlogger, which logs to the servlet engines log
ServletLogger sl = new ServletLogger( getServletContext() );
Velocity.setProperty( RuntimeConstants.RUNTIME_LOG_LOGSYSTEM, sl );
- /*
- * as for the webapp resource loader
- */
-
+ // load resources with webapp resource loader
VelocityStrutsServletAppContext vssac = new VelocityStrutsServletAppContext( getServletContext() );
-
Velocity.setApplicationAttribute( "org.apache.velocity.tools.view.servlet.WebappLoader", vssac );
Velocity.setProperty( "resource.loader", "webapp" );
Velocity.setProperty( "webapp.resource.loader.class", "org.apache.velocity.tools.view.servlet.WebappLoader" );
- /*
- * now all is ready - init()
- */
-
+ // now all is ready - init Velocity
try
{
Velocity.init();
@@ -211,36 +272,37 @@
}
}
+
/**
- * <p>Handled the request. Current responsibilities :</p>
- * <ul>
- * <li> fill context with all application/session/request attributes
- * <li> find and return Template
- * </ul>
- * @param request client request
- * @param response client response
- * @param ctx VelocityContext to fill
- * @return Velocity Template object or null
+ * <p>Handle the template processing request.</p>
+ *
+ * @param request client request
+ * @param response client response
+ * @param ctx VelocityContext to fill
+ *
+ * @return Velocity Template object or null
*/
- protected Template handleRequest( HttpServletRequest request, HttpServletResponse response, Context ctx )
+ protected Template handleRequest(HttpServletRequest request,
+ HttpServletResponse response,
+ Context ctx )
throws Exception
{
return getTemplate(request.getServletPath() );
}
+
/**
- * <p>Returns a Velocity context. A new context of class
- * {@link ChainedContext} is created and returned. This method overwrites
- * {@link org.apache.velocity.servlet.VelocityServlet#createContext(
- * HttpServletRequest request, HttpServletResponse response)}.
- * </p>
- *
- * @param request servlet request from client
- * @param response servlet reponse to client
+ * <p>Creates and returns an initialized Velocity context.</p>
+ *
+ * A new context of class {@link ChainedContext} is created and
+ * initialized. This method overwrites
+ * {@link org.apache.velocity.servlet.VelocityServlet#createContext(HttpServletRequest request, HttpServletResponse response)}.</p>
*
- * @return context
+ * @param request servlet request from client
+ * @param response servlet reponse to client
*/
- protected Context createContext(HttpServletRequest request, HttpServletResponse response )
+ protected Context createContext(HttpServletRequest request,
+ HttpServletResponse response)
{
/*
* create a ChainedContext()
@@ -261,21 +323,35 @@
return ctx;
}
+
/**
- * little wrapper class to safely pass the ServletContext to the loader
+ * <p>Wrapper class to safely pass the servlet context to the web app
+ * loader.</p>
*/
public class VelocityStrutsServletAppContext implements WebappLoaderAppContext
{
+ /**
+ * A reference to the servlet context
+ */
ServletContext servletContext = null;
+
+ /**
+ * Default constructor.
+ */
VelocityStrutsServletAppContext( ServletContext sc )
{
servletContext = sc;
}
+
+ /**
+ * Returns a reference to the servlet context.
+ */
public ServletContext getServletContext()
{
return servletContext;
}
}
+
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/servlet/ServletContextToolLogger.java
Index: ServletContextToolLogger.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.servlet;
import javax.servlet.ServletContext;
import org.apache.velocity.tools.view.tools.ContextToolLogger;
/**
* <p>A logger for context tools in a servlet environment.</p>
*
* <p>This class implements interface {@link ContextToolLogger}.
* The logged messages are forwarded to the standard log facilities
* provided by the Servlet API, namely {@link ServletContext#log(String msg)}
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
* @version $Id: ServletContextToolLogger.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public class ServletContextToolLogger implements ContextToolLogger
{
/**
* A reference to the servlet context.
*/
private ServletContext ctx;
/**
* <p>Default constructor.</p>
*
* @param ctx A reference to the servlet context of the web
* application.
*/
public ServletContextToolLogger(ServletContext ctx)
{
this.ctx = ctx;
}
/**
* <p>Logs a message to the standard servlet log facility.</p>
*
* @param msg message to be logged, no formatting is applied
*/
public void log(String msg)
{
ctx.log(msg);
}
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/servlet/ServletToolboxManager.java
Index: ServletToolboxManager.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.servlet;
import java.io.InputStream;
import java.util.List;
import java.util.Iterator;
import java.util.HashMap;
import java.util.Map;
import java.util.ArrayList;
import javax.servlet.http.HttpSession;
import javax.servlet.ServletContext;
import org.dom4j.Document;
import org.dom4j.Element;
import org.dom4j.Node;
import org.dom4j.io.SAXReader;
import org.apache.velocity.context.Context;
import org.apache.velocity.tools.view.context.ToolboxContext;
import org.apache.velocity.tools.view.context.ViewContext;
import org.apache.velocity.tools.view.tools.ServletContextTool;
import org.apache.velocity.tools.view.tools.LogEnabledContextTool;
import org.apache.velocity.tools.view.tools.ContextContextTool;
import org.apache.velocity.tools.view.tools.ThreadSafeContextTool;
/**
* <p>A toolbox manager for the servlet environment.</p>
*
* <p>A toolbox manager is responsible for automatically filling the Velocity
* context with a set of context tools. This class provides the following
* features:</p>
* <ul>
* <li>configurable through an XML-based configuration file</li>
* <li>assembles a set of context tools (the toolbox) on request</li>
* <li>handles context tools with different life cycles</li>
* <li>efficiently reuses context tool instances where possible</li>
* <li>provides special handling to known classes of context tools</li>
* <li>supports any class with a public constructor without parameters
* to be used as a context tool</li>
* </ul>
*
*
* <p><strong>Configuration</strong></p>
* <p>The toolbox manager is configured through an XML-based configuration
* file. The configuration file is passed to the {@link #load(InputStream input)}
* method. The required format is show in the following example:</p>
* <pre>
* <?xml version="1.0"?>
*
* <toolbox>
* <tool>
* <key>toolLoader</key>
* <class>org.apache.velocity.tools.tools.ToolLoaderTool</class>
* </tool>
* <tool>
* <key>math</key>
* <class>org.apache.velocity.tools.tools.MathTool</class>
* </tool>
* </toolbox>
* </pre>
* <p>The recommended location for the configuration file is the WEB-INF directory of the
* web application. Note that some classes of context tools may allow or
* require additional configuration attributes. Please consult the documentation
* of the context tools for more details.
*
*
* <p><strong>Recognized Classes of Context Tools</strong></p>
* <p>ServletToolboxManager provides special support for the following classes
* of context tools:
* <dl>
* <dt>{@link LogEnabledContextTool}</dt>
* <dd>Receive a reference to a logger object that enables them to log error
* conditions.</dd>
*
* <dt>{@link ThreadSafeContextTool}</dt>
* <dd>Instances are considered to be thread-safe. One single instance of
* the tool is re-used the entire runtime. This is much more efficient
* than the default handling (see below)</dd>
*
* <dt>{@link ServletContextTool}</dt>
* <dd>Context tools that implement this interface support the additional
* configuration attribute <i>lifecycle</i>. This allows an
* application developer to explicitely assign a <i>lifecycle</i> to the tool.
* Supported are the values <code>request</code>, <code>session</code> and
* <code>application</code>. The <i>lifecycle</i> attribute is optional.
* If not specified, a tool-specific default lifecycle is used. In the
* following configuration example a <i>lifecycle</i> of <code>session</code>
* is assigned to tool instances:
* <pre>
* <tool>
* <key>xyz</key>
* <class>org.apache.velocity.tools.tools.XYZ</class>
* <scope>session</scope>
* </tool>
* </pre>
* Furthermore, context tools of this class get access to the current
* servlet request, the current session and the servlet context.</dd>
*
* <dt>{@link ContextContextTool}</dt>
* <dd>Context tools of this class receive a reference to the Velocity
* context.</dd>
* </dl>
*
*
* <p><strong>Default Handling</strong></p>
* <p>Any object with a public constructor without parameters can be used
* as a context tool. For classes of context tools that are not listed above,
* the following default handling is applied:</p>
* <ul>
* <li>instances are created using a constructor without parameters</li>
* <li>tools are assumed to be not thread-safe, a new instance is created
* for every template being processed</li>
* <li>tools have no access to logging</li>
* <li>tools have no access to contextual information, like the servlet
* environment or the Velocity context</li>
* </ul>
*
*
* <p><strong>Other Environments</strong></p>
* <p>Note that while the implementation of this toolbox manager is specific
* to the Servlet environment, it can be easily adapted to be used in other
* environments, like the DVSL ant task, for example.</p>
*
*
* @author <a href="mailto:sidler@teamup.com">Gabriel Sidler</a>
* @author <a href="mailto:nathan@esha.com">Nathan Bubna</a>
* @author <a href="mailto:geirm@apache.org">Geir Magnusson Jr.</a>
*
* @version $Id: ServletToolboxManager.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public class ServletToolboxManager
{
// --------------------------------------------------- Properties ---------
public static final String TOOL_KEY = "key";
public static final String TOOL_LIFECYCLE = "lifecycle";
public static final String TOOL_CLASS = "class";
public static final String SESSION_TOOLS_KEY = "org.apache.velocity.tools.view.tools.ServletToolboxManager.SessionTools";
private ServletContextToolLogger logger;
private ServletContext scontext;
private SAXReader saxReader;
private Map applicationTools;
private ArrayList applicationToolsNotInitialized;
private ArrayList sessionTools;
private ArrayList requestTools;
// --------------------------------------------------- Constructor --------
/**
* Default constructor
*/
public ServletToolboxManager(ServletContext scontext)
{
this.scontext = scontext;
saxReader = new SAXReader();
applicationToolsNotInitialized = new ArrayList();
sessionTools = new ArrayList();
requestTools = new ArrayList();
logger = new ServletContextToolLogger(scontext);
}
// --------------------------------------------------- Methods ------------
private void log(String s)
{
scontext.log("ServletToolboxManager: " + s);
}
/**
* Reads an XML document from an {@link InputStream}
* using <a href="http://dom4j.org">dom4j</a> and
* sets up the toolbox for the servlet from that.
*
* Assumes toolbox.xml has a format like
*
* <toolbox>
* <tool>
* <key>foo</key>
* <lifecycle>request</lifecycle>
* <class>com.mycompany.tools.Foo</class>
* </tool>
* <tool>
* <key>bar</key>
* <class>org.yourorganization.tools.Bar</class>
* </tool>
* </toolbox>
*
* @param input the InputStream to read from
*/
public void load(InputStream input) throws Exception
{
log("Initializing the toolbox...");
Document document = saxReader.read(input);
List tools = document.selectNodes("//toolbox/*");
Iterator i = tools.iterator();
while(i.hasNext())
{
//
// Read definition of a tool in toolbox config file
//
Element e = (Element)i.next();
String name = e.getName();
log("Loading " + name);
// Read tool's key
Node n = e.selectSingleNode(TOOL_KEY);
String key = n.getText();
log(" Context key: " + key);
// Read the tool's class
n = e.selectSingleNode(TOOL_CLASS);
String classname = n.getText();
log(" Class: " + classname);
// Create an instance of the tool
Object obj;
try
{
obj = Class.forName(classname).newInstance();
}
catch(Exception ex)
{
log(" Error creating instance for class: " + classname +
". " + ex);
log(" Tool not loaded.");
continue;
}
// Try to read the tool's lifecycle (specific to ServletContextTool)
// First, check of a lifecycle has been configured.
n = e.selectSingleNode(TOOL_LIFECYCLE);
String lifecycle;
if (n != null)
{
lifecycle = n.getText();
}
else
{
// Secondly, try to read default lifecycle
try
{
lifecycle = ((ServletContextTool)obj).getDefaultLifecycle();
}
catch (ClassCastException cce)
{
lifecycle = "";
}
}
log(" Life cycle: " + lifecycle);
//
// Pass a logger to the tools that implement interface LogEnabledContextTool
//
if (obj instanceof LogEnabledContextTool)
{
((LogEnabledContextTool)obj).setLogger(logger);
log(" Known interface: LogEnabledContextTool");
}
//
// Store the tool instance in the appropriate list
//
// First, handle tools that implement interface ServletContextTool
// (the interface ThreadSafeContextTool is not considered in this
// case because the 'lifecycle' attribute takes precedence over the
// 'thread safe' attribute)
if (obj instanceof ServletContextTool)
{
log(" Known interface: ServletContextTool");
if (lifecycle.equalsIgnoreCase(ServletContextTool.REQUEST))
{
requestTools.add(new ToolInfo(key, obj, classname));
}
else if (lifecycle.equalsIgnoreCase(ServletContextTool.SESSION))
{
sessionTools.add(new ToolInfo(key, obj, classname));
}
else if (lifecycle.equalsIgnoreCase(ServletContextTool.APPLICATION))
{
applicationToolsNotInitialized.add(new ToolInfo(key, obj, classname));
}
else
{
log(" Error: Unknown lifecycle: \""+ lifecycle +"\".");
log(" Tool not loaded.");
}
continue;
}
// Secondly, handle tools that implement interface ContextContextTool
// (The interface ThreadSafeContextTool is not considered in this case
// because it doesn't matter. A new tool instance is created for every
// request anyway since the Velocity context needs to be passed.)
if (obj instanceof ContextContextTool)
{
log(" Known interface: ContextContextTool");
// These tools always have a life cycle of 'request'
requestTools.add(new ToolInfo(key, obj, classname));
continue;
}
// Third, handle tools that implement interface ThreadSafeContextTool.
// In this case, the one and only instance of the tool is reused the
// entire runtime.
if (obj instanceof ThreadSafeContextTool)
{
log(" Known interface: ThreadSafeContextTool");
applicationToolsNotInitialized.add(new ToolInfo(key, obj, classname));
continue;
}
// Fourth, handle tools that implement no known interface.
// Unknown context tools are considered not thread-safe and
// therefore a new instance is created for every template processing
// request.
log(" Known interface: None. Apply default handling.");
requestTools.add(new ToolInfo(key, obj, classname));
}
log("Done initializing the toolbox.");
}
/**
* Creates a {@link ToolboxContext} from the tools loaded
* in this manager. It uses the given {@link ViewContext}
* to create instances of session and request tools. Request
* tools are created on every call to this method. Session
* tools are created once per session. Application tool instances
* are re-used for the entire runtime.
*
* @param vcontext the current Velocity context
* @return the created ToolboxContext
*/
public ToolboxContext getToolboxContext(ViewContext vcontext)
{
// Only on first request, initialize tools with a life
// cycle of 'application'. This cannot be done earlier because
// some tools may need access to data that is only available
// with a template processing request.
if (applicationTools == null)
{
synchronized (applicationToolsNotInitialized)
{
if (applicationTools == null)
{
applicationTools = new HashMap(applicationToolsNotInitialized.size());
Iterator i = applicationToolsNotInitialized.iterator();
while (i.hasNext())
{
ToolInfo info = (ToolInfo)i.next();
Object tool = info.getTool();
// First, handle tools that implement ServletContextTool and have
// a defined life cycle of 'application'
if (tool instanceof ServletContextTool)
{
applicationTools.put(info.getKey(),
((ServletContextTool)tool).getInstance(vcontext));
continue;
}
// Secondly, handle ContextContextTools
// => they never have an 'application' life cycle, => skip
// Third, handle tools that implement ThreadSafeContextTool
if (tool instanceof ThreadSafeContextTool)
{
applicationTools.put(info.getKey(), tool);
continue;
}
// There shouldn't be any tool left, otherwise it's an error
log("Error trying to load unknown tool with a life cycle " +
"of 'application': key=" + info.getKey() + " class=" +
tool.getClass() + ". Tool not loaded.");
}
}
}
}
//
// Assemble toolbox
//
// First, add tools with an 'application' life cycle, if any.
Map toolbox = new HashMap(applicationTools);
// Secondly, add tools with a 'session' life cycle, if any.
if (!sessionTools.isEmpty())
{
HttpSession session = vcontext.getRequest().getSession();
// get the initialized session tools
Map stmap = (Map)session.getAttribute(SESSION_TOOLS_KEY);
// if session tools aren't initialized, do so and store
// them in the session attributes.
if (stmap == null)
{
synchronized (session)
{
if (stmap == null)
{
stmap = new HashMap(sessionTools.size());
Iterator i = sessionTools.iterator();
while(i.hasNext())
{
ToolInfo info = (ToolInfo)i.next();
Object tool = info.getTool();
// Only tools of class ServletContextTool can
// have a life cycle of session.
try
{
stmap.put(info.getKey(),
((ServletContextTool)tool).getInstance(vcontext));
}
catch(ClassCastException cce)
{
log("Error trying to load unknown tool with" +
" a life cycle of 'session': key=" +
info.getKey() + " class=" + tool.getClass() +
". Tool not loaded.");
}
}
session.setAttribute(SESSION_TOOLS_KEY, stmap);
}
}
}
//add the initialized session tools to the toolbox
toolbox.putAll(stmap);
}
// Thirdly, add tools with a 'request' life cycle, if any.
Iterator i = requestTools.iterator();
while(i.hasNext())
{
ToolInfo info = (ToolInfo)i.next();
Object tool = info.getTool();
// First, handle tools that implement ServletContextTool.
// They are initialized with an instance of ViewContext.
if (tool instanceof ServletContextTool)
{
toolbox.put(info.getKey(),
((ServletContextTool)(info.getTool())).getInstance(vcontext));
continue;
}
// Secondly, handle tools that implement ContextContextTool.
// They are initialized with an instance of Context.
if (tool instanceof ContextContextTool)
{
toolbox.put(info.getKey(),
((ContextContextTool)(info.getTool())).getInstance((Context)vcontext));
continue;
}
// Third, handle any other tool that does not implement any known
// interface. It is required that these tools have a public
// contructor with no parameters.
try
{
tool = Class.forName(info.getClassname()).newInstance();
toolbox.put(info.getKey(), tool);
continue;
}
catch(Exception e)
{
log("Error creating instance for class: " + info.getClassname() +
". " + e);
continue;
}
}
return new ToolboxContext(toolbox);
}
/**
* This class holds a context tool's key and original instance.
*/
protected final class ToolInfo
{
private String key;
private Object tool;
private String classname;
ToolInfo(String key, Object tool, String classname)
{
this.key = key;
this.tool = tool;
this.classname = classname;
}
String getKey()
{
return key;
}
Object getTool()
{
return tool;
}
String getClassname()
{
return classname;
}
}
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/servlet/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
These are Javadoc package comments.
-->
</head>
<body bgcolor="white">
Provides VelServlet, a standalone Velocity servlet for template
rendering in web applications, and supporting classes. All classes
in this package are specific to the Java Servlet environment.
<!--
##### THIS IS THE TEMPLATE FOR THE PACKAGE DOC COMMENTS. #####
##### TYPE YOUR PACKAGE COMMENTS HERE. BEGIN WITH A #####
##### ONE-SENTENCE SUMMARY STARTING WITH A VERB LIKE: #####
Provides for....
-->
<h2>Package Specification</h2>
<!--
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
-->
<h2>Related Documentation</h2>
<!--
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
<!-- Put @see and @since tags down here. -->
</body>
</html>
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/ContextContextTool.java
Index: ContextContextTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
import org.apache.velocity.tools.view.context.ViewContext;
import org.apache.velocity.context.Context;
/**
* <p>An interface for Velocity context tools that need access to the Velocity
* context.</p>
*
* <p>Context tools that implement this interface receive special treatment
* by a compatible toolbox manager, e.g.
* {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager}:</p>
* <ul>
* <li>Upon creation of a new instance, the toolbox manager passes
* to the context tool a reference to the Velocity context.</li>
* </ul>
*
* <p>Unlike some other tools, tools that implement this interface do not
* support multiple different life cycles. All implementations of this
* interface are assigned a life cycle of 'request', meaning that the
* tool is valid only for the processing of the currently requested template.
* A new instance is created for every request. The life cycle cannot be
* configured.</p>
*
* <p>Examples of context tools that typically would implement this
* interface are tools like a context tool loader or a context inspector.
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
* @version $Id: ContextContextTool.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public interface ContextContextTool
{
/**
* <p>Returns a new instance.</p>
*
* <p>This is effectively a factory method used to create
* object instances for use in templates. It is important
* that only instances obtained from this method are used
* in templates.</p>
*
* @param context a reference to the Velocity context
*/
public Object getInstance(Context context);
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/ContextToolLogger.java
Index: ContextToolLogger.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
/**
* <p>Defines the interface of a logger object that can be used by context
* tools to log messages to an underlying logging facility. </p>
*
* <p>Implementation of this interface can be thought of as adapters
* between context tools and the logging facilities of a specific
* environment. For example, in servlet environments a logger instance
* would accept log messages from a context tool and write them to the
* Servlet API's logging facility.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
* @version $Id: ContextToolLogger.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public interface ContextToolLogger
{
/**
* <p>Log a message to the logging infrastructure of the environment. </p>
*
* @param msg Message to be logged. The message is passed on as is. No
* formatting, etc. is applied.
*/
public void log(String msg);
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/LogEnabledContextTool.java
Index: LogEnabledContextTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
/**
* <p>An interface that marks a context tool class as capable of logging.</p>
*
* <p>The only method defined by this interface is
* <code>{@link #setLogger(ContextToolLogger logger)}</code>. This method allows
* a toolbox manager to pass an instance of a logger object to the context
* tool. This logger can be used subsequently to log messages.</p>
*
* <p>The following implementation guidelines are to be noted:</p>
* <ul>
* <li>Implementing this interface by a context tool does not garantuee
* that a logger will be passed. It is up to the implementation of the
* toolbox manager if a logger is passed or not.</li>
* <li>If a logger is passed using setLogger(), it will be passed only
* to one instance of a context tool class. It has to be made sure, that
* a reference to the logger is stored in a static variable, such that
* the logger is available to all instances of the class.</li>
* <li>Logging in context tools typically should be used only for serious
* errors. Most application environments already implement usage
* logging, etc.</li>
* </ul>
*
* @author <a href="mailto:sidler@teamup.com">Gabriel Sidler</a>
*
* @version $Id: LogEnabledContextTool.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public interface LogEnabledContextTool
{
/**
* <p>Sets a logger instance for this class of context tools.</p>
*
* <p>This logger can be used subsequently by instances to to log
* messages to the logging infrastructor of th underlying framework.</p>
*
* @param logger the logger instance to be set
*/
public void setLogger(ContextToolLogger logger);
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/LogEnabledContextToolImpl.java
Index: LogEnabledContextToolImpl.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
/**
* <p>An implementation of the {@link LogEnabledContextTool} interface. </p>
*
* <p>This class is intended to be extended by context tools that need
* logging. It implements logging to a logger object passed passed using
* the {@link #setLogger} method. The implementation support three log
* levels ERROR, WARN and INFO and takes care of formatting the log message
* appropriately.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabriel Sidler</a>
*
* @version $Id: LogEnabledContextToolImpl.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public abstract class LogEnabledContextToolImpl implements LogEnabledContextTool
{
/**
* Constant for error log messages.
*/
public static final int ERROR = 10;
/**
* Constant for warning log messages.
*/
public static final int WARN = 20;
/**
* Constant for informational log messages.
*/
public static final int INFO = 30;
/**
* A reference to the logger.
*/
protected static ContextToolLogger logger;
/**
* <p>Sets a logger instance for this class of context tools. </p>
*
* <p>This logger can be used subsequently by instances to log
* messages to the logging infrastructor of the underlying framework.
* If a logger is never set, the {@link #log(int level, String msg)}
* method will simply do nothing.</p>
*
* @param logger the logger instance to be set
*/
public void setLogger(ContextToolLogger logger)
{
this.logger = logger;
}
/**
* <p>Writes a message to the log. </p>
*
* <p>The message is modified in the following ways before it is
* sent to the logger:</p>
* <ul>
* <li>the class name is prepended</li>
* <li>one of <code>[ERROR]</code>, <code>[WARN]</code>, or
* <code>[INFO]</code> is prepended</li>
* </ul>
* <p>For example, the log message "File not found." would be
* written to the log as:
* <pre>
* org.apache.velocity.tools.tools.toolXY [ERROR] File not found.
* </pre>
* <p>If no logger has been set previously, the method will do nothing.</p>
*
* @param level log level, one of {@link #ERROR}, {@link #WARN} or
* {@link #INFO}
* @param msg log message
*/
public void log(int level, String msg)
{
if (logger != null)
{
if (level == ERROR)
{
logger.log(this.getClass() + ": [ERROR] " + msg);
}
else if (level == WARN)
{
logger.log(this.getClass() + ": [WARN] " + msg);
}
else
{
logger.log(this.getClass() + ": [INFO] " + msg);
}
}
}
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/ServletContextTool.java
Index: ServletContextTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
import org.apache.velocity.tools.view.context.ViewContext;
/**
* <p>An interface for Velocity context tools in a servlet environment.</p>
*
* <p>Context tools that implement this interface receive special treatment
* by a compatible toolbox manager, e.g.
* {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager}:</p>
* <ul>
* <li>The toolbox manager supports three different life cycle models for
* context tools: <i>request</i>, <i>session</i> and <i>application</i>.
* An application developer can choose through configuration of the
* toolbox which of the three life cycle models should be applied to a
* particular tool class. Since not every tool class is capable to be used
* with all of the three livecylce models, it is important to consult the
* tool documentation. See also
* {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager} for
* more information.</li>
* <li>Upon instantiation of a new context tool, the toolbox manager passes
* to the context tool an object of class {@link ViewContext}. This
* gives the context tool access to HttpServletRequest, HttpSession and
* ServletContext.</li>
* </ul>
*
* <p>The three static fields {@link #REQUEST}, {@link #SESSION} and
* {@link #APPLICATION} define constants to be used to specify one of the
* three life cycle models. These constants are used in the toolbox
* configuration file.</p>
*
* <p>Note that context tools that do not need any of the special treatment
* described above, do not need to implement this interface. Please refer to
* the documentation of
* {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager} for
* more information on the default treatment of context tools.</p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
* @version $Id: ServletContextTool.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public interface ServletContextTool
{
/**
* Constant for a live cycle of <i>request</i>.
*/
public static final String REQUEST = "request";
/**
* Constant for a live cycle of <i>session</i>.
*/
public static final String SESSION = "session";
/**
* Constant for a live cycle of <i>application</i>.
*/
public static final String APPLICATION = "application";
/**
* A new tool object will be instantiated per-request by calling
* this method. A ContextTool is effectively a factory used to
* create objects for use in templates. Some tools may simply return
* themselves from this method, others may instantiate new objects
* to hold the per-request state.
*
* @param context A reference to the Velocity context. Through this
* object, context tools gain access to HttpServletRequest,
* HttpSession and ServletContext.
*/
public Object getInstance(ViewContext context);
/**
* <p>Returns the default life cycle for the context tool. Some
* toolbox managers may allow an application developer to overwrite
* this default life cycle by defining a life cycle attribute in
* the toolbox configuration. An implementation of this interface
* should clearly document if life cycles other than the default
* life cycle is allowed for the tool.</p>
*
* @returns one of {@link #REQUEST}, {@link SESSION} or {@link APPLICATION}.
*/
public String getDefaultLifecycle();
}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/ThreadSafeContextTool.java
Index: ThreadSafeContextTool.java
===================================================================
/*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.velocity.tools.view.tools;
/**
* <p>A marker interface that indicates that a context tool is thread-safe. </p>
*
* <p>The handling of thread-safe context tools can be optimized by
* compatible toolbox managers like
* {@link org.apache.velocity.tools.view.servlet.ServletToolboxManager}.
* The same instance of the context tool can be reused for the entire runtime.
* </p>
*
* <p>This class does not define any methods or fields. Thread-safe context
* tools should simply add the 'implements ThreadSafeContextTool' statement
* to the class definition to signal the toolbox manager that it is
* safe to reuse the same instance for multiple template processing requests.
* </p>
*
* @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
*
* @version $Id: ThreadSafeContextTool.java,v 1.1 2002/04/02 16:46:31 sidler Exp $
*
*/
public interface ThreadSafeContextTool
{}
1.1 jakarta-velocity-tools/view/src/java/org/apache/velocity/tools/view/tools/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
These are Javadoc package comments.
-->
</head>
<body bgcolor="white">
Provides interfaces and abstract classes supporting the construction of
automatically managed context tools.
<!--
##### THIS IS THE TEMPLATE FOR THE PACKAGE DOC COMMENTS. #####
##### TYPE YOUR PACKAGE COMMENTS HERE. BEGIN WITH A #####
##### ONE-SENTENCE SUMMARY STARTING WITH A VERB LIKE: #####
Provides for....
-->
<h2>Package Specification</h2>
<!--
##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
<li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>
-->
<h2>Related Documentation</h2>
<!--
For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>
-->
<!-- Put @see and @since tags down here. -->
</body>
</html>
1.1 jakarta-velocity-tools/view/xdocs/velservlet-menue.xml
Index: velservlet-menue.xml
===================================================================
<?xml version="1.0"?>
<project href="http://jakarta.apache.org/velocity/">
<title>VelServlet Menue</title>
<logo href="http://jakarta.apache.org/velocity/images/logo.gif">< :) /></logo>
<body>
<uplink name="VelTools Home" href="docs/index.html" alt="top"/>
<menu name="About VelServlet">
<item name="Overview" href="view/docs/velservlet.html"/>
<item name="Examples"/>
<item name="Servlet Configuration"/>
<item name="Toolbox Configuration"/>
<item name="Download"/>
<item name="Javadoc" href="view/docs/javadoc-velservlet/index.html"/>
</menu>
</body>
</project>
1.1 jakarta-velocity-tools/view/xdocs/velservlet.xml
Index: velservlet.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Velocity View For Struts</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<author email="geirm@apache.org">Geir Magnusson Jr.</author>
<projectfile>xdocs/velservlet-menue.xml</projectfile>
</properties>
<body>
<section name="Welcome to VelServlet">
<p>VelServlet is a subproject of Velocity. Its goals is to create a
standalone Velocity servlet that can be used for template rendering
in Web applications.</p>
<p>Intended audience of this subproject are Web
application developers that plan on adding Velocity as a view layer
technology to their Servlet-based web application framework. VelServlet
offers the following key features:</p>
<ul>
<li>VelServlet is a standalong Java servlet that renders Velocity templates.
It can be invoked either directly from Web clients or from other servlets
by forwarding request for template rendering to it. Its usage is
similar to the JSPServlet for rendering JSP pages.</li>
<li>VelServlet makes ServletRequest attributes, HttpSession attributes and
ServletContext attributes automatically available to the template designer
through the Velocity context. It is not necessary to explicitely
populate the Velocity context.</li>
<li>VelServlet offers toolbox support. It is possible to define a set
of context tools (view helpers) that are made available to the template
designer automatically through the Velcity context.</li>
<li>Velocity log output can be redirected to the log infrastructure
of the Web application. By default, the log is directed to the
logging facility provided by the Servlet API.</li>
</ul>
<p>Using VelServlet, it becomes possible to write Web applications that are
independent of a particular view technology. This opens a straightforward
migration path between JSP pages and Velocity templates as the view layer
technology in Web application.</p>
<p>A typical application case for VelServlet is to use it in conjunction
with a Servlet-based web application framework.
<a href="../../struts/docs/index.html">Velocity for Struts</a> is a Velocity
subproject that brings Velocity to the Struts world and is the first
application that takes advantage of VelServlet.</p>
<p><strong>To be added</strong></p>
<ul>
<li>Examples</li>
<li>Configuration of Servlet</li>
<li>Configuration of Toolbox</li>
<li>Download</li>
<li><a href="javadoc-velservlet/index.html">Javadoc</a></li>
</ul>
</section>
</body>
</document>
1.3 +61 -40 jakarta-velocity-tools/xdocs/site.dvsl
Index: site.dvsl
===================================================================
RCS file: /home/cvs/jakarta-velocity-tools/xdocs/site.dvsl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- site.dvsl 12 Mar 2002 11:41:14 -0000 1.2
+++ site.dvsl 2 Apr 2002 16:46:31 -0000 1.3
@@ -1,6 +1,6 @@
-#set( $relative-path = "." )
+#set( $relative-path = "file://C:/Users/Sidler/VelTools/jakarta-velocity-tools2/" )
#set( $body-bg = '#ffffff' )
#set( $body-fg = '#000000' )
@@ -107,35 +107,51 @@
#match( "menu" )
<p>
#if ($attrib.href)
- <a href="$attrib.href"><strong>$attrib.name</strong></a>
+ <a href="${relative-path}$attrib.href"><strong>$attrib.name</strong></a>
#else
<strong>$attrib.name</strong>
#end
</p>
<ul>
- $context.applyTemplates("item")
+ $context.applyTemplates()
</ul>
#end
+
#*
- * Process a menu item for the navigation bar
+ * Process a submenu for the navigation bar
*#
-#match( "item" )
- <li><a href="${relative-path}$attrib.href">$attrib.name</a></li>
+#match( "submenu" )
+
+ #if ($attrib.href)
+ <li><a href="${relative-path}$attrib.href">$attrib.name</a>
+ #else
+ <li>$attrib.name
+ #end
+ <ul>
+ $context.applyTemplates("item")
+ </ul>
+ </li>
#end
+
#*
- * Process a link to the top of the navigation hierarchy
+ * Process a menu item for the navigation bar
*#
-#match( "toplink" )
- <p><strong><a href="$attrib.href" alt="$!attrib.alt"><img src="images/caret-t.gif" alt="$!attrib.alt" border="0"/> $attrib.name</a></strong></p>
+#match( "item" )
+ #if ($attrib.href)
+ <li><a href="${relative-path}$attrib.href">$attrib.name</a></li>
+ #else
+ <li>$attrib.name</li>
+ #end
#end
+
#*
* Process a link to one layer above in the navigation hierarchy
*#
#match( "uplink" )
- <p><strong><a href="$attrib.href"><img src="images/caret-u.gif" alt="$!attrib.alt" border="0"/> $attrib.name</a></strong></p>
+ <p><strong><a href="${relative-path}$attrib.href">$attrib.name</a></strong></p>
#end
@@ -272,44 +288,49 @@
* process a 'toolinfo' block
*#
#match( "toolinfo" )
- <dl>
- <dt><strong>Version</strong></dt>
- <dd>$attrib.version</dd>
-
- <dt><strong>JAR</strong></dt>
- <dd>$attrib.jar</dd>
-
- <dt><strong>Class</strong></dt>
- <dd>$attrib.clazz</dd>
-
- <dt><strong>Name</strong></dt>
- <dd>$attrib.name (this is the recommended name of the tool in
- the Velocity context)</dd>
+ <table cellpadding="0" cellspacing="0">
+ <tr><td colspan="2"><strong>Version</strong></td></tr>
+ <tr><td> </td><td>$node.version.value()</td></tr>
+
+ <tr><td colspan="2"><strong>JAR</strong></td></tr>
+ <tr><td> </td><td>$node.jar.value()</td></tr>
+
+ <tr><td colspan="2"><strong>Class</strong></td></tr>
+ <tr><td> </td><td>$node.clazz.value()</td></tr>
+
+ <tr><td colspan="2"><strong>Name</strong></td></tr>
+ <tr><td> </td><td>$node.name.value() (this is the recommended name of the tool in
+ the Velocity context)</td></tr>
+
+ <tr><td colspan="2"><strong>Toolbox Configuration Example</strong></td></tr>
+ <tr><td> </td><td><pre>$node.copy($node.config-example.children())</pre></td></tr>
+
+ <tr><td colspan="2"><strong>Author(s)</strong></td></tr>
+ <tr><td> </td><td>#foreach($n in $node.selectNodes("author"))<a href="mailto:$n.attribute("email")">$n</a><br>#end</td></tr>
+ </table>
- <dt><strong>Author</strong></dt>
- <dd>$attrib.authors</dd>
- </dl>
#end
+
#*
* process a 'methods' block. Generates a list of methods.
*#
#match( "methods" )
- <strong>Method Overview</strong>
- <table cellpadding="2" cellspacing="2" border="0">
- #foreach ($s in $document.body.selectNodes("section") )
- #if ($s.method)
- <tr>
- <td bgcolor="EEEEEE">
- <a href="#$s.method.attrib("name")">$s.method.attrib("name")</a></td>
- <td bgcolor="EEEEEE">
- $s.method.abstract.value()
- </td>
- </tr>
- #end
- #end
- </table>
+ <strong>Method Overview</strong>
+ <table cellpadding="2" cellspacing="2" border="0">
+ #foreach ($s in $document.body.selectNodes("section") )
+ #if ($s.method)
+ <tr>
+ <td bgcolor="EEEEEE" nowrap>
+ <a href="#$s.method.attrib("name")">$s.method.attrib("name")</a></td>
+ <td bgcolor="EEEEEE">
+ $s.method.abstract.value()
+ </td>
+ </tr>
+ #end
+ #end
+ </table>
#end
1.1 jakarta-velocity-tools/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>VelTools Project</title>
<author email="geirm@apache.org">Geir Magnusson Jr.</author>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>xdocs/menue.xml</projectfile>
</properties>
<body>
<section name="Welcome to the VelTools Project">
<p>
VelTools is a subproject of Velocity. It is the umbrella project for
several Velocity subprojects that have the goal to create tools and infrastructure
useful for creating applications using the Velocity template engine.
</p>
<p><strong>Subprojects</strong></p>
<dl>
<dt><strong><a href="vellibrary.html">VelLibrary</a></strong></dt>
<dd>VelLibrary is an effort to setup a library of reuseable and well documented
context tools. Most tools are optimized for use with an automatically managed
toolbox (see VelServlet).</dd>
<dt><strong><a href="../struts/docs/index.html">VelStruts</a></strong></dt>
<dd>The VelStruts package is a set of context tools, examples and documentation for
using the Velocity template engine as a view layer technology for the
<a href="http://jakarta.apache.org/struts/">Jakarta Struts</a> web
application framework. It is based on the VelServlet project.</dd>
<dt><strong><a href="../view/docs/velservlet.html">VelServlet</a></strong></dt>
<dd>VelServlet is a standalone servlet that can be used for template
rendering in Web applications. It offers automatic population of the
Velocity context and automatic, configurable management of context tools.
Other efforts within this project are the development of a toolbox manager
and the definition of a set of interfaces for context tools, thereby enabling the
efficient handling and reuse of context tools.</dd>
<dt><strong>Utilities</strong></dt>
<dd>When in place, this will be a library of Velocity-related utilities.</dd>
<dt><strong>Velocimacros</strong></dt>
<dd>When in place, this will be a repository of Velocimacros for use in
Velocity templates.</dd>
</dl>
</section>
<section name="CVS Repository">
<p>
The code for all the efforts within the VelTools project is maintained
in the CVS repository jakarta-velocity-tools. It is available via:</p>
<p>Web Browser: <a href="http://cvs.apache.org/viewcvs/jakarta-velocity-tools/">
http://cvs.apache.org/viewcvs/jakarta-velocity-tools/</a></p>
<p>CVS Client: <a href="http://jakarta.apache.org/getinvolved/cvsindex.html">http://jakarta.apache.org/getinvolved/cvsindex.html</a>.
</p>
<p>Since VelTools is an umbrella project for several subprojects, look for
status information, releases, documentation and application examples within
the subprojects.</p>
</section>
</body>
</document>
1.1 jakarta-velocity-tools/xdocs/menue.xml
Index: menue.xml
===================================================================
<?xml version="1.0"?>
<project href="http://jakarta.apache.org/velocity/">
<title>Velocity Tools</title>
<logo href="http://jakarta.apache.org/velocity/images/logo.gif"> < :) /></logo>
<body>
<menu name="About">
<item name="Overview" href="docs/index.html"/>
<item name="CVS Repository" href="docs/index.html#CVS Repository"/>
</menu>
<menu name="Subprojects">
<item name="VelLibrary" href="docs/vellibrary.html"/>
<item name="VelStruts" href="struts/docs/index.html"/>
<item name="VelServlet" href="view/docs/velservlet.html"/>
</menu>
</body>
</project>
1.1 jakarta-velocity-tools/xdocs/vellibrary-menue.xml
Index: vellibrary-menue.xml
===================================================================
<?xml version="1.0"?>
<project href="http://jakarta.apache.org/velocity/">
<title>VelTools Menue</title>
<logo href="http://jakarta.apache.org/velocity/images/logo.gif">< :) /></logo>
<body>
<uplink name="VelTools Home" href="docs/index.html" alt="top"/>
<menu name="About VelLibrary">
<item name="Overview" href="docs/vellibrary.html"/>
<item name="Download" href="docs/vellibrary.html#Download"/>
<item name="Contributions" href="docs/vellibrary.html#Contributions"/>
</menu>
<menu name="VelLibrary Collection">
<item name="DateTool" href="tools/docs/DateTool.html"/>
<item name="MathTool" href="tools/docs/MathTool.html"/>
<item name="ParameterParser" href="tools/docs/ParameterParser.html"/>
<submenu name="Struts Tools" href="struts/docs/tools.html">
<item name="ErrorsTool" href="struts/docs/ErrorsTool.html"/>
<item name="FormTool" href="struts/docs/FormTool.html"/>
<item name="LinkTool" href="struts/docs/LinkTool.html"/>
<item name="MessageTool" href="struts/docs/MessageTool.html"/>
</submenu>
<item name="ToolLoader" href="tools/docs/ToolLoader.html"/>
</menu>
</body>
</project>
1.1 jakarta-velocity-tools/xdocs/vellibrary.xml
Index: vellibrary.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Project VelLibrary</title>
<author email="sidler@apache.org">Gabriel Sidler</author>
<projectfile>xdocs/vellibrary-menue.xml</projectfile>
</properties>
<body>
<section name="Welcome to the VelLibrary Project">
<p>VelLibrary is a Velocity subproject that aims to build of collection
of reusable and well documented context tools.</p>
<p>Emphasis is being put on providing tool documentation that is
suitable for template designers. To achive this goal, a documenation
format has been defined that captures all information relevant to the
template designer. It is being supplied in addition to the customary
Javadoc. This should help to achive what we always claim for Velocity:
"Decouple the work of template designers from the work of software
developers". Look at the <a href="../struts/docs/MessageTool.html">Struts MessageTool</a> for a good example of the
new documentation format. We are keen on your feedback. </p>
<p>Your contribution of useful context tools to the VelLibrary
project are welcome. See <a href="#Contributions">below</a> for more details.</p>
<p><strong>VelLibrary Content:</strong></p>
<dl>
<dt><a href="../tools/docs/DateTool.html"><strong>DateTool</strong></a></dt>
<dd>A tool for manipulating and formating dates.</dd>
<dt><a href="../tools/docs/MathTool.html"><strong>MathTool</strong></a></dt>
<dd>A tool for performing floating point math.</dd>
<dt><a href="../tools/docs/ParameterParser.html"><strong>ParameterParser</strong></a></dt>
<dd>A tool for easy parsing of servlet request parameters.</dd>
<dt><a href="../struts/docs/tools.html"><strong>StrutsTools</strong></a></dt>
<dd>This includes four tools that integrate Velocity with
Struts. Velocity is now a real alternative view layer technology
for Struts applications.</dd>
<dt><a href="../tools/docs/ToolLoader.html"><strong>ToolLoader</strong></a></dt>
<dd>A tool allowing template designers to load context tools
from within the template.</dd>
</dl>
</section>
<section name="Download">
<p>The is no release available at this point in time.</p>
<pre> </pre>
</section>
<section name="Contributions">
<p>We welcome your contributions to this library. Please post your offer
to contribute a tool to the
<a href="mailto:velocity-user@jakarta.apache.org">Velocity mailing list</a>.</p>
<p><strong>Checklist for Contributions</strong></p>
<ul>
<li><a href="http://jakarta.apache.org/velocity/code-standards.html">Velocity coding conventions</a></li>
<li>JavaDoc included (the more detailed the better)</li>
<li>Examples included (in JavaDoc or as stand-alone template example)</li>
</ul>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>