<?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>
&lt;tools&gt;
  &lt;toolbox scope="application"&gt;
    &lt;tool key="date" format="MM/dd/yy"/&gt;
  &lt;/toolbox&gt;
  &lt;toolbox scope="request"&gt;
    &lt;tool key="text" bundles="resources,otherResources"/&gt;
  &lt;/toolbox&gt;
&lt;/tools&gt;
</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>
