com.primix.tapestry
Interface IPage

All Superinterfaces:
IComponent, IRender
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 ComponentSpecification).

Version:
$Id: IPage.java,v 1.17 2001/08/28 20:33:41 hship Exp $
Author:
Howard Ship
See Also:
IPageSource, IPageLoader

Method Summary
 void addPageCleanupListener(PageCleanupListener listener)
           
 void addPageDetachListener(PageDetachListener listener)
           
 void addPageRenderListener(PageRenderListener listener)
           
 void attach(IEngine value)
          Attaches the page to the engine.
 void beginResponse(IResponseWriter writer, IRequestCycle cycle)
          Invoked just before rendering of the page is initiated.
 void cleanupPage()
          Invoked when the application terminates (that is, when the HttpSession containing the IEngine is invalidated or times out).
 void detach()
          Invoked on a page when it is no longer needed by the engine, just before is is returned to the pool.
 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.
 java.util.Locale getLocale()
          Returns the Locale of the page.
 java.lang.String getName()
          The logical name is the name given by the application.
 IComponent getNestedComponent(java.lang.String path)
          Returns a particular component from within the page.
 IRequestCycle getRequestCycle()
          Returns the current IRequestCycle.
 IResponseWriter getResponseWriter(java.io.OutputStream out)
          Invoked to create a response writer appropriate to the page (i.e., appropriate to the content of the page).
 java.lang.Object getVisit()
          Returns the visit object for the application; the visit object contains application-specific information.
 void renderPage(IResponseWriter 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 setName(java.lang.String value)
           
 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 immediate services to validate that the user is allowed to visit the page.
 
Methods inherited from interface com.primix.tapestry.IComponent
addAsset, addComponent, addWrapped, finishLoad, getAsset, getAssets, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getPage, getSpecification, renderWrapped, setBinding, setContainer, setId, setPage, setSpecification
 
Methods inherited from interface com.primix.tapestry.IRender
render
 

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.
See Also:
IPageSource.releasePage(IPage)

getEngine

public IEngine getEngine()
Returns the IEngine that 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.

getName

public java.lang.String getName()
The logical name is the name given by the application.

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:
NoSuchComponentException - runtime exception thrown if the path does not identify a component.

attach

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

renderPage

public void renderPage(IResponseWriter writer,
                       IRequestCycle cycle)
                throws RequestCycleException
Invoked to render the entire page. This should only be invoked by IRequestCycle.renderPage(IResponseWriter writer).

The page performs a render using the following steps:


setChangeObserver

public void setChangeObserver(ChangeObserver value)

setName

public void setName(java.lang.String value)

validate

public void validate(IRequestCycle cycle)
              throws RequestCycleException
Method invoked by the page, action and immediate 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 thow a PageRedirectException, to redirect the user to an appropriate part of the system (such as, a login page).


getResponseWriter

public IResponseWriter getResponseWriter(java.io.OutputStream out)
Invoked to create a response writer appropriate to the page (i.e., appropriate to the content of the page). At this time, Tapestry only supports HTML, to an HTMLResponseWriter will be returned, but future enhancements may support XML, WAP, WML, etc., and thus other implementations of IResponseWriter will be returned.

beginResponse

public void beginResponse(IResponseWriter writer,
                          IRequestCycle cycle)
                   throws RequestCycleException
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

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.

setRequestCycle

public void setRequestCycle(IRequestCycle cycle)
Invoked by the IRequestCycle to inform the page of the cycle, as it is loaded.

cleanupPage

public void cleanupPage()
Invoked when the application terminates (that is, when the HttpSession containing the IEngine is invalidated or times out). This gives the page a chance to release any additional resources it may have ... in particular, it allows a page to remove stateful session EJBs it may be using.

Invokes PageCleanupListener.pageCleanup(PageEvent) on any listeners.


getVisit

public java.lang.Object getVisit()
Returns the visit object for the application; the visit object contains application-specific information.

addPageRenderListener

public void addPageRenderListener(PageRenderListener listener)
Since:
1.0.5

addPageDetachListener

public void addPageDetachListener(PageDetachListener listener)
Since:
1.0.5

addPageCleanupListener

public void addPageCleanupListener(PageCleanupListener listener)
Since:
1.0.5