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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> > 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 <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] > >> >> Software Engineer phone: 414-908-1809 > >> >> Weyco Group, Inc. fax: 414-908-1601 > >> >> > >> >> > >> >> --------------------------------------------------------------------- > >> >> To unsubscribe, e-mail: [EMAIL PROTECTED] > >> >> For additional commands, e-mail: [EMAIL PROTECTED] > >> >> > >> >> > >> >> > >> > > >> > --------------------------------------------------------------------- > >> > To unsubscribe, e-mail: [EMAIL PROTECTED] > >> > For additional commands, e-mail: [EMAIL PROTECTED] > >> > > >> > > >> > > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: [EMAIL PROTECTED] > >> For additional commands, e-mail: [EMAIL PROTECTED] > >> > >> > >> > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [EMAIL PROTECTED] > > For additional commands, e-mail: [EMAIL PROTECTED] > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
