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.
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 now includes a new mechanism for ensuring the security of server-side assets, addressing a bug that allowed a malicious user to search and download any file on the classpath. The new approach is more secure, but is based on explicitly extending access; some existing frameworks (created to be compatible with Tapestry 5.1) will need additional configuration to extend access to their assets. See the notes on securing Assets.
Tapestry no longer uses a StAX parser (it uses a normal SAX parser) to parse component templates. This change reduces the number of dependencies for Tapestry, and is a stepping stone to 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.