upgrading

[Glenn Holmer]

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: [phone]
Weyco Group, Inc.                          fax: [phone]


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Nathan Bubna]

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: [phone]
>  Weyco Group, Inc.                          fax: [phone]
>
>
>  ---------------------------------------------------------------------
>  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@...

[Glenn Holmer]

Nathan Bubna wrote:
> there are some issues with multi-line comments within macros in
> Velocity 1.5

You mean like this?

#**
  * Show messages with the given property using CSS class "info".
  * @param  property The property of messages to show.
  *#

> that's all i can think of right now, but of course, feel free to ask
> questions/report problems here.

Thanks, I'll post if we get stuck.

--
____________________________________________________________
Glenn Holmer                          gholmer@...
Software Engineer                        phone: [phone]
Weyco Group, Inc.                          fax: [phone]


---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[Nathan Bubna]

no, i mean like:

#macro( foo )#*
  *#this macro has issue :(#*
*##end

see https://issues.apache.org/jira/browse/VELOCITY-537 for more info

On Tue, Apr 1, 2008 at 10:46 AM, Glenn Holmer <gholmer@...> wrote:

> Nathan Bubna wrote:
>  > there are some issues with multi-line comments within macros in
>  > Velocity 1.5
>
>  You mean like this?
>
>  #**
>   * Show messages with the given property using CSS class "info".
>   * @param  property The property of messages to show.
>   *#
>
>
>  > that's all i can think of right now, but of course, feel free to ask
>  > questions/report problems here.
>
>  Thanks, I'll post if we get stuck.
>
>  --
>
>
> ____________________________________________________________
>  Glenn Holmer                          gholmer@...
>  Software Engineer                        phone: [phone]
>  Weyco Group, Inc.                          fax: [phone]
>
>
>  ---------------------------------------------------------------------
>  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@...

[Charles Harvey III]

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: [phone]
>>  Weyco Group, Inc.                          fax: [phone]
>>
>>
>>  ---------------------------------------------------------------------
>>  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@...

[Nathan Bubna]

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: [phone]
>  >>  Weyco Group, Inc.                          fax: [phone]
>  >>
>  >>
>  >>  ---------------------------------------------------------------------
>  >>  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@...

[Charles Harvey III]

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: [phone]
>>  >>  Weyco Group, Inc.                          fax: [phone]
>>  >>
>>  >>
>>  >>  ---------------------------------------------------------------------
>>  >>  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@...

[Nathan Bubna]

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: [phone]
>  >>  >>  Weyco Group, Inc.                          fax: [phone]
>  >>  >>
>  >>  >>
>  >>  >>  ---------------------------------------------------------------------
>  >>  >>  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@...

[Charles Harvey III]

Nathan,
Thanks for all that info.  It will definitely be a big help.  The
biggest issue
I have is that I am still stuck on tools-1.2.  So I still have to go through
the pain of removing the "implements ViewTool" from all of my tools before I
drop in anything new.  I think after that it should be fairly
straightforward.

The only thing I didn't get was how the standard VelocityTools are available
without any configuration.  That just happens when I setup
VelocityLayoutServlet
in web.xml and pass it the org.apache.velocity.toolbox param?

Thanks again.


Charlie


Nathan Bubna said the following on 4/1/2008 5:03 PM:

> 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: [phone]
>>  >>  >>  Weyco Group, Inc.                          fax: [phone]
>>  >>  >>
>>  >>  >>
>>  >>  >>  ---------------------------------------------------------------------
>>  >>  >>  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@...
>
>
>  

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@...
For additional commands, e-mail: user-help@...

[CloD]

Le mardi 01 avril 2008 à 17:26 -0400, Charles Harvey III a écrit :

> Nathan,
> Thanks for all that info.  It will definitely be a big help.  The
> biggest issue
> I have is that I am still stuck on tools-1.2.  So I still have to go through
> the pain of removing the "implements ViewTool" from all of my tools before I
> drop in anything new.  I think after that it should be fairly
> straightforward.
>
> The only thing I didn't get was how the standard VelocityTools are available
> without any configuration.  That just happens when I setup
> VelocityLayoutServlet
> in web.xml and pass it the org.apache.velocity.toolbox param?

It should not even be necessary to give it this parameter if you name it
"/WEB-INF/toolbox.xml" (old name) or "/WEB-INF/tools.xml" (new name).
Please note that the format of the new file has slightly changed. See
http://velocity.apache.org/tools/devel/config.xml.html .


  Claude

> Thanks again.
>
>
> Charlie
>
>
> Nathan Bubna said the following on 4/1/2008 5:03 PM:
> > 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 )
> >>  >>