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

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

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 addPageRenderListener(PageRenderListener listener)
          Deprecated. To be removed in 4.1 Use addPageBeginRenderListener(PageBeginRenderListener)or addPageEndRenderListener(PageEndRenderListener).
 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 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 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.
 java.lang.Object getGlobal()
          Deprecated. To be removed in 4.1. Inject an application state object instead. Do not attempt to inject property global.
 java.util.Locale getLocale()
          Returns the Locale of the page.
 IComponent getNestedComponent(java.lang.String path)
          Returns a particular component from within the page.
 java.lang.String getPageName()
          Returns the fully qualified name of the page, including its namespace prefix, if any.
 IRequestCycle getRequestCycle()
          Returns the current IRequestCycle.
 ContentType getResponseContentType()
          Invoked to obtain the content type to be used for the response.
 java.lang.Object getVisit()
          Deprecated. To be removed in 4.1. Inject an application state object instead. Do not attempt to inject property visit.
 void removePageAttachListener(PageAttachListener listener)
           
 void removePageBeginRenderListener(PageBeginRenderListener listener)
           
 void removePageDetachListener(PageDetachListener listener)
           
 void removePageEndRenderListener(PageEndRenderListener listener)
           
 void removePageRenderListener(PageRenderListener listener)
          Deprecated. To be removed in 4.1. Use removePageBeginRenderListener(PageBeginRenderListener)or removePageEndRenderListener(PageEndRenderListener).
 void removePageValidateListener(PageValidateListener listener)
           
 void renderPage(IMarkupWriter writer, IRequestCycle cycle)
          Invoked to render the entire page.
 void setChangeObserver(ChangeObserver value)
           
 void setLocale(java.util.Locale value)
          Updates the page's locale.
 void setPageName(java.lang.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, getComponent, getComponents, getContainedComponent, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, isRendering, renderBody, setBinding, setContainedComponent, setContainer, setId, setNamespace, setPage, setProperty
 
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

public 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

public IEngine getEngine()
Returns the IEnginethat the page is currently attached to.


getChangeObserver

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


getLocale

public java.util.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

public void setLocale(java.util.Locale value)
Updates the page's locale. This is write-once, a subsequent attempt will throw an ApplicationRuntimeException.


getPageName

public java.lang.String getPageName()
Returns the fully qualified name of the page, including its namespace prefix, if any.

Since:
2.3

setPageName

public void setPageName(java.lang.String pageName)
Sets the name of the page.

Parameters:
pageName - fully qualified page name (including namespace prefix, if any)
Since:
3.0

getNestedComponent

public IComponent getNestedComponent(java.lang.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

public 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

public 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

public 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:


beginPageRender

public 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

public 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

public void setChangeObserver(ChangeObserver value)

validate

public 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 , 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 PageValidateListenerinterface instead.


getResponseContentType

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


beginResponse

public 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 recorderchanges are committed. Rendering occurs after the recorders are committed, when it is too late to make changes to dynamic page properties.


getRequestCycle

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


getVisit

public java.lang.Object getVisit()
Deprecated. To be removed in 4.1. Inject an application state object instead. Do not attempt to inject property visit.

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


getGlobal

public java.lang.Object getGlobal()
Deprecated. To be removed in 4.1. Inject an application state object instead. Do not attempt to inject property global.

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

public void addPageRenderListener(PageRenderListener listener)
Deprecated. To be removed in 4.1 Use addPageBeginRenderListener(PageBeginRenderListener)or addPageEndRenderListener(PageEndRenderListener).

Since:
1.0.5

removePageRenderListener

public void removePageRenderListener(PageRenderListener listener)
Deprecated. To be removed in 4.1. Use removePageBeginRenderListener(PageBeginRenderListener)or removePageEndRenderListener(PageEndRenderListener).

Since:
2.1

addPageBeginRenderListener

public void addPageBeginRenderListener(PageBeginRenderListener listener)
Since:
4.0

removePageBeginRenderListener

public void removePageBeginRenderListener(PageBeginRenderListener listener)
Since:
4.0

addPageEndRenderListener

public void addPageEndRenderListener(PageEndRenderListener listener)
Since:
4.0

removePageEndRenderListener

public void removePageEndRenderListener(PageEndRenderListener listener)
Since:
4.0

addPageDetachListener

public void addPageDetachListener(PageDetachListener listener)
Since:
1.0.5

removePageDetachListener

public void removePageDetachListener(PageDetachListener listener)
Since:
2.1

addPageValidateListener

public void addPageValidateListener(PageValidateListener listener)
Since:
3.0

removePageValidateListener

public void removePageValidateListener(PageValidateListener listener)
Since:
3.0

addPageAttachListener

public void addPageAttachListener(PageAttachListener listener)
Since:
4.0

removePageAttachListener

public void removePageAttachListener(PageAttachListener listener)
Since:
4.0