src/site/apt/index.apt

 ----
 Apache Tapestry 5
 ----
 
What is Tapestry?

 Tapestry is an open-source framework for creating dynamic, robust, highly scalable web applications in Java. 
 Tapestry complements and builds upon the standard Java Servlet API, and so it works in any servlet container or application server.

 Tapestry divides a web application into a set of pages, each constructed from components. This provides a consistent structure, 
 allowing the Tapestry framework to assume responsibility for key concerns such as URL construction and dispatch, persistent state 
 storage on the client or on the server, user input validation, localization/internationalization, and exception reporting. 
 Developing Tapestry applications involves creating HTML templates using plain HTML, and combining the templates with small amounts of 
 Java code. In Tapestry, you create your application in terms of objects, and the methods and properties of those 
 objects -- and specifically not in terms of URLs and query parameters. 
 Tapestry brings true object oriented development to Java web applications.

 Tapestry is specifically designed to make creating new components very easy, 
 as this is a routine approach when building applications. 
 
 Tapestry is architected to scale from tiny, single-page applications all the way up to
 massive applications consisting of hundreds of individual pages, developed by
 large, diverse teams. Tapestry easily integrates with any kind of backend, including JEE, 
 HiveMind, Spring and Hibernate.
 
 It's more than what you <can> do with Tapestry ... it's also <how> you do it!  Tapestry is a vastly productive environment.
 Java developers love it because they can make <Java code> changes and see them immediately ... no redeploy, no restart! And it's blazingly fast to boot
 (even when files change). Designers
 love it because Tapestry templates are so close to ordinary HTML, without all the cruft and confusion seen in JavaServer Pages. Managers love it because
 it makes it easy for large teams to work together, and because they know important features (including localization) are baked right in. Once you work
 in Tapestry there's no going back!

 Tapestry is released under the Apache Software Licence 2.0.

Where To Go

 You are currently reading the Tapestry 5 project site.  Tapestry itself is broken into several modules:
 
*---+---+
| {{{tapestry-annotations/index.html}tapestry-annotations}} | A few Tapestry annotations that may be used with non-component classes. |
*---+---+
| {{{tapestry-core/index.html}tapestry-core}} | The core implementation of the Tapestry framework, including all the primary built-in components. |
*---+---+
| {{{tapestry-hibernate/index.html}tapestry-hibernate}} |  Integration with the {{{http://hibernate.org}Hibernate}} Object/Relational Mapping framework. |
*---+---+
| {{{tapestry-ioc/index.html}tapestry-ioc}} |  The Tapestry Inversion of Control Container. |
*---+---+
| {{{tapestry-spring/index.html}tapestry-spring}} |  Integration with {{{http://springframework.org}Spring}}. |
*---+---+
| {{{tapestry-test/index.html}tapestry-test}} |  Tapestry test utilities. |
*---+---+
| {{{tapestry-upload/index.html}tapestry-upload}} |  Tapestry file upload component. |
*---+---+
 
  Or, you can start with the {{{screencast.html}screencasts}}, which give you a better idea about how Tapestry fits together.

Roadmap

  Tapestry is, of course, an open-source project, with all the work coming from unpaid volunteers.  That being said, our rough timeline is as follows:
  
  * 5.0 Release Candidate in Q1 2008

  * 5.0 Final Release shortly thereafter

  * 5.1 development to follow, on a much shorter release schedule

  * ... but we are all open source developers working on our own time and schedules are hard to pin down.  Please be patient.  Tapestry 5
    is increasingly stable.  Further "stable" with Tapestry usually refers to names of interfaces and methods, not to code quality,
    which is always very, very high.

  * We are now edging towards a release candidate, with most work being documentation, minor bug fixes and modest
    enhancements.
     
  []

Third Party Libraries, Tutorials and Resources

  Tapestry 5 has inspired a number of people to create third party libraries, providing a mix of new components
  and new and improved integrations.

*--+--+--+
| <<Name>> | <<Author>> | <<Description>>
*--+--+--+
| {{{http://equanda.org/equanda-tapestry5/}equanda-tapestry5}} |   Joachim Van der Auwera |      Components useful for building enterprise applications. Includes Accordion, Tabs, Formtraversal. Amongst other things, these focus on easy input of data without the need for a mouse.
*--+--+--+
| {{{http://code.google.com/p/gc-tapestry-components/}Godcode Components}} |   Chris Lewis |         A mixed collection of components providing simple but time-saving functionality, as well as more exotic ones; built on top of the prototype and script.aculo.us javascript libraries. |
*--+--+--+
| {{{http://files.doublenegative.com.au/jumpstart/}JumpStart}} |   Geoff Callender | A "living tutorial" in the form of a base Tapestry application ready to be expanded and customized. |
*--+--+--+
| {{{http://interldap.org}InterLDAP}} | Linagora / Francois Armand | LDAP content management system for non tech users. |
*--+--+--+
| {{{http://code.google.com/p/shams/}Shams Examples, Components}} |  Mohammad H. Shamsi |   A set of Tapestry 5 Examples, Tutorials, Components, and Documents for beginners. |
*--+--+--+
| {{{http://code.google.com/p/tapestry5-components/}T5Components}} | Sven Homburg | Ajax-enabled components based on Prototype and Scriptaculous. |
*--+--+--+
| {{{http://tacos.sourceforge.net/tacos5/tacos-seam/}tacos-seam}} | Igor Drobiazko | Intregrates with {{{http://www.jboss.com/products/seam}JBoss Seam}}. |
*--+--+--+
| {{{http://www.localhost.nu/java/tapestry5-acegi/}tapestry5-acegi}} | Robin Helgelin  | Integration with the Acegi path-based security framework. |
*--+--+--+
| {{{http://code.google.com/p/tapestry5-treegrid/}tapestry5-treegrid}} | Gabriel Landais |  Combination tree navigation and data grid, based on sstree. |
*--+--+--+


What's changed since Tapestry 4?

  Tapestry 5 is an all new code base, written from the ground up to take Java web
  component development to new levels of productivity.
  
  This new release removes many limitations of Tapestry 4:
  
  * Components no longer extend from base classes.
  
  * {{{tapestry-core/guide/component-classes.html}Components classes are no longer <abstract>}}.  
     Components are pure, simple POJOs (<plain old Java
    objects>).
  
  * Tapestry no longer uses XML page and component specification files. Information that used to
    be supplied in such files is now supplied directly in the Java class, using Java annotations and naming conventions.
    
  * {{{tapestry-core/guide/reload.html}Changes to Tapestry component templates <and classes> are now picked up <immediately>}}, 
    without any kind
    of restart. This will even work properly in <production>, not just during development.
    
  * <<Blazing Speed>>. The new code base operates considerably faster than Tapestry 4. Critical
  code paths have been simplified, and the use of reflection has been virtually eliminated.
  Tapestry 4 was as fast as an equivalent Servlet/JSP application, Tapestry 5 is much faster.
    
  []
  
New and Noteworthy

  * In order to support Tapestry 4 applications co-existing with Tapestry 5 applications within the same WAR,
    a small number of Tapestry 5 classes and packages have been renamed or refactored.  For more information,
    see the upgrade notes for
    {{{tapestry-ioc/upgrade.html}tapestry-ioc}} and
    {{{tapestry-core/upgrade.html}tapestry-core}}.

  * A {{{faq/general.html}FAQ (Frequently Asked Questions) page}} has been added.

  * An {{{tapestry-ioc/overview.html}overview}} and {{{tapestry-ioc/cookbook/}cookbook}} for Tapestry IoC has been written.

  * The nightly build on the {{{http://tapestry.formos.com/bamboo}Bamboo CI server}} now creates 
    {{{http://tapestry.formos.com/nightly/tapestry5/}full documentation}}.

  * There is now a RegistryStartup service, allowing you to provide logic that executes when the Registry is first created.

  * Logging in Tapestry is now implemented on top of {{{http://www.slf4j.org/docs.html}Simple Logging Facade for Java}}.
 
  * A file upload form component has been added, in a new library: {{{tapestry-upload/}tapestry-upload}}. 
 
  * The {{{tapestry-spring/}tapestry-spring}} module has also been simplified, to make
  Spring beans look like Tapestry IoC services. It's all now quite seamless.

  * The {{{tapestry-ioc/}tapestry-ioc}} module has been simplified, removing the concept
  of module ids and namespaces, as well as private services, and borrowing a lot of cool
  ideas from {{{http://code.google.com/p/google-guice/}Guice}}. The goal is to make the container
  all but invisible.

  * Work has been started on {{{http://hibernate.org}Hibernate}} integration in the
  new {{{tapestry-hibernate/}tapestry-hibernate}} module.

  * A few simple utility classes for building integration tests (on top of 
  {{{http://www.openqa.org/selenium/}Selenium}}) have been split out as a new module: 
  {{{tapestry-test/}tapestry-test}}.
    
  * A  module for integrating Tapestry 5 with {{{http://springframework.org/}Spring}} has been
  added: {{{tapestry-spring/}tapestry-spring}}.

  * A Maven plugin to generate documentation about components and parameters has been added:
  {{{tapestry-component-report/}tapestry-component-report}}.
 
  * {{{http://www.formos.com}Formos}} has donated hardware and bandwidth to support the Tapestry project, starting
  with a {{{http://tapestry.formos.com/bamboo}continuous integration site}} running on
  {{{http://www.atlassian.com/software/bamboo/}Bamboo}}.  And thanks to Atlassian for donating
  the Bamboo license.

  * Howard Lewis Ship has begun work on a {{{tutorial1/}Tapestry 5 Tutorial}}. 
  
  [] 
    
About Snapshots and Releases

  Tapestry is built using {{{http://maven.apache.org/}Maven}}, which makes it really easy to download the source and build it yourself, either the whole
  project, or just one single module.
  
  Better yet, you can pull down Tapestry modules from the central Maven repository.
  
  The use of Maven has let us move with great speed, providing preview releases and <snapshots>.
  
  Snapshots are <intermediate versions> of releases. As I'm writing this, the most recent preview release is 5.0.2 and the current snapshots are
  for 5.0.3-SNAPSHOT.  Maven keys off the -SNAPSHOT suffix and handles the dependency specially. It knows that snapshot releases can change frequently,
  so it will keep checking (at least once a day, maybe more often) to see if there's an updated version of the snapshot.
  
  A nightly build process on Tapestry's continuous integration server creates new snapshots <em>every night</em>.
  
  Snapshots don't go in the central Maven repository (that's reserved for full releases). Instead, they  go into the Tapestry snapshots repository
  at {{{http://tapestry.formos.com/maven-snapshot-repository}http://tapestry.formos.com/maven-snapshot-repository}}.
  
  To access this repository, you may add <<<-DremoteRepositories=http://tapestry.formos.com/maven-snapshot-repository>>> to the command line when
  running Maven.
  
  Your best bet is to use the {{{quickstart/}quickstart Maven archetype}} to create your initial Tapestry project; it generates a full project
  directory, including a POM that links to the Apache snapshots repository.
  
  <<Documentation on this site usually refers to the latest snapshot ... that is, it is usually ahead of the last official release. In some cases,
  it is written as if the snapshot release is stable; if documentation refers to version 5.0.x and that doesn't work, try 5.0.x-SNAPSHOT.>>
    
Principle 1 -- Static Structure, Dynamic Behavior

  Tapestry is designed to be extremely scalable in several dimensions:
  
  * Tapestry applications may contain many pages and many custom components.
  
  * Tapestry applications may contain very complex functionality.
  
  * Tapestry applications may be created by large, diverse teams.
  
  * Tapestry applications can service large numbers of concurrent users.
  
 One core architecture decision in Tapestry exists to service many of the above goals
 (and others that are harder to describe).  <<Static Structure, Dynamic Behavior>>

 In Tapestry, the structure of any particular page is <static>. This is necessary for
 several reasons, most importantly because Tapestry pages are <pooled>.  Creating a Tapestry page
 is an involved process, because the page object is simply the root of a large tree of other
 objects including user provided components, many kinds of structural objects, template objects,
 and others. Creating a new page instance for each request is simply not <scalable>.
 
 Instead, Tapestry <pools> pages.  Once created, a page instance will be stored in a pool for
 that particular type of page, and reused
 in later requests. An incoming request, the result of a user clicking a link or submitting a form,
 will be processed by <some> server within a cluster, and will use <some> page instance within the
 page pool. Because page instances are static and uniform across instances and servers, 
 Tapestry can use any available page instance, or create a new one as needed.
 
 Tapestry does not need to store page instances inside the HttpSession. At most, it stores a smattering
 of <persistent field values> from the page, but not the entire page instance. This lean
 use of the HttpSession is key to Tapestry's very high scalability, especially in a clustered
 configuration.
 
 In some Tapestry-like frameworks, such as Faces and Wicket, the page structure is more dynamic, at 
 the cost of storing much, much more data in the HttpSession.
 
 This static structure is not so limiting as you might think. With different kinds of conditional
 and looping components, and the ability to "jump out of the flow" and render components in an arbitrary order, 
 you will not find Tapestry to be rigid ... anything but!
  
Public vs. Internal

  An issue plaguing previous versions of Tapestry 4 (and earlier) was the lack of a clear delineator
  between private, internal APIs and public, external APIs.  The fact that your code would extend
  from base objects but that many of the methods on those base objects were "off limits"
  further confused the issue. This has been identified as a key factor in the
  "steep learning curve of Tapestry" meme.
  
  With the clean slate of Tapestry 5, we are being much more ruthless about internal vs. external.
  
  First of all, anything inside the org.apache.tapestry5.internal package
  is <<internal>>.  It is part of the implementation of Tapestry.  It is the man behind the curtain.
  You should not ever need to directly use this code.  It is a <<bad idea>> to do so, because
  internal code may <<change from one release to the next>> without concern for backwards
  compatibility.
  
Backwards Compatibility

  Tapestry has been plagued by backwards compatibility problems with every major release. Tapestry 5
  does not even attempt to be backwards compatible to Tapestry 4. Instead, it lays the ground work for
  true backwards compatibility going forwards.
  
  Tapestry 5's API is based almost entirely on naming conventions and <annotations>.  You components are just
  ordinary Java classes; you will annotate fields to allow Tapestry to maintain their state or to allow Tapestry 
  to inject resources, and you will name (or annotate) methods to tell Tapestry under what circumstances
  a method should be invoked.
  
  Tapestry will adapt to your classes. It will call your methods, passing in values via method parameters. 
  Instead of the rigidness of a fixed interface to implement, Tapestry will simply adapt to your classes, using
  the hints provided by annotations and simple naming conventions.
  
  Because of this, Tapestry will be able to change internally to a great degree without it affecting any
  of the application code <you> write. This should finally crack the backwards compatibility nut, allowing you to have
  great assurance that you can upgrade to future releases of Tapestry without breaking your existing applications.