Author: cbrisson
Date: Wed Jan 25 22:37:29 2017
New Revision: 1780286
URL: http://svn.apache.org/viewvc?rev=1780286&view=rev
Log:
[engine] upgrade README.txt file
Modified:
velocity/engine/trunk/README.txt
Modified: velocity/engine/trunk/README.txt
URL:
http://svn.apache.org/viewvc/velocity/engine/trunk/README.txt?rev=1780286&r1=1780285&r2=1780286&view=diff
==============================================================================
--- velocity/engine/trunk/README.txt (original)
+++ velocity/engine/trunk/README.txt Wed Jan 25 22:37:29 2017
@@ -2,64 +2,126 @@
Apache Velocity
---------------
-Welcome to Apache Velocity! Apache Velocity is a general purpose
+Welcome to Apache Velocity 2.0! Apache Velocity is a general purpose
template engine written in Java. For more information about Velocity,
-please look at the HTML documentation in the docs/ directory, as well
-as the Velocity web site.
+please look at the HTML documentation on the Velocity web site:
http://velocity.apache.org/index.html
-The following top level directories are in the Velocity distribution
-archive. Please consult the documentation in each of the lower level
-directories for information that is specific to their contents.
-
-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.
-
-Caveat! This is the directory structure of the distribution
-archive. If you checked out the source from the Apache Subversion
-Repository, the directory layout is slightly different.
+Here's a description of the top level directories:
+velocity-engine-core/ The Velocity Engine core module
+velocity-engine-examples/ Several simple examples
+velocity-engine-scripting/ JSR-223 implementation for Velocity scripting
+src/ Source for parent modules, mainly changelog
REQUIREMENTS
------------
-Apache Velocity will run with any version of Java greater than 1.3.
+Apache Velocity will run with any version of Java greater than 1.5.
-Building from source requires Java version 1.4 (or greater) and ant
-1.6 or greater.
+Building from source requires Java version 1.5 (or greater) and Maven 2.
+
+At compile time, Maven should fetch all needed dependencies, which are:
+ - commons-lang v3.5
+ - slf4j-api v1.7.21
+plus the following ones, needed for the integrated tests:
+ - slf4j-simple v1.7.21
+ - junit v4.12
+ - hsqldb v2.3.4
+ - commons-io 2.5
+
+At runtime, Velocity only needs:
+ - commons-lang v3.5+
+ - slf4j-api and an slf4j binding, v1.7.x
UPGRADING FROM EARLIER RELEASES
-------------------------------
-Release with the same major number (1.x) are intended to be drop-in
+Release with the same major number are intended to be drop-in
replacements. However, in most cases the versions of dependency jars
must be adjusted because newer versions of Velocity might require
updates.
-Upgrading from Velocity 1.4 or earlier
- * JDOM has been upgraded to version 1.0.
- * Commons Collections has been upgraded to version 3.1.
- * Commons Lang 2.1 has been added.
+Upgrading from Velocity 1.7.x to Velocity 2.0
- Optional:
+ Behavior / API changes:
- * Apache Ant 1.6 or better is required for rebuilding.
- * Java CC 3.2 is recommended to compile the parser files.
- * HSQLDB 1.7.1 is required for running unit tests.
+ * velocity is now using the SLF4J logging facade. Hence, all methods
accepting
+ or returning a logger now use the org.slf4j.Logger object. Velocity uses a
+ logger name of org.apache.velocity (configurable with the runtime.log.name
+ configuration entry), and several other childen loggers.
+ * the internal Context API now enforces String keys everywhere, this may
break
+ custom Context implementations at compile-time.
+ * invalid reference events are now more sparsely sent; they're not sent if
any
+ of the following conditions is met (the 1.x behavior did send invalid
+ reference events in all those cases):
+ x the reference is a quiet reference
+ x the reference could be successfully evaluated but resulted in a null
value
+ x the reference is tested for validity inside an #if / #elseif statement
+ * all events do now receive the current Velocity Context as a first argument.
+ The signatures of the MethodExceptionEventHandler,
+ ReferenceInsertionEventHandler and IncludeEventHandler events have changed,
+ and the ContextAware interface has been suppressed, as long as the
+ NullSetEventHandler event which is obsolete.
+ * The ResourceLoader class API has replaced InputStream getters by Reader
+ getters: InputStream ResourceLoader.getResourceStream(String name) has been
+ replaced by a Reader ResourceLoader.getResourceReader(String name, String
+ encoding).
+ * the default encoding ('ISO-8859-1' in 1.x) is now UTF-8.
+ * the MethodException event handler now receives an additional argument
+ providing template name and location infos.
+ * Initialization methods in Velocity and VelocityEngine taking an
+ ExtendedProperties have been removed (but setProperties(Properties) methods
+ are still here). All occurences of the
+ org.apache.commons.collections.ExtendedProperties class in the runtime
+ internal initialization API have been replaced by
+ org.apache.velocity.util.ExtProperties.
+ * the macros are now using a 'call by sharing' convention (which means that
+ all arguments are evaluated once at start, and that the macro receives a
+ copy of the reference to each argument).
+ * the UberspectLoggable interface has been removed.
+
+ VTL Changes:
+
+ * the hypen ( - ) cannot be used in variable names anymore
+ * method arguments can be arithmetic expressions
+ * method arguments are now converted as needed between all main basic Java
+ standard types (booleans, numbers and strings). If you want to revert to
+ the 1.x behavior, set the property runtime.conversion.handler = none.
+ * space gobbling (to control the indentation of generated code) is now
+ configurable via the space.gobbing configuration key, which can take the
+ following values: none, bc (aka. backward compatible), lines and
structured.
+ See the related documentation section for details. To maximize backward
+ compatibility with 1.x, set it to bc.
+
+ Dependencies changes:
+
+ * Velocity now requires a JDK version of 1.7 or higher.
+ * commons-collections and commons-logging aren't needed any more at runtime.
+ * there's a new runtime dependency, slf4j-api 1.7.12.
+ * you'll need an SLF4J binding.
+ * commons-lang has to be upgraded to 3.5.
+
+Upgrading from Velocity 1.6.x to Velocity 1.7.x
+
+ There are no changes in the dependencies since Velocity 1.6
+
+ * Deprecated $velocityCount; please use $foreach.count or $foreach.index
+ * Deprecated $velocityHasNext; please use $foreach.hasNext, $foreach.first
or $foreach.last
+ * Deprecated velocimacro.context.localscope setting; please get/set local
#macro references
+ as members of the provided $macro scope control instead. (e.g. #set(
$macro.foo = 'bar' )
+ and $macro.foo )
+ * Deprecated directive.evaluate.context.class setting; please get/set local
#evaluate
+ references as members of the provided $evaluate scope control instead.
(e.g.
+ #set( $evaluate.foo = 'bar' ) and $evaluate.foo )
+ * Deprecated #literal directive; please use #[[this syntax]]# instead.
+ * Changed #stop to end template rendering rather than template parsing.
+ * Removed obsolete Veltag (use VelocityViewTag in VelocityTools project)
+ * Removed obsolete WebMacro conversion code.
-Upgrading from Velocity 1.5
+Upgrading from Velocity 1.5.x to Velocity 1.6.x
* Commons Collections has been upgraded to version 3.2.1.
* Commons Lang has been upgraded to version 2.4.
@@ -70,6 +132,18 @@ Upgrading from Velocity 1.5
* Maven Ant 2.0.9 is required for the Maven Ant tasks.
* Java CC 4.1 is recommended to compile the parser files.
+Upgrading from Velocity 1.4.x or earlier to Velocity 1.5.x
+
+ * JDOM has been upgraded to version 1.0.
+ * Commons Collections has been upgraded to version 3.1.
+ * Commons Lang 2.1 has been added.
+
+ Optional:
+
+ * Apache Ant 1.6 or better is required for rebuilding.
+ * Java CC 3.2 is recommended to compile the parser files.
+ * HSQLDB 1.7.1 is required for running unit tests.
+
BUILDING APACHE VELOCITY
------------------------
@@ -79,58 +153,35 @@ build it.
Building is easy. All components necessary to build are included or
get downloaded from the internet during the build, except for the Java
-2 SDK and the Ant build tool. You can find details on how to build
+ SDK and the Maven build tool. You can find details on how to build
Velocity online at:
http://velocity.apache.org/engine/devel/build.html
-Note that you must use Ant version 1.6 or later.
-
*IMPORTANT* As the Apache Velocity build process wants to download a
number of jars from the internet, you must be online when you are
building for the first time.
-To build Velocity's jar, change directory into the build/ directory
-and enter:
+To build Velocity's jar, just run maven using the command:
-ant jar
+mvn
-This will create a bin/ directory containing the Velocity .jar
-file. Be sure to update your classpath to include Velocity's .jar
+This will create a target/ directory containing the Velocity .jar
+file in each sub-module directory.
+
+Be sure to update your classpath to include Velocity's .jar
file, or when using a modern servlet container, put it in the
WEB-INF/lib directory.
-If you wish to build a jar that contains all dependencies, we have
-provided an optional build target for your convenience:
-
-ant jar-dep
-
-This will build a complete Velocity jar with dependencies included,
-and it can be found in the /bin directory as
-
-velocity-dep-<version>.jar
-
-
-KNOWN ISSUES AND LIMITATIONS
-----------------------------
-
-When running findbugs on a project, the default heap size might not
-be enough to complete the build. For now there is no way to fork
-findbugs and run with its own memory requirements, but the following
-system variable will allow you to do so when running it via Maven:
-
-export MAVEN_OPTS=-Xmx384M
-
-
TRYING THE EXAMPLES
-------------------
After building Velocity, you can also buld the examples that are
-included with the Velocity distribution. These examples show how to
-use Velocity in your Java applications. There also are examples of
-how to use Anakia, a XML transformation engine.
+included with the Velocity distribution. These examples show how to
+use Velocity in your Java applications.
+
-For more information, please see the README.txt in the examples/
-directory.
+For more information, please see the README.txt in the
+velocity-engine-exemples/src/etc/ directory.
- The Apache Velocity Team
