VelocityTools 2.0 marks the most significant set of upgrades and changes ever done for the VelocityTools library. In order to provide flexible configurations, lazy-loading for tools, and a host of other improvements, almost all of the tool management and configuration code from Tools 1.x has been deprecated and replaced by completely different APIs. Thankfully, we were able to continue supporting old toolbox.xml configuration files and old tool design patterns, though these too have been deprecated and are unable to take full advantage of many of the new features.
Still, as such things have only been deprecated and not removed, the first step in upgrading to 2.0 is simply replacing your old VelocityTools jar with the 2.0 jar. If this causes any errors for you, please report them to user@velocity.apache.org, so that we can fix it and help you work around it in the meantime.
Once you have your application compiling and running with Tools 2, your next step is to begin updating or replacing deprecations. Many of these should show up with deprecation warnings during compiling or deprecation notices in your logs. Read through these carefully to be aware of all that needs updating. Below is a list of instructions for handling many of these:
In general, anything in the packages:
org.apache.velocity.tools.view.tools
,org.apache.velocity.tools.view.servlet
ororg.apache.velocity.tools.view.context
,has been moved to:
org.apache.velocity.tools.view
The
extra packages had proved superfluous and problematic.
All VelocityView classes are now in the
org.apache.velocity.view
package. Those
that remain in the subpackages are merely deprecated
shells that extend the classes in the new location.
Also, some classes have had their class names adjusted
to be more consistent with existing conventions.
Some specific ones to watch out for are as follows. If you directly referenced:
NOTE: If you are still using the old toolbox.xml format do NOT update the tool paths in that file! First, update your configuration, otherwise your tools may not work as expected. Also, this is not a complete list. Please take note of all deprecation warnings and notices when compiling and running your app.
Along with the class renamings above have come many deprecations that have no one-to-one replacement class. The vast majority of these have to do with tool management, as XMLToolboxManager and all of its subclasses and support classes could not simply be evolved to achieve the key goals for Tools 2. A few other classes are simply no longer necessary in any form. Here is an overview of all these deprecations-without-direct-replacements:
XMLToolboxManager was the the central tool management class in Tools 1.x. If you used it or ServletToolboxManager you were probably a more advanced user or a framework developer working to integrate VelocityTools support. If so, you should go read this document. If you used XMLToolboxManager directly, you should familiarize yourself with these classes:
Toolbox
es yourself until you are sure that
ToolManager/VelocityView can't do the job for you.
All of the upgrades to tool management allowed some GenericTool classes to perform functions previously only possible to implement in VelocityView tools. As such, some VelocityView subclasses of generic tools have become obsolete. If you used:
Since Tools 2 does lazy-loading of tools, it now makes sense
to have almost all tools available by default for most uses,
as there is minimal overhead for that at startup and essentially
no cost at runtime unless/until the tool is used. So,
in Tools 2, unless the
user is doing something to trigger the "deprecation support mode" for
VelocityView (using the old toolbox.xml format would do this)
or explicitly telling
org.apache.velocity.tools.loadDefaults
with the value of false
to the relevant servlet.
If you do need a configuration, you should update your configuration to one of the new formats. Easiest would be to go from the old xml format to the new xml format. Remember, you can just leave out standard tools that you don't do any configuration of, as your configuration will just be added to the default one (again, unless the default behavior is turned off). Also, do note that all VelocityView tools have changed packages and/or names; please avoid using the deprecated versions as those will eventually be removed.
If you are largely happy with the default tools.xml configuration,
but wish to override just a few parts, you can override them with
your own file. Tool configurations are key-centric. If you just
want to provide a different default format for the
This just overrides the format property of the "date" tool and the bundles property of the "text" tool in the configuration. Since "date" and "text" already have classes set in the default tools.xml files that come with the GenericTools and VelocityView packages, you don't need to include those.
You don't even have to use XML to override/extend the defaults. Other available formats are a properties file or plain java.
Please see the framework integration page for information on this subject.
Those of you who write your own custom tools may want to make a few changes to upgrade your custom tools to do things the "Tools 2 way". Here's a few quick starts for that, though this doesn't cover everything. More details can be found in the instructions for creating tools.
Naming:
The recommended practice is to give a tool to be used as
$foo
the name FooTool
.
This is not required but is a convention that keeps things easy
follow and learn. If you have to name a tool FooBarUtility but want
it to be $foo
in templates, the second best thing is to
provide a
Scoping:
If your tool is only meant to be used in a particular scope,
it's recommended that you give the class a
class provides constants for
REQUEST, SESSION, and APPLICATION. Other scopes are now
theoretically possible, but only a little work and no testing has
been done there at this point.
Configuration:
If you have a configurable tool whose configuration should not changed
by the templates which use it, then consider having your tool extend
the