org.apache.tapestry
Interface IPage

All Superinterfaces:

IComponent, ILocatable, ILocationHolder, IRender

All Known Subinterfaces:

IExternalPage

All Known Implementing Classes:

AbstractPage, BasePage, Deck, Exception, Inspector, StaleLink, WMLException, WMLStaleLink

public interface IPage
extends IComponent

A root level component responsible for generating an entire a page within the application.

Pages are created dynamically from thier class names (part of the IComponentSpecification).

Version:

$Id: IPage.java 243791 2004-02-19 17:38:13Z hlship $

Author:

Howard Lewis Ship

See Also:

IPageSource, IPageLoader

Method Summary

void	addPageDetachListener(PageDetachListener listener)
void	addPageRenderListener(PageRenderListener listener)
void	addPageValidateListener(PageValidateListener listener)
void	attach(IEngine value) Attaches the page to the engine.
void	beginPageRender() Invoked before a partial render of the page occurs (this happens when rewinding a Form within the page).
void	beginResponse(IMarkupWriter writer, IRequestCycle cycle) Invoked just before rendering of the page is initiated.
void	detach() Invoked on a page when it is no longer needed by the engine, just before is is returned to the pool.
void	endPageRender() Invoked after a partial render of the page occurs (this happens when rewinding a Form within the page).
ChangeObserver	getChangeObserver() Returns the object (effectively, an IPageRecorder) that is notified of any changes to persistant properties of the page.
IEngine	getEngine() Returns the IEngine that the page is currently attached to.
Object	getGlobal() Returns the globally shared application object.
Locale	getLocale() Returns the Locale of the page.
IComponent	getNestedComponent(String path) Returns a particular component from within the page.
String	getPageName() Returns the fully qualified name of the page, including its namespace prefix, if any.
IRequestCycle	getRequestCycle() Returns the current IRequestCycle.
IMarkupWriter	getResponseWriter(OutputStream out) Invoked to create a response writer appropriate to the page (i.e., appropriate to the content of the page).
Object	getVisit() Returns the visit object for the application; the visit object contains application-specific information.
void	removePageDetachListener(PageDetachListener listener)
void	removePageRenderListener(PageRenderListener listener)
void	removePageValidateListener(PageValidateListener listener)
void	renderPage(IMarkupWriter writer, IRequestCycle cycle) Invoked to render the entire page.
void	setChangeObserver(ChangeObserver value)
void	setLocale(Locale value) Updates the page's locale.
void	setPageName(String pageName) Sets the name of the page.
void	setRequestCycle(IRequestCycle cycle) Invoked by the IRequestCycle to inform the page of the cycle, as it is loaded.
void	validate(IRequestCycle cycle) Method invoked by the page, action and direct services to validate that the user is allowed to visit the page.

Methods inherited from interface org.apache.tapestry.IComponent

addAsset, addBody, addComponent, finishLoad, getAsset, getAssets, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, getString, renderBody, setBinding, setContainer, setId, setNamespace, setPage, setProperty, setSpecification

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.tapestry.ILocationHolder

setLocation

Methods inherited from interface org.apache.tapestry.ILocatable

getLocation

Method Detail

detach

void detach()

Invoked on a page when it is no longer needed by the engine, just before is is returned to the pool. The page is expected to null the engine, visit and changeObserver properties.

Classes should also reset any properties to default values (as if the instance was freshly instantiated).

See Also:

IPageSource.releasePage(IPage)

getEngine

IEngine getEngine()

Returns the IEngine that the page is currently attached to.

getChangeObserver

ChangeObserver getChangeObserver()

Returns the object (effectively, an IPageRecorder) that is notified of any changes to persistant properties of the page.

getLocale

Locale getLocale()

Returns the Locale of the page. The locale may be used to determine what template is used by the page and the components contained by the page.

setLocale

void setLocale(Locale value)

Updates the page's locale. This is write-once, a subsequent attempt will throw an ApplicationRuntimeException.

getPageName

String getPageName()

Returns the fully qualified name of the page, including its namespace prefix, if any.

Since:

2.3

setPageName

void setPageName(String pageName)

Sets the name of the page.

Parameters:

pageName - fully qualified page name (including namespace prefix, if any)

Since:

3.0

getNestedComponent

IComponent getNestedComponent(String path)

Returns a particular component from within the page. The path is a dotted name sequence identifying the component. It may be null in which case the page returns itself.

Throws:

ApplicationRuntimeException - runtime exception thrown if the path does not identify a component.

attach

void attach(IEngine value)

Attaches the page to the engine. This method is used when a pooled page is claimed for use with a particular engine; it will stay attached to the engine until the end of the current request cycle, then be returned to the pool.

This method is rarely overriden; to initialize page properties before a render, override beginResponse(IMarkupWriter, IRequestCycle).

renderPage

void renderPage(IMarkupWriter writer,
                IRequestCycle cycle)

Invoked to render the entire page. This should only be invoked by IRequestCycle.renderPage(IMarkupWriter writer).

The page performs a render using the following steps:

• Invokes PageRenderListener.pageBeginRender(org.apache.tapestry.event.PageEvent)
• Invokes beginResponse(IMarkupWriter, IRequestCycle)
• Invokes IRequestCycle.commitPageChanges() (if not rewinding)
• Invokes IRender.render(IMarkupWriter, IRequestCycle)
• Invokes PageRenderListener.pageEndRender(org.apache.tapestry.event.PageEvent) (this occurs even if a previous step throws an exception).

beginPageRender

void beginPageRender()

Invoked before a partial render of the page occurs (this happens when rewinding a Form within the page). The page is expected to fire appopriate events.

Since:

2.2

endPageRender

void endPageRender()

Invoked after a partial render of the page occurs (this happens when rewinding a Form within the page). The page is expected to fire appropriate events.

Since:

2.2

setChangeObserver

void setChangeObserver(ChangeObserver value)

validate

void validate(IRequestCycle cycle)

Method invoked by the page, action and direct services to validate that the user is allowed to visit the page.

Most web applications have a concept of 'logging in' and pages that an anonymous (not logged in) user should not be able to visit directly. This method acts as the first line of defense against a malicous user hacking URLs.

Pages that should be protected will typically throw a PageRedirectException, to redirect the user to an appropriate part of the system (such as, a login page).

Since 3.0, it is easiest to not override this method, but to implement the PageValidateListener interface instead.

getResponseWriter

IMarkupWriter getResponseWriter(OutputStream out)

Invoked to create a response writer appropriate to the page (i.e., appropriate to the content of the page).

beginResponse

void beginResponse(IMarkupWriter writer,
                   IRequestCycle cycle)

Invoked just before rendering of the page is initiated. This gives the page a chance to perform any additional setup. One possible behavior is to set HTTP headers and cookies before any output is generated.

The timing of this explicitly before page recorder changes are committed. Rendering occurs after the recorders are committed, when it is too late to make changes to dynamic page properties.

getRequestCycle

IRequestCycle getRequestCycle()

Returns the current IRequestCycle. This is set when the page is loaded (or obtained from the pool) and attached to the engine.

setRequestCycle

void setRequestCycle(IRequestCycle cycle)

Invoked by the IRequestCycle to inform the page of the cycle, as it is loaded.

getVisit

Object getVisit()

Returns the visit object for the application; the visit object contains application-specific information.

getGlobal

Object getGlobal()

Returns the globally shared application object. The global object is stored in the servlet context.

Returns the global object, if it exists, or null if not defined.

Since:

2.3

addPageRenderListener

void addPageRenderListener(PageRenderListener listener)

Since:

1.0.5

removePageRenderListener

void removePageRenderListener(PageRenderListener listener)

Since:

2.1

addPageDetachListener

void addPageDetachListener(PageDetachListener listener)

Since:

1.0.5

removePageDetachListener

void removePageDetachListener(PageDetachListener listener)

Since:

2.1

addPageValidateListener

void addPageValidateListener(PageValidateListener listener)

Since:

3.0

removePageValidateListener

void removePageValidateListener(PageValidateListener listener)

Since:

3.0