| <?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> |
| <section name="Upgrading to 1.3"> |
| <todo/> |
| </section> |
| </body> |
| |
| </document> |
