org.apache.tapestry.engine
Class RequestCycle

java.lang.Object
  org.apache.tapestry.engine.RequestCycle

All Implemented Interfaces:

IRequestCycle

public class RequestCycle
extends Object
implements IRequestCycle

Provides the logic for processing a single request cycle. Provides access to the engine and the RequestContext.

Author:

Howard Lewis Ship

Field Summary

protected ResponseBuilder

_responseBuilder

Constructor Summary

RequestCycle()
Alternate constructor used only for testing purposes.

RequestCycle(IEngine engine, QueryParameterMap parameters, String serviceName, RequestCycleEnvironment environment)
Standard constructor used to render a response page.

Method Summary

void	activate(IPage page) Sets the active page for the request.
void	activate(String name) A convienience for invoking IRequestCycle.activate(IPage).
void	cleanup() Called at the end of the request cycle (i.e., after all responses have been sent back to the client), to release all pages loaded during the request cycle.
void	commitPageChanges() Invokes IPageRecorder.commit() on each page recorder loaded during the request cycle (even recorders marked for discard).
void	disableFocus() Sets client side form focus off globally for all forms in this request cycle.
void	discardPage(String name) As of 4.0, just a synonym for forgetPage(String).
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 pageName) 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 IRequestCycle.setListenerParameters(Object[]).
IPage	getPage() Identifies the active page, the page which will ultimately render the response.
IPage	getPage(String name) Gets the page from the engines's IPageSource.
protected IPageRecorder	getPageRecorder(String name) Returns the page recorder for the named page.
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 IRequestCycle.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 page by invoking IPage.renderPage(ResponseBuilder, IRequestCycle).
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) Rewinds an individual form by invoking IForm.rewind(IMarkupWriter, IRequestCycle).
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.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_responseBuilder

protected ResponseBuilder _responseBuilder

Constructor Detail

RequestCycle

public RequestCycle(IEngine engine,
                    QueryParameterMap parameters,
                    String serviceName,
                    RequestCycleEnvironment environment)

Standard constructor used to render a response page.

Parameters:

engine - the current request's engine

parameters - query parameters (possibly the result of ServiceEncoders decoding path information)

serviceName - the name of engine service

environment - additional invariant services and objects needed by each RequestCycle instance

RequestCycle

public RequestCycle()

Alternate constructor used only for testing purposes.

Since:

4.0

Method Detail

cleanup

public void cleanup()

Called at the end of the request cycle (i.e., after all responses have been sent back to the client), to release all pages loaded during the request cycle.

Specified by:

cleanup in interface IRequestCycle

getService

public IEngineService getService()

Description copied from interface: IRequestCycle

Returns the service which initiated this request cycle.

Specified by:

getService in interface IRequestCycle

Returns:

The service associated with current request.

encodeURL

public String encodeURL(String URL)

Description copied from interface: IRequestCycle

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

Specified by:

encodeURL in interface IRequestCycle

Parameters:

URL - The url to encode.

Returns:

The encoded form of the url.

getEngine

public IEngine getEngine()

Description copied from interface: IRequestCycle

Returns the engine which is processing this request cycle.

Specified by:

getEngine in interface IRequestCycle

Returns:

The engine.

getAttribute

public Object getAttribute(String name)

Description copied from interface: IRequestCycle

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

Specified by:

getAttribute in interface IRequestCycle

Parameters:

name - The name of the attribute to retrieve.

Returns:

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

getPage

public IPage getPage()

Description copied from interface: IRequestCycle

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

Specified by:

getPage in interface IRequestCycle

Returns:

The active page.

getPage

public IPage getPage(String name)

Gets the page from the engines's IPageSource.

Specified by:

getPage in interface IRequestCycle

Parameters:

name - The page to get a reference to.

Returns:

The page instance.

See Also:

IPageSource.getPage(IRequestCycle, String)

getPageRecorder

protected IPageRecorder getPageRecorder(String name)

Returns the page recorder for the named page. Starting with Tapestry 4.0, page recorders are shortlived objects managed exclusively by the request cycle.

setResponseBuilder

public void setResponseBuilder(ResponseBuilder builder)

Description copied from interface: IRequestCycle

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)

Specified by:

setResponseBuilder in interface IRequestCycle

Parameters:

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

getResponseBuilder

public ResponseBuilder getResponseBuilder()

Description copied from interface: IRequestCycle

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

Specified by:

getResponseBuilder in interface IRequestCycle

Returns:

The response builder used for this response.

renderStackEmpty

public boolean renderStackEmpty()

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

Specified by:

renderStackEmpty in interface IRequestCycle

Returns:

True, if the current stack is empty.

renderStackPeek

public IRender renderStackPeek()

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

Specified by:

renderStackPeek in interface IRequestCycle

Returns:

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

renderStackPop

public IRender renderStackPop()

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

Specified by:

renderStackPop in interface IRequestCycle

Returns:

The removed IRender, if any.

renderStackPush

public IRender renderStackPush(IRender render)

Pushes the specified render onto the current render stack.

Specified by:

renderStackPush in interface IRequestCycle

Parameters:

render - The IRender object being pushed.

Returns:

The added IRender.

renderStackSearch

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

Specified by:

renderStackSearch in interface IRequestCycle

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

public Iterator renderStackIterator()

Creates a traversable iterator for moving through the stack.

Specified by:

renderStackIterator in interface IRequestCycle

Returns:

An iterator over the current stack.

isRewinding

public boolean isRewinding()

Description copied from interface: IRequestCycle

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.

Specified by:

isRewinding in interface IRequestCycle

Returns:

True if rewinding a form, false otherwise.

isRewound

public boolean isRewound(IComponent component)

Description copied from interface: IRequestCycle

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.

Specified by:

isRewound in interface IRequestCycle

Parameters:

component - The component to check.

Returns:

True if the specified component has been rewound.

removeAttribute

public void removeAttribute(String name)

Description copied from interface: IRequestCycle

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

Specified by:

removeAttribute in interface IRequestCycle

Parameters:

name - The key name of the attribute to remove.

renderPage

public void renderPage(ResponseBuilder builder)

Renders the page by invoking IPage.renderPage(ResponseBuilder, IRequestCycle). This clears all attributes.

Specified by:

renderPage in interface IRequestCycle

Parameters:

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

rewindForm

public void rewindForm(IForm form)

Rewinds an individual form by invoking IForm.rewind(IMarkupWriter, IRequestCycle).

The process is expected to end with a RenderRewoundException. If the entire page is renderred without this exception being thrown, it means that the target action id was not valid, and a ApplicationRuntimeException is thrown.

This clears all attributes.

Specified by:

rewindForm in interface IRequestCycle

Parameters:

form - The form to rewind.

Since:

1.0.2

disableFocus

public void disableFocus()

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

Specified by:

disableFocus in interface IRequestCycle

isFocusDisabled

public boolean isFocusDisabled()

Check for global focus being disabled.

Specified by:

isFocusDisabled in interface IRequestCycle

Returns:

True if focus is disabled, false otherwise.

setAttribute

public void setAttribute(String name,
                         Object value)

Description copied from interface: IRequestCycle

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.

Specified by:

setAttribute in interface IRequestCycle

Parameters:

name - Key name of the attribute to store.

value - Value of the attribute.

commitPageChanges

public void commitPageChanges()

Invokes IPageRecorder.commit() on each page recorder loaded during the request cycle (even recorders marked for discard).

Specified by:

commitPageChanges in interface IRequestCycle

See Also:

IPageRecorder.commit()

discardPage

public void discardPage(String name)

As of 4.0, just a synonym for forgetPage(String).

Since:

2.0.2

getListenerParameters

public Object[] getListenerParameters()

Description copied from interface: IRequestCycle

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

Specified by:

getListenerParameters in interface IRequestCycle

Returns:

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

Since:

4.0

setListenerParameters

public void setListenerParameters(Object[] parameters)

Description copied from interface: IRequestCycle

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 IRequestCycle.getListenerParameters().

Specified by:

setListenerParameters in interface IRequestCycle

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

activate

public void activate(String name)

Description copied from interface: IRequestCycle

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

Specified by:

activate in interface IRequestCycle

Parameters:

name - The name of the page to activate.

Since:

3.0 *

activate

public void activate(IPage page)

Description copied from interface: IRequestCycle

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.

Specified by:

activate in interface IRequestCycle

Parameters:

page - The page to activate.

Since:

3.0

getParameter

public String getParameter(String name)

Description copied from interface: IRequestCycle

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

Specified by:

getParameter in interface IRequestCycle

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

public String[] getParameters(String name)

Description copied from interface: IRequestCycle

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

Specified by:

getParameters in interface IRequestCycle

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

toString

public String toString()

Overrides:

toString in class Object

Since:

3.0

getAbsoluteURL

public String getAbsoluteURL(String partialURL)

Description copied from interface: IRequestCycle

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.

Specified by:

getAbsoluteURL in interface IRequestCycle

Parameters:

partialURL - The url to modify into an absolute url.

Returns:

The converted absolute url representation of the specified partialURL.

Since:

4.0

forgetPage

public void forgetPage(String pageName)

Description copied from interface: IRequestCycle

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.

Specified by:

forgetPage in interface IRequestCycle

Parameters:

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

Since:

4.0

getInfrastructure

public Infrastructure getInfrastructure()

Description copied from interface: IRequestCycle

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

Specified by:

getInfrastructure in interface IRequestCycle

Returns:

The Infrastructure object associated with this request.

Since:

4.0

getUniqueId

public String getUniqueId(String baseId)

Description copied from interface: IRequestCycle

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

Specified by:

getUniqueId in interface IRequestCycle

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

Since:

4.0

peekUniqueId

public String peekUniqueId(String baseId)

Description copied from interface: IRequestCycle

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

Specified by:

peekUniqueId in interface IRequestCycle

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

Since:

4.1

sendRedirect

public void sendRedirect(String URL)

Description copied from interface: IRequestCycle

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.

Specified by:

sendRedirect in interface IRequestCycle

Parameters:

URL - The url to send a client redirect for.

Since:

4.0

encodeIdState

public String encodeIdState()

Description copied from interface: IRequestCycle

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.

Specified by:

encodeIdState in interface IRequestCycle

Returns:

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

initializeIdState

public void initializeIdState(String encodedSeed)

Description copied from interface: IRequestCycle

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

Specified by:

initializeIdState in interface IRequestCycle

Parameters:

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