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 project-wide release notes for information about bugs fixes and other improvements.
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.".
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.
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.
The 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 ComponentClassTransformWorkers, 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.
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.
Tapestry's alpha URL rewriting support (available from 5.1.0.1) has undergone some API changes:
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.
Tapestry's client-side JavaScript relating to input field validation has changed somewhat to account for TAP5-211. This will only affect users who have created their own client-side validations.
The handling of the Secure annotation is now only enabled in production mode (by default).
This is the change between releases that is most likely to affect your upgrade.
The PrimaryKeyEncoder interface has been deprecated and will be removed in a later release. See 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 ValueEncoder. Generally, the only change is to invoke the new constructor for 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.
As part of the changes related to 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 inform Tapestry that the render phase should be invoked.
There have been some significant changes to the 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.
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 persistent page data notes for more details.
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.