Re: upgrading

> sadly, no.  no one has written such a document yet.  but here's a
> sketch outline:
>
> first, just drop in the Tools 2 jar as a straight up replacement.
> assuming your app already worked great with Tools 1.3+, it should just
> work.  if not, let us know.  we're trying to be fully backwards
> compatible (though we did drop some stuff that's was deprecated in
> 1.3).
>
> when you run that, look for any upgrade/deprecation notices in the
> logs.  that might help give details for the rest. (not sure on that
> though)
>
> next, try adjusting to the new package locations for things like the
> VelocityViewServlet and VelocityLayoutServlet.  Quick guide would be
> that things in org.apache.velocity.tools.view.servlet and
> org.apache.velocity.tools.view.context are now just in
> org.apache.velocity.tools.view.
>
> if you specifically reference the o.a.v.t.view.servlet.WebappLoader,
> it is now the o.a.v.t.view.WebappResourceLoader.
>
> now, since Tools 2 does lazy loading of tools, it now costs very
> little per-request to have a lot of tools available.  so, unless the
> user is doing something to trigger the "deprecation support mode" for
> VelocityView (using the old xml format would trigger this), all of the
> standard VelocityTools will be automatically made available by
> default.  so, 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.
>
> if you do need a configuration, try switching your configuration to
> the new format.  easiest would be to go from the old xml format to the
> new xml format:
> http://velocity.apache.org/tools/devel/config.xml.html
> remember, you can just leave out standard tools that you don't do any
> configuration of.
>
> if you do configure some of the standard tools, then while you are
> updating the configuration format, you might also check to see if that
> tool has been moved to a new package.  the easiest way is probably
> just to check in the javadoc.  tools which are deprecated should tell
> you what their replacement is.  a few tools also had name changes
> (e.g. ParameterParser to ParameterTool and BrowserSniffer to
> BrowserTool)
>
> that should cover most everything, except how 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:
>
> the recommended practice is to give a tool to be used as $foo the name
> FooTool.  not required, but it makes things easier for people to
> follow and learn.  if you are going name a tool FooBarUtility but want
> it to be $foo in the context, the second best thing is to provide a
> @DefaultKey("foo") annotation on the class.
>
> also, if your tool is only meant to be used in a particular scope,
> it's recommended that you give the class a @ValidScope(Scope.REQUEST)
> annotation as well.  if you only want to ban a particular scope and
> allow all others, you could provide a @InvalidScope(Scope.APPLICATION)
> annotation on the class.  the Scope class provides constants for
> REQUEST, SESSION, and APPLICATION.  i believe other scopes are now
> theoretically possible, but only a little work and less testing has
> been done there.
>
> if you have a configurable tool whose configuration should not changed
> by the templates which use it, then consider having your tool extend
> the AbstractLockConfig class (or one of its kin FormatConfig or
> LocaleConfig).  if you want to know more about these, let me know.
>
> in general, 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.
>
> and that all turned out longer than planned.  i guess i have the start
> of a migration document now, eh?  let me know how it works out for
> you.
>
> On Tue, Apr 1, 2008 at 12:32 PM, Charles Harvey III <charlieh@...> wrote:
>  
>> I would like to start migrating my tools to the 2.0 path.  Is there a
>>  good document
>>  on the site that tells me how to do do?  I have been looking and I'm not
>>  sure if I
>>  am looking in the right places.
>>
>>  Thanks.
>>
>>
>>  Charlie
>>
>>
>>  Nathan Bubna said the following on 4/1/2008 3:16 PM:
>>
>>
>>    
>>> yep, that's the idea.  as for the init() method, you only need it if
>>>      
>>  > your tool needs access to the  initData for that scope (ServletContext
>>  > for application scope and ViewContext for request or session scope).
>>  > if your tool doesn't need access to any of those things, then it
>>  > doesn't need an init(Object) method.
>>  >
>>  > of course, this is all with Tools 1.3 or Tools 1.4.  with Tools 2,
>>  > things get even easier. :)
>>  >
>>  > On Tue, Apr 1, 2008 at 12:05 PM, Charles Harvey III <charlieh@...> wrote:
>>  >
>>  >> As far as your own tools goes, I want to make sure I've got it right:
>>  >>
>>  >>  Old:
>>  >>  -------------------------------------------------------------
>>  >>  public class MyTool implements ViewTool
>>  >>  {
>>  >>     private String theString;
>>  >>
>>  >>     public void init( Object o )
>>  >>     {
>>  >>         if( !( obj instanceof ViewContext ) )
>>  >>         {
>>  >>             throw new IllegalArgumentException( "Tool can only be
>>  >>  initialized with a ViewContext" );
>>  >>         }
>>  >>     }
>>  >>
>>  >>     public String getTheString()
>>  >>     {
>>  >>         return "this string comes from a velocity tool";
>>  >>     }
>>  >>  }
>>  >>  -------------------------------------------------------------
>>  >>
>>  >>
>>  >>  New:
>>  >>  -------------------------------------------------------------
>>  >>  public class MyTool
>>  >>  {
>>  >>     private String theString;
>>  >>
>>  >>     public void init( Object o )
>>  >>     {
>>  >>         if( !( obj instanceof ViewContext ) )
>>  >>         {
>>  >>             throw new IllegalArgumentException( "Tool can only be
>>  >>  initialized with a ViewContext" );
>>  >>         }
>>  >>     }
>>  >>
>>  >>     public String getTheString()
>>  >>     {
>>  >>         return "this string comes from a velocity tool";
>>  >>     }
>>  >>  }
>>  >>  -------------------------------------------------------------
>>  >>
>>  >>
>>  >>  Do I still need the init method?  Or can I skip that too?
>>  >>
>>  >>  Thanks.
>>  >>
>>  >>
>>  >>  Charlie
>>  >>
>>  >>
>>  >>
>>  >>
>>  >>
>>  >>  Nathan Bubna said the following on 4/1/2008 1:06 PM:
>>  >>
>>  >>
>>  >>
>>  >>> there are some issues with multi-line comments within macros in Velocity 1.5
>>  >>>
>>  >>  >
>>  >>  > if you have written your own custom tools, then you'll find the
>>  >>  > ViewTool and Configurable interfaces have been axed in VelocityTools
>>  >>  > 1.4.  just remove the implements declarations for those interfaces.
>>  >>  > they are unnecessary, as Tools 1.4 will automatically look for their
>>  >>  > methods in any tool class.  if you haven't written any tools of your
>>  >>  > own, i don't think there's anything to be concerned about.
>>  >>  >
>>  >>  > that's all i can think of right now, but of course, feel free to ask
>>  >>  > questions/report problems here.
>>  >>  >
>>  >>  > On Tue, Apr 1, 2008 at 8:49 AM, Glenn Holmer <gholmer@...> wrote:
>>  >>  >
>>  >>  >> I'm doing maintenance on an app that uses Velocity 1.4 and VelocityTools
>>  >>  >>  1.1, and would like to upgrade to Velocity 1.5 and tools 1.4.  Are there
>>  >>  >>  any gotchas I should watch out for?
>>  >>  >>
>>  >>  >>  --
>>  >>  >>  ____________________________________________________________
>>  >>  >>  Glenn Holmer                          gholmer@...
>>  >>  >>  Software Engineer                        phone: 414-908-1809
>>  >>  >>  Weyco Group, Inc.                          fax: 414-908-1601
>>  >>  >>
>>  >>  >>
>>  >>  >>  ---------------------------------------------------------------------
>>  >>  >>  To unsubscribe, e-mail: user-unsubscribe@...
>>  >>  >>  For additional commands, e-mail: user-help@...
>>  >>  >>
>>  >>  >>
>>  >>  >>
>>  >>  >
>>  >>  > ---------------------------------------------------------------------
>>  >>  > To unsubscribe, e-mail: user-unsubscribe@...
>>  >>  > For additional commands, e-mail: user-help@...
>>  >>  >
>>  >>  >
>>  >>  >
>>  >>
>>  >>  ---------------------------------------------------------------------
>>  >>  To unsubscribe, e-mail: user-unsubscribe@...
>>  >>  For additional commands, e-mail: user-help@...
>>  >>
>>  >>
>>  >>
>>  >
>>  > ---------------------------------------------------------------------
>>  > To unsubscribe, e-mail: user-unsubscribe@...
>>  > For additional commands, e-mail: user-help@...
>>  >
>>  >
>>  >
>>
>>  ---------------------------------------------------------------------
>>  To unsubscribe, e-mail: user-unsubscribe@...
>>  For additional commands, e-mail: user-help@...
>>
>>
>>    
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: user-unsubscribe@...
> For additional commands, e-mail: user-help@...
>
>
>