You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by nb...@apache.org on 2008/06/24 03:33:10 UTC
svn commit: r670990 - in /velocity/tools/trunk/xdocs: project.xml
upgrading.xml
Author: nbubna
Date: Mon Jun 23 18:33:10 2008
New Revision: 670990
URL: http://svn.apache.org/viewvc?rev=670990&view=rev
Log:
add 'upgrade to 2.0' documentation
Added:
velocity/tools/trunk/xdocs/upgrading.xml (with props)
Modified:
velocity/tools/trunk/xdocs/project.xml
Modified: velocity/tools/trunk/xdocs/project.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/project.xml?rev=670990&r1=670989&r2=670990&view=diff
==============================================================================
--- velocity/tools/trunk/xdocs/project.xml (original)
+++ velocity/tools/trunk/xdocs/project.xml Mon Jun 23 18:33:10 2008
@@ -58,6 +58,7 @@
<item name="Standalone Use" href="standalone.html"/>
<item name="Web Framework Integration" href="frameworks.html"/>
<item name="Creating Tools" href="creatingtools.html"/>
+ <item name="Upgrading to 2.0" href="upgrading.html"/>
<!--
TODO: link to glossary on main velocity site, once it is up there
-->
Added: velocity/tools/trunk/xdocs/upgrading.xml
URL: http://svn.apache.org/viewvc/velocity/tools/trunk/xdocs/upgrading.xml?rev=670990&view=auto
==============================================================================
--- velocity/tools/trunk/xdocs/upgrading.xml (added)
+++ velocity/tools/trunk/xdocs/upgrading.xml Mon Jun 23 18:33:10 2008
@@ -0,0 +1,233 @@
+<?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="Content">
+ <p>
+ This document provides helpful instructions in upgrading from
+ previous versions of VelocityTools.
+ <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
+ <code>org.apache.velocity.tools.view.tools</code>,
+ <code>org.apache.velocity.tools.view.servlet</code> or
+ <code>org.apache.velocity.tools.view.context</code>,
+ has been moved to
+ <code>org.apache.velocity.tools.view</code>. 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:
+ <ul>
+ <li>VelocityViewServlet, it is now at
+ <code>org.apache.velocity.tools.view.VelocityViewServlet</code></li>
+ <li>VelocityLayoutServlet, it is now at
+ <code>org.apache.velocity.tools.view.VelocityLayoutServlet</code></li>
+ <li>WebappLoader, it is now at
+ <code>org.apache.velocity.tools.view.WebappResourceLoader</code></li>
+ <li>ViewContext, it is now at
+ <code>org.apache.velocity.tools.view.ViewContext</code></li>
+ <li>ServletLogger, it has been replaced by
+ <code>org.apache.velocity.tools.view.ServletLogChute</code></li>
+ <li>ServletUtils, it is now at
+ <code>org.apache.velocity.tools.view.ServletUtils</code></li>
+ <li>BrowserSniffer, it is now at
+ <code>org.apache.velocity.tools.view.BrowserTool</code></li>
+ <li>AbstractPagerTool, it is now at
+ <code>org.apache.velocity.tools.view.PagerTool</code></li>
+ <li>ParameterParser, it is now at
+ <code>org.apache.velocity.tools.view.ParameterTool</code></li>
+ <li>ContextTool, it is now at
+ <code>org.apache.velocity.tools.view.ViewContextTool</code></li>
+ </ul>
+ <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>org.apache.velocity.tools.ToolManager</li>
+ <li>org.apache.velocity.tools.config.ConfigurationUtils</li>
+ <li>org.apache.velocity.tools.config.FactoryConfiguration</li>
+ <li>org.apache.velocity.tools.ToolboxFactory</li>
+ <li>org.apache.velocity.tools.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>org.apache.velocity.tools.view.VelocityView</li>
+ <li>org.apache.velocity.tools.view.ViewToolContext</li>
+ <li>org.apache.velocity.tools.view.ServletUtils</li>
+ </ul>
+ <b>NOTE:</b> For the vast majority of users and developers,
+ ToolManager or 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>org.apache.velocity.tools.RenderTool</code></li>
+ <li>ViewResourceTool, you should now just use
+ <code>org.apache.velocity.tools.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 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!
+ </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>Other available formats are <a href="config.properties.html">a
+ properties file</a> or <a href="config.java.xml">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">
+ <todo>
+ Incorporate the instructions and code for custom tools laid out in
+ <a href="http://velocity.markmail.org/search/?q=subject%3A%22upgrading%22#query:subject%3Aupgrading%20order%3Adate-forward+page:3+mid:pw56jxgsudhwwnnd+state:results">this email thread</a>,
+ </todo>
+ <p>
+ </p>
+ </subsection>
+ </section>
+ <section name="Upgrading to 1.4">
+ <todo/>
+ </section>
+ <section name="Upgrading to 1.3">
+ <todo/>
+ </section>
+ </body>
+
+</document>
Propchange: velocity/tools/trunk/xdocs/upgrading.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: velocity/tools/trunk/xdocs/upgrading.xml
------------------------------------------------------------------------------
svn:executable = *
Propchange: velocity/tools/trunk/xdocs/upgrading.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml