1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
|
<?xml version="1.0"?>
<!--
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.
-->
<document>
<properties>
<title>Upgrading VelocityTools</title>
<projectfile>xdocs/project.xml</projectfile>
</properties>
<body>
<section name="Upgrading VelocityTools">
<p>
<ul>
<li>
<a href="#Upgrading_to_2.0">Upgrading to 2.0</a>
<ul>
<li><a href="#Renamings_in_2.0">Renamings</a></li>
<li><a href="#Deprecations_in_2.0">Deprecations</a></li>
<li><a href="#Configuration_in_2.0">Configuration</a></li>
<li><a href="frameworks.html">Integration</a></li>
<li><a href="#Custom_Tools_in_2.0">Custom Tools</a></li>
</ul>
</li>
<li><a href="#Upgrading_to_1.4">Upgrading to 1.4</a></li>
<li><a href="#Upgrading_to_1.3">Upgrading to 1.3</a></li>
</ul>
</p>
</section>
<section name="Upgrading to 2.0">
<p>
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.
</p>
<p>
Still, as such things have only been deprecated and not
removed, <b>the first step in upgrading to 2.0 is simply
replacing your old VelocityTools jar with the 2.0 jar</b>.
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.
</p>
<p>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:
</p>
<subsection name="Renamings in 2.0">
<p>
In general, anything in the packages:
</p>
<ul>
<li><code>org.apache.velocity.tools.view.tools</code>,</li>
<li><code>org.apache.velocity.tools.view.servlet</code> or</li>
<li><code>org.apache.velocity.tools.view.context</code>,</li>
</ul>
<p>
has been moved to:<blockquote>
<code>org.apache.velocity.tools.view</code></blockquote> The
extra packages had proved superfluous and problematic.
All VelocityView classes are now in the
<code>org.apache.velocity.view</code> 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.
</p><p>
Some specific ones to watch out for are as follows.
If you directly referenced:
</p>
<ul>
<li>VelocityViewServlet, it is now at
<javadoc package="view" name="VelocityViewServlet" full="true"/></li>
<li>VelocityLayoutServlet, it is now at
<javadoc package="view" name="VelocityLayoutServlet" full="true"/></li>
<li>WebappLoader, it is now at
<javadoc package="view" name="WebappResourceLoader" full="true"/></li>
<li>ViewContext, it is now at
<javadoc package="view" name="ViewContext" full="true"/></li>
<li>ServletLogger, it has been replaced by
<javadoc package="view" name="ServletLogChute" full="true"/></li>
<li>ServletUtils, it is now at
<javadoc package="view" name="ServletUtils" full="true"/></li>
<li>BrowserSniffer, it is now at
<javadoc package="view" name="BrowserTool" full="true"/></li>
<li>AbstractPagerTool, it is now at
<javadoc package="view" name="PagerTool" full="true"/></li>
<li>ParameterParser, it is now at
<javadoc package="view" name="ParameterTool" full="true"/></li>
<li>ContextTool, it is now at
<javadoc package="view" name="ViewContextTool" full="true"/></li>
</ul>
<p>
<b>NOTE:</b> If you are still using the old toolbox.xml format
do NOT update the tool paths in that file! First,
<a href="#Configuration">update your configuration</a>, 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.
</p>
</subsection>
<subsection name="Deprecations in 2.0">
<p>
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:
</p>
<p>
<b>XMLToolboxManager</b> was the the central tool management class
in Tools 1.x. If you used it or <b>ServletToolboxManager</b> you
were probably a more advanced user or a framework developer
working to integrate VelocityTools support. If so, you should go
read <a href="frameworks.html">this document</a>. If you used
XMLToolboxManager directly, you should familiarize
yourself with these classes:
<ul>
<li><javadoc name="ToolManager"/></li>
<li><javadoc package="config" name="ConfigurationUtils"/></li>
<li><javadoc package="config" name="FactoryConfiguration"/></li>
<li><javadoc name="ToolboxFactory"/></li>
<li><javadoc name="ToolContext"/></li>
</ul>
If you used ServletToolboxManager directly, you should learn
about all of the above classes (except perhaps ToolManager) and
the following ones as well:
<ul>
<li><javadoc package="view" name="VelocityView"/></li>
<li><javadoc package="view" name="ViewToolContext"/></li>
<li><javadoc package="view" name="ServletUtils"/></li>
</ul>
<b>NOTE:</b> For the vast majority of users and developers,
<javadoc name="ToolManager"/> or
<javadoc package="view" name="VelocityView"/>
should be all they really need
to work with directly. Don't waste time trying to manage
<code>Toolbox</code>es yourself until you are sure that
ToolManager/VelocityView can't do the job for you.
</p>
<p>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:
<ul>
<li>ViewRenderTool, you should now just use
<code><javadoc full="true" package="generic" name="RenderTool"/></code></li>
<li>ViewResourceTool, you should now just use
<code><javadoc full="true" package="generic" name="ResourceTool"/></code></li>
</ul>
</p>
</subsection>
<subsection name="Configuration in 2.0">
<p>
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
<javadoc package="view" name="VelocityView"/>
not to load the default tools, then all of the supported,
standard VelocityTools will be automatically made available by
default. If you don't custom configure any of the provided tools
and don't have any custom tools of your own, then you don't actually
need a configuration at all! Tools 2 comes with a default tools.xml
file each for GenericTools, VelocityView and VelocityStruts, and
the
<javadoc name="ToolManager"/>,
<javadoc package="view" name="VelocityViewServlet"/>,
<javadoc package="view" name="VelocityLayoutServlet"/> and
<javadoc package="view.jsp" name="VelocityViewTag"/>
will all automatically look for
and load those unless you are using a deprecated toolbox.xml file
or explicitly tell them not to by adding the init-param
<code>org.apache.velocity.tools.loadDefaults</code> with the value of false
to the relevant servlet.
</p>
<p>
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 <a href="config.xml.html">the new xml format</a>.
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
<a href="#Renamings_in_2.0">changed packages and/or names</a>; please
avoid using the deprecated versions as those will eventually be
removed.
</p>
<p>
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
<javadoc package="generic" name="DateTool"/> and
a second bundle for the ResourceTool, your tools.xml can be just:
</p>
<sourcecode>
<tools>
<toolbox scope="application">
<tool key="date" format="MM/dd/yy"/>
</toolbox>
<toolbox scope="request">
<tool key="text" bundles="resources,otherResources"/>
</toolbox>
</tools>
</sourcecode>
<p>
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.
</p>
<p>
You don't even have to use XML to override/extend the defaults.
Other available formats are <a href="config.properties.html">a
properties file</a> or <a href="config.java.html">plain java</a>.
</p>
</subsection>
<subsection name="Integration with 2.0">
<p>
Please see the <a href="frameworks.html">framework integration</a>
page for information on this subject.
</p>
</subsection>
<subsection name="Custom Tools in 2.0">
<p>
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 <a href="creatingtools.html">instructions for creating tools</a>.
</p>
<p><b>Naming:</b>
The recommended practice is to give a tool to be used as
<code>$foo</code> the name <code>FooTool</code>.
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 <code>$foo</code> in templates, the second best thing is to
provide a
<javadoc package="config" name="DefaultKey">@DefaultKey("foo")</javadoc>
annotation on the class, though this introduces a dependency on
VelocityTools. As a last resort, if you are providing tools
for a framework or otherwise can influence or control the configuration,
you might consider providing a default configuration--perhaps even
one automatically discoverable by
<javadoc package="config" name="ConfigurationUtils"/>--to
set the tool's key for your users.
</p>
<p><b>Scoping:</b>
If your tool is only meant to be used in a particular scope,
it's recommended that you give the class a
<javadoc package="config" name="ValidScope">@ValidScope(Scope.REQUEST)</javadoc>
annotation as well. If you only want to ban a particular scope and
allow all others, you could provide a
<javadoc package="config" name="InvalidScope">@InvalidScope(Scope.APPLICATION)</javadoc>
annotation on the class. The
<code><javadoc name="Scope"/></code> 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.
</p>
<p><b>Configuration:</b>
If you have a configurable tool whose configuration should not changed
by the templates which use it, then consider having your tool extend
the <javadoc package="generic" name="SafeConfig"/> class (or
<javadoc package="generic" name="FormatConfig"/> or
<javadoc package="generic" name="LocaleConfig"/>). These safely
standardize configuration of these common configuration properties.
Also take note that the configure(Map) and init(Object) methods have been
changed into just the configure(Map) and individual setter methods
(e.g. setRequest, setSession, etc). Basically, when it's time to
instantiate a tool, the tool manager will gather all the "configuration
properties" for that tool, its toolbox, etc and combine it into a
single map with the "init data" (context, request, session, etc). The
manager searches for relevant setter methods that accept that data and
also for a configure(Map) method. The setters get what they're asking
for (if available) and the configure() method accepts the whole combined
Map. The upshot of this approach is that tools no longer need to
conform to any interfaces or patterns. In fact, it's possible to
write a FooTool that doesn't know anything about any VelocityTools
classes whatsoever and yet be fully instantiable and configurable by
VelocityTools. Your tools don't need to know about anything except
what they need to know about.
</p>
</subsection>
</section>
<section name="Upgrading to 1.4">
<todo/>
</section>
</body>
</document>
|
