org.apache.tapestry
Interface IRequestCycle

All Known Implementing Classes:

RequestCycle

public interface IRequestCycle

Controller object that manages a single request cycle. A request cycle is one 'hit' on the web server. In the case of a Tapestry application, this will involve:

• Responding to the URL by finding an IEngineServiceobject
• Determining the result page
• Renderring the result page
• Releasing any resources

Mixed in with this is:

• Exception handling
• Loading of pages and templates from resources
• Tracking changes to page properties, and restoring pages to prior states
• Pooling of page objects

A request cycle is broken up into two phases. The rewind phase is optional, as it tied to Form components. In the rewind phase, a previous page render is redone (discarding output) until a specific component of the page is reached. This rewinding ensures that the page is restored to the exact state it had when the URL for the request cycle was generated, taking into account the dynamic nature of the page (ForBean, Conditional, etc.). Once this component is reached, it can notify its IActionListener. The listener has the ability to update the state of any pages and select a new result page.

Following the rewind phase is the render phase. During the render phase, a page is actually rendered and output sent to the client web browser.

Author:

Howard Lewis Ship

Method Summary

void	activate(IPage page) Sets the active page for the request.
void	activate(String name) A convienience for invoking activate(IPage).
void	cleanup() Invoked after the request cycle is no longer needed, to release any resources it may have.
void	commitPageChanges() Invoked just before rendering the response page to get all page recorderstouched in this request cycle to commit their changes (save them to persistant storage).
void	disableFocus() Sets client side form focus off globally for all forms in this request cycle.
String	encodeIdState() Encodes the current state of all allocated component ids (using IdAllocator) to a String value that can be embedded in URLs or forms.
String	encodeURL(String URL) Passes the String through HttpServletResponse.encodeURL(java.lang.String), which ensures that the session id is encoded in the URL (if necessary).
void	forgetPage(String name) Forgets any stored changes to the specified page.
String	getAbsoluteURL(String partialURL) Converts a partial URL into an absolute URL.
Object	getAttribute(String name) Retrieves a previously stored attribute, returning null if not found.
IEngine	getEngine() Returns the engine which is processing this request cycle.
Infrastructure	getInfrastructure() Returns the central Infrastructure object used to manage the processing of the request.
Object[]	getListenerParameters() Returns parameters previously stored by setListenerParameters(Object[]).
IPage	getPage() Identifies the active page, the page which will ultimately render the response.
IPage	getPage(String name) Returns the page with the given name.
String	getParameter(String name) Returns a query parameter value, or null if not provided in the request.
String[]	getParameters(String name) Returns all query parameter values for the given name.
ResponseBuilder	getResponseBuilder() Entry point for getting the response builder used to build this response.
IEngineService	getService() Returns the service which initiated this request cycle.
String	getUniqueId(String baseId) Returns the provided string, possibly modified (with an appended suffix) to make it unique.
void	initializeIdState(String encodedSeed) Used in conjunction with encodeIdState() to re-initialize the internal id allocation state of a request during a form rewind.
boolean	isFocusDisabled() Check for global focus being disabled.
boolean	isRewinding() Returns true if the context is being used to rewind a prior state of the page.
boolean	isRewound(IComponent component) Checks to see if the current action id matches the target action id.
String	peekUniqueId(String baseId) Returns what will be the next unique id generated based on the given input, but doesn't store the result.
void	removeAttribute(String name) Removes a previously stored attribute, if one with the given name exists.
void	renderPage(ResponseBuilder builder) Renders the given page.
boolean	renderStackEmpty() Tests if the render component chain is empty, meaning no components have been loaded onto the stack yet.
Iterator	renderStackIterator() Creates a traversable iterator for moving through the stack.
IRender	renderStackPeek() Looks at the object at the top of the render stack without removing the IRender from the stack.
IRender	renderStackPop() Removes the IRender at the top of the stack, if any.
IRender	renderStackPush(IRender render) Pushes the specified render onto the current render stack.
int	renderStackSearch(IRender render) Returns the 1-based position where an object is on this stack.
void	rewindForm(IForm form) Used by formsto perform a partial rewind so as to respond to the form submission (using the direct service).
void	sendRedirect(String URL) Sends a redirect to the client web browser.
void	setAttribute(String name, Object value) Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated objects to communicate.
void	setListenerParameters(Object[] parameters) Invoked by a service to store an array of application-specific parameters.
void	setResponseBuilder(ResponseBuilder builder) Sets the ResponseBuilder to use for this response, don't try setting this unless you're very sure you know what you are doing as this isn't the only way that it is used.

Method Detail

cleanup

void cleanup()

Invoked after the request cycle is no longer needed, to release any resources it may have. This includes releasing any loaded pages back to the page source.

encodeURL

String encodeURL(String URL)

Passes the String through HttpServletResponse.encodeURL(java.lang.String), which ensures that the session id is encoded in the URL (if necessary).

Parameters:

URL - The url to encode.

Returns:

The encoded form of the url.

getEngine

IEngine getEngine()

Returns the engine which is processing this request cycle.

Returns:

The engine.

getAttribute

Object getAttribute(String name)

Retrieves a previously stored attribute, returning null if not found. Attributes allow components to locate each other; primarily they allow a wrapped component to locate a component which wraps it. Attributes are cleared at the end of the render (or rewind).

Parameters:

name - The name of the attribute to retrieve.

Returns:

The matching attribute with the specified name, or null if none found.

getPage

IPage getPage()

Identifies the active page, the page which will ultimately render the response.

Returns:

The active page.

getPage

IPage getPage(String name)

Returns the page with the given name. If the page has been previously loaded in the current request cycle, that page is returned. Otherwise, the engine's page loader is used to load the page.

Parameters:

name - The page to get a reference to.

Returns:

The page instance.

Throws:

PageNotFoundException - if the page does not exist.

See Also:

IPageSource.getPage(IRequestCycle, String)

isRewinding

boolean isRewinding()

Returns true if the context is being used to rewind a prior state of the page. This is only true when there is a target action id.

Returns:

True if rewinding a form, false otherwise.

isRewound

boolean isRewound(IComponent component)

Checks to see if the current action id matches the target action id. Returns true only if they match. Returns false if there is no target action id (that is, during page rendering).

If theres a match on action id, then the component is compared against the target component. If there's a mismatch then a StaleLinkExceptionis thrown.

Parameters:

component - The component to check.

Returns:

True if the specified component has been rewound.

setResponseBuilder

void setResponseBuilder(ResponseBuilder builder)

Sets the ResponseBuilder to use for this response, don't try setting this unless you're very sure you know what you are doing as this isn't the only way that it is used. (ie replacing this builder won't necessarily override another builder being used already)

Parameters:

builder - The response builder that may be used by components to help with delegate/sub component rendering.

getResponseBuilder

ResponseBuilder getResponseBuilder()

Entry point for getting the response builder used to build this response.

Returns:

The response builder used for this response.

renderStackEmpty

boolean renderStackEmpty()

Tests if the render component chain is empty, meaning no components have been loaded onto the stack yet.

Returns:

True, if the current stack is empty.

renderStackPeek

IRender renderStackPeek()

Looks at the object at the top of the render stack without removing the IRender from the stack.

Returns:

The last (parent) item added to the current render stack.

renderStackPop

IRender renderStackPop()

Removes the IRender at the top of the stack, if any.

Returns:

The removed IRender, if any.

renderStackPush

IRender renderStackPush(IRender render)

Pushes the specified render onto the current render stack.

Parameters:

render - The IRender object being pushed.

Returns:

The added IRender.

renderStackSearch

int renderStackSearch(IRender render)

Returns the 1-based position where an object is on this stack. If the object o occurs as an item in this stack, this method returns the distance from the top of the stack of the occurrence nearest the top of the stack; the topmost item on the stack is considered to be at distance 1. The equals method is used to compare o to the items in this stack.

Parameters:

render - The IRender being searched for.

Returns:

the 1-based position from the top of the stack where the object is located; the return value -1 indicates that the object is not on the stack.

renderStackIterator

Iterator renderStackIterator()

Creates a traversable iterator for moving through the stack.

Returns:

An iterator over the current stack.

removeAttribute

void removeAttribute(String name)

Removes a previously stored attribute, if one with the given name exists.

Parameters:

name - The key name of the attribute to remove.

renderPage

void renderPage(ResponseBuilder builder)

Renders the given page. Applications should always use this method to render the page, rather than directly invoking IRender.render(IMarkupWriter, IRequestCycle)since the request cycle must perform some setup before rendering.

Parameters:

builder - Renders the currently active page using the specified builder.

setAttribute

void setAttribute(String name,
                  Object value)

Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated objects to communicate. This is similar to HttpServletRequest.setAttribute(), except that values can be changed and removed as well.

This is used by components to locate each other. A component, such as Body, will write itself under a well-known name into the request cycle, and components it wraps can locate it by that name.

Attributes are cleared at the end of each render or rewind phase.

Parameters:

name - Key name of the attribute to store.

value - Value of the attribute.

commitPageChanges

void commitPageChanges()

Invoked just before rendering the response page to get all page recorderstouched in this request cycle to commit their changes (save them to persistant storage).

See Also:

IPageRecorder.commit()

getService

IEngineService getService()

Returns the service which initiated this request cycle.

Returns:

The service associated with current request.

Since:

1.0.1

rewindForm

void rewindForm(IForm form)

Used by formsto perform a partial rewind so as to respond to the form submission (using the direct service).

Parameters:

form - The form to rewind.

Since:

1.0.2

disableFocus

void disableFocus()

Sets client side form focus off globally for all forms in this request cycle.

isFocusDisabled

boolean isFocusDisabled()

Check for global focus being disabled.

Returns:

True if focus is disabled, false otherwise.

setListenerParameters

void setListenerParameters(Object[] parameters)

Invoked by a service to store an array of application-specific parameters. These can later be retrieved (typically, by an application-specific listener method) by invoking getListenerParameters().

Parameters:

parameters - The parameters to set which will be available as method parameters to any listeners invoked in this request.

Since:

4.0

See Also:

DirectService

getListenerParameters

Object[] getListenerParameters()

Returns parameters previously stored by setListenerParameters(Object[]).

Returns:

The current set of bound listener parameters for the current service.

Since:

4.0

activate

void activate(String name)

A convienience for invoking activate(IPage). Invokes getPage(String)to get an instance of the named page.

Parameters:

name - The name of the page to activate.

Since:

3.0

activate

void activate(IPage page)

Sets the active page for the request. The active page is the page which will ultimately render the response. The activate page is typically set by the service. Frequently, the active page is changed (from a listener method) to choose an alternate page to render the response).

IPage.validate(IRequestCycle)is invoked on the page to be activated. PageRedirectExceptionis caught and the page specified in the exception will be the active page instead (that is, a page may "pass the baton" to another page using the exception). The new page is also validated. This continues until a page does not throw PageRedirectException.

Validation loops can occur, where page A redirects to page B and then page B redirects back to page A (possibly with intermediate steps). This is detected and results in an ApplicationRuntimeException.

Parameters:

page - The page to activate.

Since:

3.0

getParameter

String getParameter(String name)

Returns a query parameter value, or null if not provided in the request. If multiple values are provided, returns the first value.

Parameters:

name - The name of the request parameter to retrieve.

Returns:

The value matching the specified parameter name, or null if none found.

Since:

4.0

getParameters

String[] getParameters(String name)

Returns all query parameter values for the given name. Returns null if no values were provided.

Parameters:

name - The name of the parameters to retrieve.

Returns:

The matching multi value array for the specified name, or null if none found.

Since:

4.0

getAbsoluteURL

String getAbsoluteURL(String partialURL)

Converts a partial URL into an absolute URL. Prefixes the provided URL with servlet context path (if any), then expands it to a full URL by prepending with the scheme, server and port (determined from the current request.

Parameters:

partialURL - The url to modify into an absolute url.

Returns:

The converted absolute url representation of the specified partialURL.

Since:

4.0

forgetPage

void forgetPage(String name)

Forgets any stored changes to the specified page. If the page has already been loaded (and rolled back) then the loaded page instance is not affected; if the page is only loaded subsequently, the page instance will not see any persisted property changes.

Parameters:

name - The name of the page instance to throw all persistent properties away for.

Since:

4.0

getInfrastructure

Infrastructure getInfrastructure()

Returns the central Infrastructure object used to manage the processing of the request.

Returns:

The Infrastructure object associated with this request.

Since:

4.0

getUniqueId

String getUniqueId(String baseId)

Returns the provided string, possibly modified (with an appended suffix) to make it unique.

Parameters:

baseId - the base id from which to generate the unique string.

Returns:

baseId, or baseId with a suffix appended (if the method has been previously invoked with the same baseId).

peekUniqueId

String peekUniqueId(String baseId)

Returns what will be the next unique id generated based on the given input, but doesn't store the result.

Parameters:

baseId - the base id from which to generate the unique string.

Returns:

baseId, or baseId with a suffix appended (if the method has been previously invoked with the same baseId).

sendRedirect

void sendRedirect(String URL)

Sends a redirect to the client web browser. This is currently a convinience for constructing and throwing a RedirectException, but may change in a later release.

Parameters:

URL - The url to send a client redirect for.

Throws:

RedirectException

Since:

4.0

encodeIdState

String encodeIdState()

Encodes the current state of all allocated component ids (using IdAllocator) to a String value that can be embedded in URLs or forms.

This method is used primarily by the Form component to encode the state of the current ids allocated so as to maintain consistent state during rewind - especially in cases where multiple form components are rendered in a page.

Returns:

The encoded state, which can be used to re-initialize a request to the same ID state by invoking initializeIdState(String).

initializeIdState

void initializeIdState(String encodedSeed)

Used in conjunction with encodeIdState() to re-initialize the internal id allocation state of a request during a form rewind.

Parameters:

encodedSeed - The value returned from a previous invocation of encodeIdState() .