org.apache.tapestry
Interface IPage

All Superinterfaces:

IComponent, IRender, org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder

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 their class names (part of the IComponentSpecification).

Author:

Howard Lewis Ship

See Also:

IPageSource, IPageLoader

Method Summary

void	addPageAttachListener(PageAttachListener listener)
void	addPageBeginRenderListener(PageBeginRenderListener listener)
void	addPageDetachListener(PageDetachListener listener)
void	addPageEndRenderListener(PageEndRenderListener listener)
void	addPageValidateListener(PageValidateListener listener)
void	attach(IEngine engine, IRequestCycle cycle) Attaches the page to the engine.
void	beginPageRender() Invoked before a partial render of the page occurs (this happens when rewinding a Formwithin the page).
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 Formwithin the page).
void	firePageAttached() Used to explicitly fire PageAttachListeners for this 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 IEnginethat the page is currently attached to.
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.
PropertyChangeObserver	getPropertyChangeObserver() Returns the injected property change service responsible for monitoring changes to individual object properties being persisted.
IRequestCycle	getRequestCycle() Returns the current IRequestCycle.
ContentType	getResponseContentType() Invoked to obtain the content type to be used for the response.
boolean	hasFormComponents() Whether or not this page contains IForm instances.
boolean	hasWidgets() Whether or not this page contains IWidget instances.
void	removePageAttachListener(PageAttachListener listener)
void	removePageBeginRenderListener(PageBeginRenderListener listener)
void	removePageDetachListener(PageDetachListener listener)
void	removePageEndRenderListener(PageEndRenderListener listener)
void	removePageValidateListener(PageValidateListener listener)
void	renderPage(ResponseBuilder builder, IRequestCycle cycle) Invoked to render the entire page.
void	setChangeObserver(ChangeObserver value)
void	setHasFormComponents(boolean value) Sets whether or not page has forms.
void	setHasWidgets(boolean value) Sets whether or not page has widgets.
void	setLocale(Locale value) Updates the page's locale.
void	setPageName(String pageName) Sets the name of the page.
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, enterActiveState, finishLoad, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getClientId, getComponent, getComponents, getContainedComponent, getContainer, getEventInvoker, getExtendedId, getId, getIdPath, getListeners, getMessages, getNamespace, getPage, getSpecification, getSpecifiedId, getTemplateTagName, isRendering, peekClientId, renderBody, setBinding, setClientId, setContainedComponent, setContainer, setId, setNamespace, setPage, setTemplateTagName

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

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 IEnginethat 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.

getPropertyChangeObserver

PropertyChangeObserver getPropertyChangeObserver()

Returns the injected property change service responsible for monitoring changes to individual object properties being persisted.

Returns:

The injected property change service.

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:

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

attach

void attach(IEngine engine,
            IRequestCycle cycle)

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 will notify any PageAttachListeners.

This method is rarely overriden; to initialize page properties before a render, implement the PageBeginRenderListenerinterface.

firePageAttached

void firePageAttached()

Used to explicitly fire PageAttachListeners for this page. This is used when a page is first loaded; The page loader attaches the newly created page instance before the rest of the page and components is loaded. In order to have meaningful event notifications when a page is first loaded (rather than pulled from the pool), it is necessary to fire page attach listeners at the end of the load.

Since:

4.0

renderPage

void renderPage(ResponseBuilder builder,
                IRequestCycle cycle)

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

The page performs a render using the following steps:

• Invokes PageBeginRenderListener.pageBeginRender(org.apache.tapestry.event.PageEvent)
• Invokes beginPageRender()
• Invokes IRequestCycle.commitPageChanges()(if not rewinding)
• Invokes IRender.render(IMarkupWriter, IRequestCycle)
• Invokes PageEndRenderListener.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 Formwithin 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 Formwithin 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.

getResponseContentType

ContentType getResponseContentType()

Invoked to obtain the content type to be used for the response. The implementation of this method is the primary difference between an HTML page and an XML/WML/etc. page.

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.

hasFormComponents

boolean hasFormComponents()

Whether or not this page contains IForm instances.

Returns:

True if page contains forms, false otherwise.

setHasFormComponents

void setHasFormComponents(boolean value)

Sets whether or not page has forms.

Parameters:

value - Indicator of containing forms.

hasWidgets

boolean hasWidgets()

Whether or not this page contains IWidget instances.

Returns:

True if page contains widgets, false otherwise.

setHasWidgets

void setHasWidgets(boolean value)

Sets whether or not page has widgets.

Parameters:

value - Indicator of containing widgets.

addPageBeginRenderListener

void addPageBeginRenderListener(PageBeginRenderListener listener)

Since:

4.0

removePageBeginRenderListener

void removePageBeginRenderListener(PageBeginRenderListener listener)

Since:

4.0

addPageEndRenderListener

void addPageEndRenderListener(PageEndRenderListener listener)

Since:

4.0

removePageEndRenderListener

void removePageEndRenderListener(PageEndRenderListener listener)

Since:

4.0

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

addPageAttachListener

void addPageAttachListener(PageAttachListener listener)

Since:

4.0

removePageAttachListener

void removePageAttachListener(PageAttachListener listener)

Since:

4.0