maint-5-2/src/site/apt/upgrade.apt

 ----
 Upgrade Notes
 ----

Upgrade Notes

  This is a quick guide to changes <since> Tapestry 5.1.0.5.  This is meant to provide information
  on any additions or changes that developers will face after upgrading to Tapestry 5.2.
  
  It is always advised to perform a full and complete build after upgrading.

  You should also check the {{{release-notes.html}project-wide release notes}} for information
  about bugs fixes and other improvements.

Release 5.2.0

* Service Id Injection

  In prior releases of Tapestry, a constructor parameter of type String was assumed to be the service id.
  In the many cases where these was not the case (such as using the @Value or @Symbol annotation), the parameter
  needed to be annotated with the @Inject annotation.
  
  Starting in 5.2, this feature is no longer present (this is a <non-backwards compatible change>, but one that
  affects virtually nobody).  A parameter of type String will be subject to normal
  injection; you will likely want to use @Value or @Symbol with it, or you will see an error that "No service
  implements java.lang.String.".

* TranslatorSource

  The configuration type for TranslatorSource has changed in an <<incompatible>> way: from
  an unordered collection to a mapped collection; this is to support overrides. This will break
  existing module classes that contribute to the TranslatorSource service configuration.

* Assets

  There have been some changes to how assets operate in Tapestry 5.2.
  
  Virtual folders, used to define root packages for component libraries, may no longer
  contain slashes. Virtual folders are the pathPrefix property of the LibraryMapping objects
  that are contributed to the ComponentClassResolver service.
  
  Each LibraryMapping  is now automatically converted into a matching contribution to   
  the ClasspathAssetAliasManager service. Previously a library author was encouraged
  to make contributions to both services. The path prefix of a LibraryMapping is also
  now prohibited from containing the slash character.

  It is now quite necessary to configure the application version number: all assets are exposed via
  a URL that incorporates the application version number; in previous releases, each library could
  configure its own version number. By implication, changing library versions and nothing else will now
  require a change to the application version number.

* ClassTransformation API changes

  The
  {{{apidocs/org/apache/tapestry5/services/ClassTransformation.html}ClassTransformation}} 
  API, used to implement component meta-programming,
  has been rewritten with an eye to making class transformations easier to implement while
  removing the dependency on the Javassist library. This is of note only to <advanced> users who have implemented
  {{{apidocs/org/apache/tapestry5/services/ComponentClassTransformWorker.html}ComponentClassTransformWorker}}s, which operate on
  the ClassTransformation API. 
    
  Much of the existing API has been deprecated and <some> deprecated
  methods are now non-functional. The deprecated methods will be removed in Tapestry 5.3.
  
  This represents a shift in how the API operates; previously much of the logic in ComponentClassTransformWorkers
  was built in terms of Javassist: adding new bytecode to existing methods. The new API switches away from this, and
  now works in terms of adding new fields, initializing those fields using callbacks, providing callbacks for access
  to fields, and adding advice to methods.

* Template Parser back to SAX

  Tapestry no longer uses a StAX parser to parse component templates, it has reverted to using a normal SAX parser. This change
  reduces the number of dependencies for Tapestry, and is a stepping stone towards compatibility with
  Google App Engine.

Release 5.1.0.4

  Tapestry's alpha URL rewriting support (available from 5.1.0.1) has undergone some API changes:

    * The core url rewriting service to which rules are contributed has changed from URLRewriterService to 
      URLRewriter, with a corresponding change to the service id.  Modules contributing to this service will need to
      update the corresponding contribution method names.

    * The signature of the "process" method of the URLRewriterRule interface now requires an additional parameter
      of type org.apache.tapestry5.urlrewriter.URLRewriteContext.

    * URLRewriteRule implementations must now also implement the "applicability" method which determines whether
      rules should be applied to incoming requests, outgoing urls (links), or both.

    []

* {{{https://issues.apache.org/jira/browse/TAP5-622}TAP5-622}}

    The client-side ids for labels and error icons have slightly different names; the ':' seperator (i.e. "textfield:label")
    has been changed to a '-' (i.e., "textfield-label"). This should only affect users who have significantly
    overridden client-side validation.

    The same approach has been taken with the many client-side elements used by the Palette and DateField components.

Release 5.1.0.1

  Tapestry's client-side JavaScript relating to input field validation has changed somewhat
  to account for
  {{{https://issues.apache.org/jira/browse/TAP5-211}TAP5-211}}. This will only affect users
  who have created their own client-side validations.

  The handling of the
  {{{apidocs/org/apache/tapestry5/annotations/Secure.html}Secure}} annotation is now only enabled
  in production mode (by default).

Release 5.1.0.0

* Primary Key Encoder

  <<This is the change between releases that is most likely to affect your upgrade.>>

  The {{{apidocs/org/apache/tapestry5/PrimaryKeyEncoder.html}PrimaryKeyEncoder}}
  interface has been deprecated and will be removed in a later release.
  See   {{{https://issues.apache.org/jira/browse/TAP5-165}TAP5-165}} for the rationale.

  You may see type coercion errors on pages where you have specified the encoder parameter of
  the Grid, Loop or AjaxFormLoop components as a PrimaryKeyEncoder.
  These errors indicate that Tapestry was unable to automatically convert your PrimaryKeyEncoder instance into
  a {{{apidocs/org/apache/tapestry5/ValueEncoder.html}ValueEncoder}}. Generally, the only change is to invoke the new constructor for
  {{{apdiocs/org/apache/tapestry5/util/DefaultPrimaryKeyEncoder.html}DefaultPrimaryKeyEncoder}}, to identify
  the type of key used.

  If you don't use DefaultPrimaryKeyEncoder, you will see compile errors about the new method, getKeyType().
  You will have to change your code to implement that new method.
  
* Performance Improvements

  As part of the changes related to
  {{{https://issues.apache.org/jira/browse/TAP5-417}TAP5-417: Tapestry 5.0 Performance Improvements}},
  you should be aware that Tapestry will now optimize the render phase state machine.
  This is only relevant to advanced users who have written a ComponentClassTransformWorker
  that adds logic to a render phase: it is necessary to
  {{{apidocs/org/apache/tapestry5/model/MutableComponentModel.html#addRenderPhase(Class)}inform
  Tapestry that the render phase should be invoked}}.

* Tapestry/Spring

  There have been some significant changes to the {{{tapestry-spring/}tapestry-spring}} module, to
  support injection of Tapestry services into Spring beans. You may find you need to add some new configuration
  to revert to the Tapestry 5.0 behavior.

* Session Persisted Objects
                      
  Tapestry is now more aggressive about automatically re-storing any session persisted object
  back into the session at the end of the request (this used to only apply to application state objects).  See the 
  {{{guide/persist.html}persistent page data}} notes for more details.

* Module Classes

  Many questionable practices in Tapestry module classes that used to produce warnings
  have been changed to fail early (that is, throw exceptions). The rationale is that the warnings
  are almost always ignored,
  resulting in more difficult to diagnose runtime errors. 

  Extra public methods on module classes (methods that do not define services, contribute to services,
  or decorate or advise services) are now errors.