You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by ap...@apache.org on 2010/11/26 13:17:45 UTC
svn commit: r1039326 - in /velocity/engine/branches/2.0_Exp/src/site:
apt/release.apt site.xml xdoc/build.xml xdoc/developer-guide.xml
xdoc/getting-started.xml xdoc/jar-dependencies.xml xdoc/user-guide.xml
Author: apetrelli
Date: Fri Nov 26 12:17:45 2010
New Revision: 1039326
URL: http://svn.apache.org/viewvc?rev=1039326&view=rev
Log:
VELOCITY-788
Updated existing files and added release process guide.
Added:
velocity/engine/branches/2.0_Exp/src/site/apt/release.apt
Modified:
velocity/engine/branches/2.0_Exp/src/site/site.xml
velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml
velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml
velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml
velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml
velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml
Added: velocity/engine/branches/2.0_Exp/src/site/apt/release.apt
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/apt/release.apt?rev=1039326&view=auto
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/apt/release.apt (added)
+++ velocity/engine/branches/2.0_Exp/src/site/apt/release.apt Fri Nov 26 12:17:45 2010
@@ -0,0 +1,348 @@
+~~ $Id$
+~~
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~
+ -----------
+ Release Process
+ -----------
+
+Velocity Engine Release Process
+
+ Here you will find the steps to create releases for Velocity Engine.
+
+Prerequisites
+
+ To create a release you have to install:
+
+ * {{{http://java.sun.com/j2se/1.5.0/}Java 5.0}}. If you are using a newer
+ version of Java, it is suggested to <<change JAVA_HOME environment variable>>
+ when calling Maven, so it points to an instance of Java 5.0;
+
+ * {{{http://maven.apache.org/}Maven 2}};
+
+ * {{{http://www.gnupg.org/}GnuPG}};
+
+ * {{{http://www.openssh.com/}OpenSSH}};
+
+One-time operations
+
+ These operations need to be performed only one time.
+
+* Create and publish your GPG key
+
+ To create a GPG key, follow the
+ {{{http://www.apache.org/dev/openpgp.html}guidelines}}.
+ Insert in the file you find on people.apache.org at the directory:
+
+-------------------------------------
+/www/www.apache.org/dist/velocity/
+-------------------------------------
+
+ Publish your GPG key in a PGP key server, such as
+ {{{http://pgp.mit.edu/} MIT Keyserver}}.
+
+* Create and upload yout SSH key
+
+ * Generate your SSH key (in this case we will use RSA encryption):
+
+---------------------------------
+ssh-keygen -t rsa
+---------------------------------
+
+ * Copy your public key to the server:
+
+--------------------------------------
+scp ~/.ssh/id_rsa.pub user@people.apache.org:.ssh/authorized_keys
+--------------------------------------
+
+ * Try to login:
+
+---------------------------------
+ssh user@people.apache.org
+---------------------------------
+
+ If it does not ask you a password, everything is ok.
+
+* Modify <<<settings.xml>>>
+
+ Your <<<settings.xml>>> must be modified to allow deployment.
+
+ This is the minimal configuration, obviously if you already have a <<<settings.xml>>> file,
+ you must edit it:
+
+---------------------------
+<settings xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+ http://maven.apache.org/xsd/settings-1.0.0.xsd">
+ <servers>
+ <server>
+ <id>apache-site</id>
+ <username>YOUR_APACHE_USERNAME</username>
+ <filePermissions>664</filePermissions>
+ <directoryPermissions>775</directoryPermissions>
+ </server>
+ <server>
+ <id>apache.snapshots.https</id>
+ <username>YOUR_APACHE_USERNAME</username>
+ <password>YOUR_APACHE_PASSWORD</password>
+ </server>
+ <server>
+ <id>apache.releases.https</id>
+ <username>YOUR_APACHE_USERNAME</username>
+ <password>YOUR_APACHE_PASSWORD</password>
+ </server>
+ </servers>
+ <profiles>
+ <profile>
+ <id>release</id>
+ <properties>
+ <gpg.passphrase>YOUR_SECRET_PHRASE</gpg.passphrase>
+ </properties>
+ </profile>
+ </profile>
+ </profiles>
+</settings>
+---------------------------
+
+Repeatable operations
+
+ These steps must be performed <<for each>> release.
+
+* Prepare the release tag
+
+ To prepare the release Subversion tag, check out the branch/trunk from where
+ you are preparing the release and type:
+
+-----------------------------------
+mvn release:prepare -Dusername=YOUR_SVN_USER -Dpassword=YOUR_SVN_PASSWORD
+-----------------------------------
+
+ The plugin interactively will ask you the version to release, the Subversion
+ tag to use and the next snapshot version. It is reccomended to use the tag:
+ <<velocity-engine-parent-X.X.X>> (the default).
+
+* Perform the Release
+
+ To perform the release, i.e. creating and deploying Maven artifacts, use:
+
+-----------------------------------
+mvn release:perform
+-----------------------------------
+
+* Close the staging repository
+
+ Login to {{{https://repository.apache.org using} Nexus repository}} your Apache LDAP credentials.
+ Click on "Staging". Then click on "velocity" in the list of repositories.
+ In the panel below you should see an open repository that is linked to your username and ip.
+ Right click on this repository and select "Close".
+ This will close the repository from future deployments and make it available for others to view.
+ If you are staging multiple releases together, skip this step until you have staged everything.
+ Enter the name and version of the artifact being released in the "Description" field and then click "Close".
+ This will make it easier to identify it later.
+
+* Verify the staged artifacts
+
+ If you click on your repository, a tree view will appear below.
+ You can then browse the contents to ensure the artifacts are as you expect them.
+ Pay particular attention to the existence of *.asc (signature) files.
+ If the you don't like the content of the repository, right click your repository and choose "Drop".
+ You can then rollback your release and repeat the process.
+
+ Note the repository URL, you will need this in your vote email.
+
+* Digest and upload assemblies
+
+ * Go into the release assembly target directory:
+
+-----------------------------------
+cd target/checkout/assembly/target/assembly/out
+-----------------------------------
+
+ * Create MD5 and SHA1 files for each files (including ASC files). You can do
+ it with this simple shell script:
+
+-----------------------------------
+#!/bin/sh
+
+for fileitem in *
+do
+ openssl md5 < $fileitem > $fileitem.md5
+ openssl sha1 < $fileitem > $fileitem.sha1
+done
+-----------------------------------
+
+ * Upload everything to the build site:
+
+-----------------------------------
+scp * user@people.apache.org:/www/people.apache.org/builds/velocity-engine-parent/${version}
+-----------------------------------
+
+* Release the JIRA version
+
+ * In JIRA go to the version that you want to release and release it.
+
+ * Create a new version, if it has not been done before.
+
+ * Create the release notes and <<write down the link>> that it uses.
+
+* Send announcement for the test build
+
+ In <<developers mailing list>> send an announcement for the test build:
+
+-----------------------------------
+Subject: [ANNOUNCE] Velocity Engine ${version} test build available
+
+The test build of Velocity Engine ${version} is available.
+
+
+No determination as to the quality ('alpha,' 'beta,' or 'GA') of Velocity Engine
+${version} has been made, and at this time it is simply a "test build". We
+welcome any comments you may have, and will take all feedback into
+account if a quality vote is called for this build.
+
+Release notes:
+
+* ${jira.release.notes}
+
+Distribution:
+
+ * http://people.apache.org/builds/velocity-engine-parent/${version}/
+
+Maven 2 staging repository:
+
+ * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/
+
+A vote regarding the quality of this test build will be initiated
+within the next couple of days.
+-----------------------------------
+
+* Call for a vote
+
+ A few days after the test build announcement, call for a vote in
+ <<developers mailing list>>.
+
+-----------------------------------
+Subject: [VOTE] ${version} Release Quality
+
+The Velocity Engine ${version} test build has been available since ${testBuildDate}.
+
+Release notes:
+
+* ${jira.release.notes}
+
+Distribution:
+
+ * http://people.apache.org/builds/velocity-engine-parent/${version}/
+
+Maven 2 staging repository:
+
+ * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/
+
+If you have had a chance to review the test build, please respond with
+a vote on its quality:
+
+ [ ] Leave at test build
+ [ ] Alpha
+ [ ] Beta
+ [ ] General Availability (GA)
+
+
+Everyone who has tested the build is invited to vote. Votes by PMC
+members are considered binding. A vote passes if there are at least
+three binding +1s and more +1s than -1s.
+-----------------------------------
+
+* Post-vote operations
+
+ After a vote is finished, and it has been decided that is
+ <<at least of alpha quality>>, there is the need of a post-vote process.
+
+** Promote staged artifacts
+
+ Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users.
+
+ Login to {{{https://repository.apache.org}Nexus repository}} again.
+ Click on "Staging" and then on the repository with id "velocity-staging".
+ Find your closed staging repository, right click on it and choose "Promote".
+ Select the "Releases" repository and click "Promote".
+
+ Next click on "Repositories", select the "Releases" repository
+ and validate that your artifacts exist as you expect them.
+
+** Move assemblies
+
+ * Move assemblies to the Apache distribution mirrors:
+
+-------------------------------------------
+ssh user@people.apache.org
+
+cd /www/people.apache.org/builds/velocity/${version}
+mkdir /www/www.apache.org/dist/velocity/v${version}/
+cp * /www/www.apache.org/dist/velocity/v${version}/
+-------------------------------------------
+
+** Update the site
+
+ * Wait 24 hours to let the mirror sync to the release and then update the
+ site. In particular you have to update the index and the download pages:
+
+------------------------------------------------
+https://svn.apache.org/repos/asf/velocity/site/site/xdoc/download.xml
+https://svn.apache.org/repos/asf/velocity/site/site/news.xml
+------------------------------------------------
+
+ Build and publish the site:
+
+--------------------------------------
+mvn site
+mvn site:deploy
+--------------------------------------
+
+** Send announcement
+
+ Finally, send an an announcement to the <<users>> and <<developers mailing
+ list>>:
+
+--------------------------------------
+Subject: [ANNOUNCE] Velocity Engine ${version} ${quality} released
+
+The Apache Velocity team is pleased to announce the release of Velocity Engine ${version}
+${quality}.
+
+Velocity Engine ${version} is available in a binary and a source distribution.
+
+http://velocity.apache.org/download.html
+
+It is also available in the central Maven repository under Group ID
+"org.apache.velocity".
+
+The 2.0.x series of the Apache Velocity Engine framework has a minimum
+requirement of the following specification versions:
+
+* Java Standard Edition (Java SE) 1.6
+
+The release notes are available online at:
+
+* ${jira.release.notes}
+
+Please feel free to test the distribution and post your comments to
+the user list, or, if appropriate, file a ticket with JIRA.
+--------------------------------------
+
+ <<You have finished!>>
\ No newline at end of file
Modified: velocity/engine/branches/2.0_Exp/src/site/site.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/site.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/site.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/site.xml Fri Nov 26 12:17:45 2010
@@ -87,6 +87,7 @@
<item name="Dependencies" href="jar-dependencies.html"/>
<item name="Source Code Repository" href="http://svn.apache.org/viewvc/velocity/engine/trunk/"/>
<item name="Building from Source" href="build.html"/>
+ <item name="Release Process" href="release.html"/>
</menu>
<menu name="Community">
Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<document>
@@ -30,166 +30,51 @@
<section name="Installation">
<p>
-Velocity runs on a variety of platforms that have installed the Java 2
-Virtual Machine. The J2SDK is required for users who want to compile
+Velocity runs on a variety of platforms that have installed the Java
+Virtual Machine. The Java Development Kit version 1.6 is required for users who want to compile
Velocity from its source code.
</p>
<p>
Everything required to build Velocity comes with the distribution, which
can be obtained from <a
-href="http://www.apache.org/dev/version-control.html">Subversion</a> or
+href="http://svn.apache.org/repos/asf/velocity/engine/">Subversion</a> or
from the <a
-href="http://vc.apache.org/snapshots/velocity/">nightly
-snapshots</a>. However, you will need to install Ant to build the Velocity sources.</p>
+href="http://velocity.apache.org/download.cgi#Engine">main distribution</a>.
+However, you will need to install <a href="http://maven.apache.org/">Maven</a> to build the Velocity sources.</p>
-<p>Ant is also an Apache project, and can be
-found <a href="http://ant.apache.org/">here</a>. To build Apache Velocity, you need at least Version 1.6 of Apache Ant.
+<p><a href="http://maven.apache.org/">Maven</a> is also an Apache project.
+To build Apache Velocity, you need at least Version 2.2.1 of Apache Maven.
</p>
-<p>
-The directory tree of the distribution looks like:
-</p>
-
-<source><![CDATA[
-build/ This is where the build scripts live.
-convert/ The WebMacro to Apache Velocity conversion program.
-docs/ Velocity Documentation in HTML format.
-docs/api/ Velocity Javadocs.
-examples/ Examples how to use Velocity.
-lib/ Dependencies for building and using Velocity.
-lib/test/ Dependencies needed for the various unit tests.
-src/ This is where all of the source code is located.
-test/ Contains test files needed for the unit tests.
-xdocs/ Here are the .xml files for building the .html files
- related to the website and documentation. The files
- located in docs/ have been built from these sources.
-]]></source>
-
</section>
<section name="Required Tools">
<p>
-To make building Velocity easy and consistent, we require an Apache project
-called <a href="http://ant.apache.org/">Ant</a> version 1.6 or
-higher to perform the build process. We assume that you have followed
-Ant's installation instructions and have it properly installed.
+To build Velocity we require <a href="http://maven.apache.org/">Maven</a>
+version 2.2.1 or higher (Mave 3 can be used too) to perform the build process.
+We assume that you have followed Maven's installation instructions and have it properly installed.
</p>
<p>
-Velocity requires JDK 1.4 or greater to compile. It's possible to use JDK 1.3
-to compile but several useful features will not be included. Velocity requires
-a minimum of JDK 1.3 to run.
+Velocity requires JDK 1.6 or greater to compile.
</p>
<p>
Finally, if you wish to modify Velocity's grammar you will need to a tool
-called <a href="http://javacc.dev.java.net">JavaCC</a>. We recommend
+called <a href="http://javacc.dev.java.net">JavaCC</a>. We recommend
version 3.2 or greater (for compatibility with JDK 1.5 syntax changes).
</p>
</section>
-<section name="Jar Dependencies">
-
-<p>Velocity requires various third party jar files for compiling and
-for running. Not all jar files are required in all cases. When
-building, all dependencies will be downloaded automatically. You can
-control the download with the <code>skip.jar.loading</code> and
-<code>force.jar.loading</code> properties in the
-<code>build.properties</code> file.
-</p>
-
-<table>
-
-<tr>
- <th>Jar</th>
- <th>Purpose</th>
- <th>Required at Runtime?</th>
-</tr>
-
-<tr>
- <td><code>antlr-2.7.5.jar</code></td>
- <td>XML parsing (XPath queries in particular)</td>
- <td>Only for Anakia</td>
-</tr>
-<tr>
- <td><code>avalon-logkit-2.1.jar</code></td>
- <td>Possible means of logging</td>
- <td>No</td>
-</tr>
-<tr>
- <td><code>commons-collection-3.1.jar</code></td>
- <td>Used in parsing configuration</td>
- <td>Yes</td>
-</tr>
-<tr>
- <td><code>commons-lang-2.1.jar</code></td>
- <td>Various String utility functions</td>
- <td>Yes</td>
-</tr>
-<tr>
- <td><code>commons-logging-1.1.jar</code></td>
- <td>To redirect log output to commons-logging</td>
- <td>Only for those using commons-logging</td>
-</tr>
-<tr>
- <td><code>jdom-1.0.jar</code></td>
- <td>XML parsing</td>
- <td>Only for Anakia</td>
-</tr>
-<tr>
- <td><code>log4j.1.2.12.jar</code></td>
- <td>Possible means of logging</td>
- <td>No</td>
-</tr>
-<tr>
- <td><code>oro-2.0.8.jar</code></td>
- <td>For regular expression parsing in tests and event handlers</td>
- <td>Only for reference escaping event handlers</td>
-</tr>
-<tr>
- <td><code>servletapi-2.3.jar</code></td>
- <td>For the deprecated VelocityServlet and redirecting log output to the servlet log.</td>
- <td>Only for VelocityServlet or ServletLogChute</td>
-</tr>
-<tr>
- <td><code>werken-xpath-0.9.4.jar</code></td>
- <td>XML parsing</td>
- <td>Only for Anakia</td>
-</tr>
-<tr>
- <td><code>junit-3.8.1.jar</code></td>
- <td>For running unit tests</td>
- <td>No</td>
-</tr>
-<tr>
- <td><code>hsqldb-1.7.1.jar</code></td>
- <td>For running database related unit tests</td>
- <td>No</td>
-</tr>
-<tr>
- <td><code>ant.jar</code></td>
- <td>Required for compilation. Provided by the ant build tool.</td>
- <td>No</td>
-</tr>
-</table>
-
-
-<p>
-Note that you can always create a jar with all required run-time dependencies by executing the
-<code>jar-dep</code> task.
-</p>
-
-</section>
-
<section name="Building">
<p>
In each case below, it is assumed that you were successful in getting
-the distribution from Subversion or as a nightly build, and with the latter,
+the distribution from Subversion, and with the latter,
were successful in unpacking. Also, it is assumed that you are starting
in the 'velocity' directory, the root of the distribution tree.
All directory references will be relative to 'velocity'.
@@ -201,151 +86,27 @@ build</code>). Then, to build the jar fi
</p>
<source><![CDATA[
-ant
+mvn install
]]></source>
<p>
-Executing this script will create a <b>bin</b> directory
-within the Velocity distribution directory. The <b>bin</b>
-directory will contain the compiled class files (inside a
-<b>classes</b> directory) as well as a
-<b>velocity-XX.jar</b> file, where XX is the current
-version number. Be sure to update your classpath to include Velocity's
-<b>.jar</b> file.
+Executing this script will create a <b>target</b> directory
+within the Velocity distribution directory. Each subdirectory
+containing a module of Velocity will contain a "target" directory
+too, containing all built jars. In the "velocity-assembly" module
+you will find built distributions.
</p>
<p>
-Note that to build any of the specific build targets simply add
-the target name to the command line. For example, to build the Javadoc
-API documentation:
+Refer to Maven documentation for all phases you can invoke.
</p>
-<source><![CDATA[
-ant javadocs
-]]></source>
-
-
-<p>Some of the most useful targets are:
-</p>
-
-<ul>
- <li>
- <b><code>jar</code></b> builds the complete Velocity jar in the
- <code>bin</code> directory. This jar will be called 'velocity-X.jar',
- where 'X' is the current version number. This jar does not include
- necessary dependencies for Velocity. If you use this
- target, you must put the required dependent jars in your CLASSPATH (or WEB-INF/lib).
- For convenience, you can use the <code>jar-dep</code> target to build
- a jar with all required dependent classes included.
- </li>
- <li>
- <b><code>jar-dep</code></b> builds the complete Velocity jar in
- the <code>bin</code> directory.
- </li>
- <li>
- <b><code>clean</code></b> deletes all generated classes, jars, documentation, and other files.
- </li>
- <li>
- <b><code>real-clean</code></b> like <code>clean</code> but also deletes all downloaded jars.
- </li>
- <li>
- <b><code>docs</code></b> builds these docs in the <code>docs</code> directory
- using Velocity's <a href="anakia.html">Anakia</a> XML transformation tool.
- Allows you to use
- Velocity templates in place of stylesheets
- - give it a try!
- </li>
- <li>
- <b><code>examples</code></b> builds the example code in the example programs
- found in the <code>examples</code> directory.
- </li>
- <li>
- <b><code>jar-src</code></b> bundles all the Velocity source code into a single
- jar, placed in the <code>bin</code> directory.
- </li>
- <li>
- <b><code>javadocs</code></b> builds the Javadoc class documentation in the
- <code>docs/api</code> directory
- </li>
- <li>
- <b><code>package</code></b> will generate the complete Velocity distribution package.
- </li>
- <li>
- <b><code>parser</code></b> will compile the JavaCC parser files from src/Parser.jjt into
- the appropriate Java source files. Requires JavaCC 3.2+ to be installed, and the
- property <code>javacc.home</code> to contain a path to the installed JavaCC directory.
- </li>
- <li>
- <b><code>test</code></b> (after jar) will test Velocity against its testbed
- suite of test routines.
- </li>
-</ul>
-
-
-
<p>
-Velocity should build 'out of the box', independent of your classpath.
-If you get an error building Velocity, try a different nightly build (as
-sometimes we make a mistake and the Subversion at the time of the nightly
-snapshot isn't complete) or refresh from Subversion (you might have gotten a
-Subversion snapshot while a developer was checking things in.)
-</p>
-
-<p>
-If the problems persist, do not hesitate to ask the Velocity community
+If you find a problem, do not hesitate to ask the Velocity community
via our mail lists. They can be found <a
-href="http://velocity.apache.org/contact.html">here</a>.
-</p>
-
-</section>
-
-<section name="Testing Your Installation">
-
-<p>
-The Velocity developers use an automated test facility, and it is
-included in the distribution. You can use it to make sure that all is
-well with your build of Velocity.
-</p>
-
-<p>The tests are run with the ant task <junit>. For ant 1.6, this task requires that
-<code>junit.jar</code> be copied into the <code>lib</code> subdirectory of your
-ant directory. For ant 1.7 this is not required.
-</p>
-
-<p>
-To run the test suite, simply use the build target
-<b>test</b> when you build:
+href="http://velocity.apache.org/contact.html">here</a>.
</p>
-<source><![CDATA[
-ant test
-]]></source>
-
-<p>
-If all is well, you should see output similar to:
-</p>
-
-<source><![CDATA[
-test:
- [mkdir] Created dir: ..../bin/test-reports
- [junit] Running org.apache.velocity.io.UnicodeInputStreamTestCase
- [junit] Tests run: 8, Failures: 0, Errors: 0, Time elapsed: 0.011 sec
- [junit] Running org.apache.velocity.test.AbsoluteFileResourceLoaderTestCase
- [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.015 sec
- [junit] Running org.apache.velocity.test.ArithmeticTestCase
- [junit] Tests run: 7, Failures: 0, Errors: 0, Time elapsed: 0.006 sec
- [junit] Running org.apache.velocity.test.BuiltInEventHandlerTestCase
-...
-
-BUILD SUCCESSFUL
-Total time: 42 seconds
-
-]]></source>
-
-<p>
-Note that the number of tests may vary from those shown above, but if
-you see 'OK' after the tests are run, all is well.
-</p>
</section>
</body>
Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<document>
@@ -163,8 +163,8 @@ more detail on the various options.
<p>
You can download the latest release version of
- <a href="http://velocity.apache.org/download.cgi#engine">Velocity</a>
- or <a href="http://velocity.apache.org/download.cgi#tools">Velocity Tools</a>
+ <a href="http://velocity.apache.org/download.cgi#Engine">Velocity</a>
+ or <a href="http://velocity.apache.org/download.cgi#Tools">Velocity Tools</a>
from the main Apache Velocity download site. For Velocity itself, source is included with the binary download.
</p>
@@ -571,7 +571,7 @@ in the VTL <code>#foreach()</code> direc
here. Velocity will internally wrap your array in a class that provides an
Iterator interface, but that shouldn't concern you as the programmer, or the
template author. Of more interest, is the fact that Velocity will now
-allow template authors to treat arrays as fixed-length lists (as of Velocity 1.6).
+allow template authors to treat arrays as fixed-length lists (as of Velocity 1.6).
This means they may call methods like <code>size()</code>,
<code>isEmpty()</code> and <code>get(int)</code> on both arrays and standard
java.util.List instances without concerning themselves about the difference.
@@ -1128,10 +1128,10 @@ template content other than template fil
<a name="exceptions"><strong>Exceptions</strong></a>
<p>
-Velocity may throw one of several exceptions during the parse / merge cycle. These
+Velocity may throw one of several exceptions during the parse / merge cycle. These
exceptions extend RuntimeException and do not need to explicitly caught,
although each includes specific properties that may help in presenting
-useful error messages to the end user. The exceptions
+useful error messages to the end user. The exceptions
are found in the package <code>org.apache.velocity.exception</code> and are:
</p>
@@ -1311,15 +1311,15 @@ Velocity contains a fine-grained event h
<p>
<i><code>org.apache.velocity.app.event.IncludeEventHandler</code></i>
<blockquote>
-The <code>IncludeEventHandler</code> can be used to modify the template that is included
+The <code>IncludeEventHandler</code> can be used to modify the template that is included
in a page with <code>#include</code> or <code>#parse</code>. For example, this may be used to make all includes relative to the current directory or to prevent access to unauthorized resources.
Multiple <code>IncludeEventHandler</code>'s may be chained, with the return value of the final
call used as the name of the template to retrieve.
<pre>
public IncludeEventHandler extends EventHandler
{
- public String includeEvent( String includeResourcePath,
- String currentResourcePath,
+ public String includeEvent( String includeResourcePath,
+ String currentResourcePath,
String directiveName );
}
</pre>
@@ -1338,21 +1338,21 @@ calls behave will differ per method. (S
<pre>
public InvalidReferenceEventHandler extends EventHandler
{
- public Object invalidGetMethod( Context context,
- String reference,
- Object object,
- String property,
+ public Object invalidGetMethod( Context context,
+ String reference,
+ Object object,
+ String property,
Info info);
- public boolean invalidSetMethod( Context context,
- String leftreference,
- String rightreference,
+ public boolean invalidSetMethod( Context context,
+ String leftreference,
+ String rightreference,
Info info);
- public Object invalidMethod( Context context,
- String reference,
- Object object,
- String method,
+ public Object invalidMethod( Context context,
+ String reference,
+ Object object,
+ String method,
Info info);
}
</pre>
@@ -1370,13 +1370,13 @@ When a user-supplied method throws an ex
and thrown Exception. The handler can either return a valid Object to be used
as the return value of the method call or throw the passed-in or new Exception,
which will be wrapped and propogated to the user as a
-<code>MethodInvocationException</code>. While <code>MethodExceptionEventHandler</code>'s can be
+<code>MethodInvocationException</code>. While <code>MethodExceptionEventHandler</code>'s can be
chained only the first handler is actually called -- all others are ignored.
<pre>
public interface MethodExceptionEventHandler extends EventHandler
{
- public Object methodException( Class claz,
- String method,
+ public Object methodException( Class claz,
+ String method,
Exception e )
throws Exception;
}
@@ -1392,12 +1392,12 @@ Available implementations include:
<blockquote>
A <code>ReferenceInsertionEventHandler</code> allows the
developer to intercept each write of a reference ($foo) value to the output
-stream and modify that output. Multiple <code>ReferenceInsertionEventHandler</code>'s
+stream and modify that output. Multiple <code>ReferenceInsertionEventHandler</code>'s
may be chained with each step potentially altering the inserted reference.
<pre>
public interface ReferenceInsertionEventHandler extends EventHandler
{
- public Object referenceInsert( String reference,
+ public Object referenceInsert( String reference,
Object value );
}
</pre>
@@ -1460,12 +1460,12 @@ public class Test
....
/**
- * Make a cartridge to hold the event handlers
+ * Make a cartridge to hold the event handlers
*/
EventCartridge ec = new EventCartridge();
/*
- * then register and chain two escape-related handlers
+ * then register and chain two escape-related handlers
*/
ec.addEventHandler(new EscapeHtmlReference());
ec.addEventHandler(new EscapeSqlReference());
@@ -1680,7 +1680,7 @@ runtime log.
</p>
<p>
-<code>resource.manager.cache.class</code>
+<code>resource.manager.cache.class</code>
<br/>
Declares the class to be used
for resource caching. The current default is
@@ -1692,7 +1692,7 @@ is 89. Note that the ConcurrentHashMap
</p>
<p>
-<code>resource.manager.defaultcache.size</code>
+<code>resource.manager.defaultcache.size</code>
<br/>
Sets the size of the default implementation of the resource
manager cache size. The default is 89.
@@ -1824,7 +1824,7 @@ This feature is intended for development
<code>velocimacro.arguments.strict = false</code><br/>
When set to true, will throw a <code>ParseErrorException</code> when
parsing a template containing a macro with an invalid number of arguments.
-Is set to false by default to maintain backwards compatibility with
+Is set to false by default to maintain backwards compatibility with
templates written before this feature became available.
</p>
@@ -1862,7 +1862,7 @@ New in Velocity 1.6, when set to true Ve
defined in the context, or have not been defined with a #set
directive. This setting will also throw an exception if an attempt is
made to call a non-existing property on an object or if the object is
-null. When this property is true then
+null. When this property is true then
'directive.foreach.skip.invalid' defaults to true,
but explicitly setting 'directive.foreach.skip.invalid' will
override this default. For a complete discussion see <a
Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<document>
@@ -65,8 +65,8 @@ Application Guide is highly recommended!
<section name="Downloading Velocity" href="DownloadingVelocity">
<p>
You can download the latest release version of
- <a href="http://velocity.apache.org/download.cgi#engine">Velocity</a>
- or <a href="http://velocity.apache.org/download.cgi#tools">Velocity Tools</a>
+ <a href="http://velocity.apache.org/download.cgi#Engine">Velocity</a>
+ or <a href="http://velocity.apache.org/download.cgi#Tools">Velocity Tools</a>
from the main Apache Velocity download site. For Velocity itself, source is included with the binary download.
</p>
Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<document>
@@ -75,37 +75,9 @@
</tr>
<tr>
<td>servletapi</td><td>No</td>
- <td>Only needed when the <a
- href="apidocs/org/apache/velocity/servlet/VelocityServlet.html">VelocityServlet</a>
- or <a href="apidocs/org/apache/velocity/runtime/log/ServletLogChute.html">ServletLogChute</a> are used.
- Should normally be supplied by the servlet container.
- <b>VelocityServlet is deprecated and should
- be replaced with VelocityViewServlet from the
- <a href="http://velocity.apache.org/tools/devel/">velocity-tools</a> distribution.</b></td>
- </tr>
- <tr>
- <td>jdom</td><td>No</td>
- <td>Only required for the deprecated Anakia tool / ant task</td>
- </tr>
- <tr>
- <td>werken-xpath</td><td>No</td>
- <td>Only required for the deprecated Anakia tool / ant task</td>
- </tr>
- <tr>
- <td>antlr</td><td>No</td>
- <td>Only required for the deprecated Anakia tool / ant task</td>
- </tr>
- <tr>
- <td>ant</td><td>No</td>
- <td>Only needed for compilation.</td>
- </tr>
- <tr>
- <td>junit</td><td>No</td>
- <td>Only needed for running the tests during compilation.</td>
- </tr>
- <tr>
- <td>hsqldb</td><td>No</td>
- <td>Only needed for running the tests during compilation.</td>
+ <td>Only needed when the
+ <a href="apidocs/org/apache/velocity/runtime/log/ServletLogChute.html">ServletLogChute</a> is used.
+ Should normally be supplied by the servlet container.</td>
</tr>
</table>
@@ -117,10 +89,7 @@
you should check if you need to update their versions.
</p>
- <p>The <a href="dependencies.html">auto-generated dependency report</a> lists all mandatory
- dependencies as <b>compile</b> and all optional dependencies as <b>provided</b>, though
- it fails to properly reflect the optional nature of the Oro and Commons-Logging dependencies.
- </p>
+ <p>Take a look at each module documentation to see all dependencies in detail</p>
</section>
</body>
</document>
Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<document>
@@ -37,6 +37,12 @@
<li><a href="#The_Mud_Store_Example">The Mud Store example</a></li>
</ol>
</li>
+<li><a href="#What_jar_should_I_use">What jar should I use?</a>
+ <ol>
+ <li><a href="#Maven_users">Maven users</a></li>
+ <li><a href="#Other_users">Other users</a></li>
+ </ol>
+</li>
<li><a href="#Velocity_Template_Language_VTL:_An_Introduction">Velocity Template Language (VTL): An Introduction</a></li>
<li><a href="#Hello_Velocity_World">Hello Velocity World!</a></li>
<li><a href="#Comments">Comments</a></li>
@@ -226,6 +232,75 @@ Hello $customer.Name!
</section>
+
+<section name="What jar should I use?" href="What_jar_should_I_use">
+ <p>
+ Velocity Engine 2.x distribution has several jars, related to the Maven
+ artifacts that are published to the Maven repository.
+ </p>
+ <subsection name="Maven users" href="Maven_users">
+ <p>
+ Include the following dependency to your POM file:
+ </p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>velocity-engine-core</artifactId>
+ <version>x.x.x</version>
+</dependency>]]>
+ </source>
+ <p>If you want to connect Velocity log facility to Commons Logging, Log4j or the servlet logger,
+ choose the appropriate dependency:</p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>velocity-engine-commons-logging</artifactId>
+ <version>x.x.x</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>velocity-engine-log4j</artifactId>
+ <version>x.x.x</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.velocity</groupId>
+ <artifactId>velocity-engine-servlet</artifactId>
+ <version>x.x.x</version>
+</dependency>
+]]>
+ </source>
+ </subsection>
+ <subsection name="Other users" href="Other_users">
+ <p>
+ First of all <a href="http://velocity.apache.org/download.cgi#Engine">download Velocity Engine distribution</a>.
+ </p>
+ <p>
+ If you want to jumpstart your application, simply include <strong>velocity-x.x.x.jar</strong>
+ in your classpath: it includes all classes of Velocity Engine (with the exclusion of the examples).
+ Include all the jars in the "lib" subdirectory too.
+ </p>
+ <p>
+ The other jars are finely-grained jars that contain only what you might need.
+ </p>
+ <ul>
+ <li><strong>velocity-engine-core-x.x.x.jar</strong>: The main Velocity library. It
+ must be included at all times.</li>
+ <li><strong>velocity-engine-commons-logging-x.x.x.jar</strong>: It contains the binding to
+ Commons Logging, so all log messages will be directed to it. To be used in
+ conjunction with Commons Logging (included in "lib" directory).</li>
+ <li><strong>velocity-engine-log4j-x.x.x.jar</strong>: It contains the binding to
+ Log4j, so all log messages will be directed to it. To be used in
+ conjunction with Log4j (included in "lib" directory).</li>
+ <li><strong>velocity-engine-servlet-x.x.x.jar</strong>: It contains the binding to
+ the servlet logger. To be used in a servlet container.</li>
+ </ul>
+ <p>The extra jars you will always need always are Commons Collections and Commons Lang,
+ included in "lib" directory.</p>
+ </subsection>
+</section>
+
<section name="Velocity Template Language (VTL): An Introduction" href="velocity_template_language_vtl:_an_introduction">
<p>
@@ -375,7 +450,7 @@ visible. *# This text is outside the com
<p>
There is a third type of comment, the VTL comment block, which may
- be used to store any sort of extra information you want to track
+ be used to store any sort of extra information you want to track
in the template (e.g. javadoc-style author and versioning information):
</p>
@@ -611,7 +686,7 @@ $sun.setPlanets()
</p>
<p>
- <a name="index"><strong>Index Notation</strong></a>
+ <a name="index"><strong>Index Notation</strong></a>
<br/>
Using the notation of the form <code>$foo[0]</code> can be used to access a
given index of an object. This form is synonymous with calling
@@ -621,7 +696,7 @@ $sun.setPlanets()
following are valid uses:
</p>
<source>$foo[0] ## $foo takes in an Integer look up
-$foo[$i] ## Using another reference as the index
+$foo[$i] ## Using another reference as the index
$foo["bar"] ## Passing a string where $foo may be a Map</source>
<p>
The bracketed syntax also works with Java arrays since Velocity
@@ -632,7 +707,7 @@ $foo["bar"] ## Passing a string where
<p>
The bracketed syntax is valid anywhere <code>.get</code> is valid,
for example:
- </p>
+ </p>
<source>$foo.bar[1].junk
$foo.callMethod()[1]
$foo["apple"][4]</source>
@@ -769,14 +844,14 @@ Jack is a ${vice}maniac.
<source><![CDATA[$foo ## Exception
#set($bar = $foo) ## Exception
#if($foo == $bar)#end ## Exception
-#foreach($item in $foo)#end ## Exception]]></source>
+#foreach($item in $foo)#end ## Exception]]></source>
<p>
Also, The following statements show examples in which Velocity will
throw an exception when attempting to call methods or properties
that do not exist. In these examples $bar contains an object that
defines a property 'foo' which returns a string, and 'retnull' which
returns null.
- </p>
+ </p>
<source><![CDATA[$bar.bogus ## $bar does not provide property bogus, Exception
$bar.foo.bogus ## $bar.foo does not provide property bogus, Exception
$bar.retnull.bogus ## cannot call a property on null, Exception]]></source>
@@ -1576,10 +1651,10 @@ $count
<p>
The <em>#evaluate</em> directive can be used to dynamically evaluate VTL. This allows
the template to evaluate a string that is created at render time. Such a string might be
- used to internationalize the template or to include parts of a template from a database.
+ used to internationalize the template or to include parts of a template from a database.
</p>
- <p>The example below will display <code>abc</code>.
+ <p>The example below will display <code>abc</code>.
</p>
<source><![CDATA[
@@ -1590,7 +1665,7 @@ $count
#evaluate($dynamicsource)
]]></source>
-
+
</section>
<section name="Define" href="define">
@@ -1599,7 +1674,7 @@ $count
The <em>#define</em> directive lets one assign a block of VTL to a reference.
</p>
- <p>The example below will display <code>Hello World!</code>.
+ <p>The example below will display <code>Hello World!</code>.
</p>
<source><![CDATA[
@@ -1608,7 +1683,7 @@ $count
$block
]]></source>
-
+
</section>
<section name="Velocimacros" href="velocimacros">
@@ -2054,7 +2129,7 @@ ${D}{my:invalid:non:reference}
<p>You can, of course, put your <code>$</code> or <code>#</code> string directly
into the context from your java code (e.g. <code>context.put("D","$");</code>)
to avoid the extra #set() directive in your template(s). Or, if you are using
- <a href="http://velocity.apache.org/tools/devel/">VelocityTools</a>, you can
+ <a href="http://velocity.apache.org/tools/devel/">VelocityTools</a>, you can
just use the EscapeTool like this:</p>
<source><![CDATA[