[Springframework-developer] Resource param descriptions

[Colin S. <col...@ex...>]

I think we need to be a bit clearer when documenting API params which 
take Resource types. My feeling is that many if not most Spring users 
don't really realize that the ResourceEditor PropertyEditor mechanism 
which takes their String path and produces a resource for the param is 
actually going to give them different results for paths used inside a 
web AppContext variant as opposed to the other AppContext types. 
Actually my gut feel is that for some Spring users at least, the whole 
way Resources are resolved is a bit of magic, and they don't even fully 
understand the Resource types, or know the default ResourceEditor 
PropertyEditor exists...

In the case of SqlMapClientFactoryBean for example, the configLocation 
param, which is a Resource, is just described as
   'Set the location of the iBATIS SqlMapClient config file as class 
path resource. A typical value is "WEB-INF/sql-map-config.xml"'.

This is actually pretty wrong. It's setting it as a Resource, which is 
not necessarilly a classpath resource. The typical value described will 
in fact only work inside a web ApplicationContext variant (it should 
also really have a leading slash for the example, although Spring will 
add that if necessary).

Here's a link to a forum thread where a user ran into some confusion 
related to this:
  http://forum.springframework.org/viewtopic.php?p=1761

I'm going to try to track down params like this and document them a bit 
better...

Regards,
Colin