Page History

...

Many of the basic concepts in Tapestry 4 are still present in Tapestry 5, but refactored, improved, streamlined, and simplified. The basic concept of pages, templates and components are largely the same. Other aspects, such as server-side event handling, is markedly different.

How do I upgrade from one version of Tapestry 5 to another?

A lot of effort goes into making an upgrade from one Tapestry 5 release to another go smoothly. In the general case, it is just a matter of updating the version number in your Maven build.xml or Gradle build.gradle file and executing the appropriate commands (e.g., gradle idea or mvn eclipse:eclipse) to bring your local workspace up to date with the latest binaries.

We make every effort to ensure backwards-compatibility; you should always be able to upgrade and, at most, recompile your code. Tapestry is mostly coded in terms of interfaces; those interfaces are stable to a point: interfaces your code is expected to implement are usually completely frozen; interfaces your code is expected to invoke, such as the interfaces to IoC services, are stable, but may have new methods added in a release; existing methods are not changed.

In rare cases a choice is necessary between fixing bugs (or adding essential functionality) and maintaining stability; in those cases, an incompatible change may be introduced. These are always discussed in detail in the Release Notes for the specific release. You should always read the release notes before attempting an upgrade, and always (really, always) be prepared to retest your application afterwards.

Note that you should be careful any time you make use of internal APIs (you can tell an API is internal by the package name, org.apache.tapestry5.internal.... Internal APIs may change at any time; there's no backwards-compatible guarantee. Please always check on the documentation, or consult the user mailing list, to see if there's a stable, public alternative. If you do make use of internal APIs, be sure to get a discussion going so that your needs can be met in the future by a stable, public API.

A final note: Tapestry incorporates your application's version number into the URLs for JavaScript, CSS, and other assets exposed to the browser; these assets are cached on the browser with the assumption that when the server-side assets are changed, the version number (and thus the URL) will change as well. This version number applies to framework-provided assets as well as those specific to your application.

Thus, whenever you upgrade, you must change the tapestry.application-version configuration symbol as well. If you fail to do so, you will see odd behavior in some clients who may be running a mix of old and new assets. This can result in execution errors or incorrect behavior in your clients.

Again, after an upgrade to a new version of Tapestry, change your application version number as well to ensure that the latest version of all assets are downloaded into your client's browsers.

Why are there both Request and HttpServletRequest?

...