This is a quick guide to changes between snapshot releases of Tapestry 5.0. This is meant to provide information on any additions or changes that developers will face after upgrading to the latest version of Tapestry.
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.
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.
The client-side class Tapestry.Zone has been renamed to Tapestry.ZoneManager.
Method getElementName() of the RadioContainer interface was renamed to getControlName(), to bring it into alignment with the analagous method of the Field interface.. This should not affect any user code.
A method of the interface GridSortModel was renamed to correct a misspelling.
The methods findFields() and findFieldsWithAnnotation() of ClassTransformation have been changed to return all fields (regardless of whether they have been claimed). The method findAllFieldsWithAnnotation() has been removed.
Some significant overhauling of Tapestry's client-side validation support has occurred. If you have created your own validations, or have overriden how Tapestry decorates fields and presents error messages, you will need to make some changes to your code.
Several API changes related to Translator have occured, to support client-side validation of user input.
The signature of the BeanModelSource.create() method has changed; the last parameter is now Messages, not ComponentResources.
The Grid, PropertyDisplay, PropertyEditor and BeanEditor components have had their override parameter changed from ComponentResources to the new PropertyOverrides interface. No changes should be necessary, as Tapestry can coerce ComponentResources to PropertyOverrides.
Attempting to instantiate a component class will now result in a runtime exception (this is a common beginner's mistake; pages and components should be injected, not instantiated).
Properties files in message catalogs are now automatically read using the UTF-8 charset. Unlike traditional Java ResourceBundles, it is not necessary to use Java's native2ascii tool.
TAPESTRY-2543 simplifies Tapestry's approach to localization, as it pertains to output and request character encodings. Previously, each page could be configured with a different character encoding, which causes a number of problems related to Ajax and file upload requests. A single application-wide character encoding is now used, by default UTF-8.
As part of TAPESTRY-2311, there have been subtle changes to how event handler and render phase methods are invoked, when the methods are overrides of base class methods.
Several methods of ClassFabUtils have been removed. The new method is an improved replacement for the removed methods. These methods were largely used when decorating services, and the new AspectDecorator is even easier.
Tapestry now organizes JavaScript a bit differently; all JavaScript is at the bottom of the page, just before the </body> tag. This applies to both externally loaded scripts, and to per-page dynamically generated JavaScript.
This can cause some pages to break, those that included inline <script> blocks in their templates. You should inject the RenderSupport environmental and use it to include JavaScript properly.
A new annotation, ReorderProperties (which is placed on a type) has replaced the OrderAfter and OrderBefore annotations (which were placed on accessor methods).
The root package for all Tapestry code was changed from org.apache.tapestry to org.apache.tapestry5. This will make it reasonable to deploy Tapestry 3 or Tapestry 4 applications side-by-side with a Tapestry 5 application.
In addition, a number of classes were refactored.
PageRenderSupport has been renamed to just RenderSupport.
TapestryConstants has been removed, split into a number of new classes (by type), such as SymbolConstants.
Likewise, TapestryUtils has been split into MarkupUtils and VersionUtils.
Many of the internal services of Tapestry have been split off into their own module, InternalModule. This should not affect any user code.
The default ValidationTracker built into the Form component now has a persistence strategy of "flash". This means that if you navigate away from a page with validation errors and return, you will lose the errors. To support this style of navigation, you will need to bind the Form's tracker parameter to a field that has the correct persistency (most likely, "session", the previous persistence strategy).
The methods exists() and openStream() were added to the Resource interface. The semantics of some of the other methods were slightly alterred.
The Loop component's elementName parameter was renamed to simply element (to be consistent with element parameters added to the Any and FormInjector components).
The method getElementName() on interface Field was renamed to getControlName(). This brings the property in alignment with W3C documentation and terminology, and helps differentiate from the element name (i.e., the tag name used to represent the element in a component template).
This affects a number of existing components that implement the interface.
Method allocateElementName() on interface FormSupport was likewise renamed to allocateControlName().
The show and hide parameters of the Zone component now have a default binding prefix of "literal".
In addition, the client-side Tapestry.ZoneEffect object was renamed to Tapestry.ElementEffect to reflect that it can be used with elements that are not explicitly Zones.
The method invokeIfBlank() on interface Validator was renamed to isRequired().
The findMeta() method on interface MetaDataLocator has changed significantly; it now expands symbols and performs type coercion.
The GridModel interface and the prepare() method of GridDataSource have changed to accommodate the ability to sort using multiple columns.
The getWidth() method was removed from the PropertyModel interface; the logic for deducing the desired field size from the @Width annotation has been moved into AbstractTextField.
The data type for boolean values has changed from "checkbox" (reflecting how it is rendered in an edit form) to "boolean" (reflecting what it is). In addition, all numeric types are given the data type "number". This will only affect your application if you provided an overriding contribution to the BeanBlockSource service.
The return type for getStackTrace() on ExceptionInfo changed from List<String> to List<StackTraceElement>.
The store methods on these two interfaces were renamed to be more explicit. These are not methods typically invoked from user code.
The remove() method of BeanModel was renamed to exclude(), and a new method, include() was added. The remove parameter of BeanEditForm, BeanEditor, BeanDisplay and Grid were all renamed to exclude as well (and a new include parameter was added to each).