org.apache.tapestry.internal.structure
Interface Page

All Known Implementing Classes:

PageImpl

public interface Page

Represents a unique page within the application. Pages are part of the internal structure of a Tapestry application; end developers who refer to "page" are really referring to the root component of the actual page.

One of the most important aspects of a Page is that it does not have to be coded in a thread-safe manner. Pages are always accessed within a single thread, associated with a single incoming request.

The Page object is never visible to end-user code. The page also exists to provide a kind of service to components embedded (directly or indirectly) within the page.

Method Summary

void	addLifecycleListener(PageLifecycleListener listener) Adds a listener that is notified of large scale page events.
void	attached() Invoked to inform the page that it is attached to the current request.
Link	createActionLink(String nestedId, String eventType, boolean forForm, Object... context) Creates a link that will trigger behavior in a component within the page.
Link	createPageLink(String pageName, boolean override, Object... context) Creates a link to the named page.
void	decrementDirtyCount() Called as a component finishes rendering itself.
boolean	detached() Invoked to inform the page that it is being detached from the current request.
void	discardPersistentFieldChanges() Discards all persistent field changes for the page containing the component.
ComponentPageElement	getComponentElementByNestedId(String nestedId) Retrieves a component element by its nested id (a sequence of simple ids, separated by dots).
Object	getFieldChange(String nestedId, String fieldName) Gets a change for a field within the component.
Locale	getLocale() The locale for which the page is localized.
org.slf4j.Logger	getLogger() Returns the logger of the root component element.
String	getLogicalName() Returns the short, logical name for the page.
Component	getRootComponent() The root component of the page.
ComponentPageElement	getRootElement() The root component of the page.
void	incrementDirtyCount() Called as a component initially starts to render itself.
void	loaded() Inform the page that it is now completely loaded.
void	persistFieldChange(ComponentResources resources, String fieldName, Object newValue) Posts a change to a persistent field.
void	setRootElement(ComponentPageElement component) Invoked during page construction time to connect the page's root component to the page instance.

Method Detail

getLogicalName

String getLogicalName()

Returns the short, logical name for the page. This is the page name as it might included in an action or page render URL (though it will be converted to lower case when it is included).

getLocale

Locale getLocale()

The locale for which the page is localized. This is set when the page is created and does not change.

setRootElement

void setRootElement(ComponentPageElement component)

Invoked during page construction time to connect the page's root component to the page instance.

getRootElement

ComponentPageElement getRootElement()

The root component of the page. This is the wrapper around the end developer's view of the page.

getRootComponent

Component getRootComponent()

The root component of the page. A convenience over invoking getRootElement().getComponent().

detached

boolean detached()

Invoked to inform the page that it is being detached from the current request. This occurs just before the page is returned to the page pool.

A page may be clean or dirty. A page is dirty if its dirty count is greater than zero (meaning that, during the render of the page, some components did not fully render), or if any of its listeners throw an exception from containingPageDidDetech().

The page pool should discard pages that are dirty, rather than store them into the pool.

Returns:

true if the page is "dirty", false otherwise

See Also:

PageLifecycleListener.containingPageDidDetach()

attached

void attached()

Invoked to inform the page that it is attached to the current request. This occurs when a page is first referenced within a request. If the page was created from scratch for this request, the call to loaded() will preceded the call to attached().

loaded

void loaded()

Inform the page that it is now completely loaded.

See Also:

PageLifecycleListener.containingPageDidLoad()

addLifecycleListener

void addLifecycleListener(PageLifecycleListener listener)

Adds a listener that is notified of large scale page events.

getLogger

org.slf4j.Logger getLogger()

Returns the logger of the root component element. Any logging about page construction or activity should be sent to this logger.

getComponentElementByNestedId

ComponentPageElement getComponentElementByNestedId(String nestedId)

Retrieves a component element by its nested id (a sequence of simple ids, separated by dots). The individual names in the nested id are matched without regards to case. A nested id of '' (the empty string) returns the root element of the page.

Throws:

IllegalArgumentException - if the nestedId does not correspond to a component

createActionLink

Link createActionLink(String nestedId,
                      String eventType,
                      boolean forForm,
                      Object... context)

Creates a link that will trigger behavior in a component within the page.

See Also:

ComponentResources.createActionLink(String, boolean, Object[])

createPageLink

Link createPageLink(String pageName,
                    boolean override,
                    Object... context)

Creates a link to the named page.

See Also:

ComponentResources.createPageLink(String, boolean, Object[])

persistFieldChange

void persistFieldChange(ComponentResources resources,
                        String fieldName,
                        Object newValue)

Posts a change to a persistent field.

Parameters:

resources - the component resources for the component or mixin containing the field whose value changed

fieldName - the name of the field

newValue - the new value for the field

getFieldChange

Object getFieldChange(String nestedId,
                      String fieldName)

Gets a change for a field within the component.

Parameters:

nestedId - the nested component id of the component containing the field

fieldName - the name of the persistent field

Returns:

the value, or null if no value is stored

incrementDirtyCount

void incrementDirtyCount()

Called as a component initially starts to render itself. This is used to check for the cases where a component causes a runtime exception that aborts the render early, leaving the page in an invalid state.

decrementDirtyCount

void decrementDirtyCount()

Called as a component finishes rendering itself.

discardPersistentFieldChanges

void discardPersistentFieldChanges()

Discards all persistent field changes for the page containing the component. Changes are eliminated from persistent storage (such as the Session) which will take effect in the next request (the attached page instance is not affected).