| Required Pages | ||
|---|---|---|
 | Chapter 5. Application Engines and Services |  |
| Required Pages | ||
|---|---|---|
| | Chapter 5. Application Engines and Services | |
Each application is required to have a minimum of five pages with specific names. Tapestry provides default implementations for four of the five, but a full-featured Tapestry application may override any of the others to provide a consistent look-and-feel.
Table 5.1. Tapestry Pages
| Page Name | Required | Description |
|---|---|---|
| Exception | Default provided, may be overridden. | Page used to present uncaught exceptions to the user. |
| Home | Must be provided by developer. | The initial page displayed when the application is started. |
| Inspector | Provided, never overriden. | Inspector that allows the Tapestry application to be interrogated on its structure. |
| StaleLink | Provided | Page displayed when a StaleLinkException is thrown during the processing of a request. |
| StaleSession | Provided | Page displayed when a StaleSessionException is thrown during the processing of a request. |
Tapestry only mandates the logical name of these four pages; the actual page component used is defined in the application specification.
The Home page is the first page viewed by a client connecting to the application.
Other than that,
there is nothing special about the page.
The initial connection to the application, where nothing is specified in the URL but the path to the servlet, causes the home service to be invoked, which makes use of the home page. The restart service will also redirect the user to the home page.
No default is provided for the Home page; every Tapestry application must define its
own Home page.
The Exception page is invoked whenever an uncaught exception is thrown when processing a service.
The Tapestry framework catches the exception and discards any HTML output (this is why output is buffered in memory).
The Exception page must implement a writable JavaBeans property of type
java.lang.Throwable named exception.
The framework will invoke the accessor method
before the page is rendered.
The class ExceptionAnalyzer and the
ExceptionDisplay component are typically used to present this information.
The StaleLink page is displayed when a StaleLinkException
is thrown, which may occur during the processing of the request. The exception is thrown when
Tapestry determines that the state of the page (on the server) is out of synch with the client's view
of the page ... this most often happens when the user makes use of the browser's back button.
[3]
The default implementation informs the user of the problem ("you really shouldn't use the back
button on your browser") and uses the home service to create a link back to the
Home page.
The StaleSession page is displayed when a
org.apache.tapestry.StaleSessionException
is thrown. This exception is thrown when the component
is configured to be stateful (which is the default)
and the HttpSession doesn't exist, or is
newly created - this indicates a fresh connection to the servlet container after the old session
timed out and was discarded.
[4]
The Inspector page is provided by the framework;
it allows a developer to interrogate a running
Tapestry application to determine its structure.
[3]
If desired, the application engine can override the method
handleStaleLinkException(). The default implementation of
this method redirects to the StaleLink page, but a custom implementation
could set up an error message on the application's Home page and
redirect there instead.
[4]
Likewise, the default behavior can be changed by overriding the method
handleStaleSessionException().
| |  | |
| Application Servlet |  | Server-Side State |