org.apache.tapestry.engine
Class RequestCycle

java.lang.Object
  extended by org.apache.tapestry.engine.RequestCycle
All Implemented Interfaces:
IRequestCycle

public class RequestCycle
extends java.lang.Object
implements IRequestCycle

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

Author:
Howard Lewis Ship

Constructor Summary
RequestCycle()
          Alternate constructor used only for testing purposes.
RequestCycle(IEngine engine, QueryParameterMap parameters, java.lang.String serviceName, IMonitor monitor, RequestCycleEnvironment environment, RequestContext context)
          Standard constructor used to render a response page.
 
Method Summary
 void activate(IPage page)
          Sets the active page for the request.
 void activate(java.lang.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 discardPage(java.lang.String name)
          As of 4.0, just a synonym for forgetPage(String).
 java.lang.String encodeURL(java.lang.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(java.lang.String pageName)
          Forgets any stored changes to the specified page.
 java.lang.String getAbsoluteURL(java.lang.String partialURL)
          Converts a partial URL into an absolute URL.
 java.lang.Object getAttribute(java.lang.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.
 java.lang.Object[] getListenerParameters()
          Returns parameters previously stored by IRequestCycle.setListenerParameters(Object[]).
 IMonitor getMonitor()
           
 java.lang.String getNextActionId()
          Deprecated.  
 IPage getPage()
          Identifies the active page, the page which will ultimately render the response.
 IPage getPage(java.lang.String name)
          Gets the page from the engines's IPageSource.
protected  IPageRecorder getPageRecorder(java.lang.String name)
          Returns the page recorder for the named page.
 java.lang.String getParameter(java.lang.String name)
          Returns a query parameter value, or null if not provided in the request.
 java.lang.String[] getParameters(java.lang.String name)
          Returns all query parameter values for the given name.
 RequestContext getRequestContext()
          Returns the RequestContext.
 IEngineService getService()
          Returns the service which initiated this request cycle.
 java.lang.Object[] getServiceParameters()
          Returns parameters previously stored by IRequestCycle.setServiceParameters(Object[]).
 java.lang.String getUniqueId(java.lang.String baseId)
          Returns the provided string, possibly modified (with an appended suffix) to make it unique.
 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.
 void removeAttribute(java.lang.String name)
          Removes a previously stored attribute, if one with the given name exists.
 void renderPage(IMarkupWriter writer)
          Renders the page by invoking IPage.renderPage(IMarkupWriter, IRequestCycle).
 void rewindForm(IForm form)
          Rewinds an individual form by invoking IForm.rewind(IMarkupWriter, IRequestCycle).
 void rewindPage(java.lang.String targetActionId, IComponent targetComponent)
          Deprecated. To be removed in 4.1 with no replacement.
 void sendRedirect(java.lang.String URL)
          Sends a redirect to the client web browser.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated objects to communicate.
 void setListenerParameters(java.lang.Object[] parameters)
          Invoked by a service to store an array of application-specific parameters.
 void setServiceParameters(java.lang.Object[] serviceParameters)
          Invoked by a service to store an array of application-specific parameters.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RequestCycle

public RequestCycle(IEngine engine,
                    QueryParameterMap parameters,
                    java.lang.String serviceName,
                    IMonitor monitor,
                    RequestCycleEnvironment environment,
                    RequestContext context)
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
monitor - informed of various events during the processing of the request
environment - additional invariant services and objects needed by each RequestCycle instance
context - Part of (partial) compatibility with Tapestry 3.0

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

encodeURL

public java.lang.String encodeURL(java.lang.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

getEngine

public IEngine getEngine()
Description copied from interface: IRequestCycle
Returns the engine which is processing this request cycle.

Specified by:
getEngine in interface IRequestCycle

getAttribute

public java.lang.Object getAttribute(java.lang.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

getMonitor

public IMonitor getMonitor()
Specified by:
getMonitor in interface IRequestCycle

getNextActionId

public java.lang.String getNextActionId()
Deprecated. 

Description copied from interface: IRequestCycle
Returns the next action id. ActionLink ids are used to identify different actions on a page (URLs that are related to dynamic page state).

Specified by:
getNextActionId in interface IRequestCycle
See Also:
IRequestCycle.getUniqueId(String)

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

getPage

public IPage getPage(java.lang.String name)
Gets the page from the engines's IPageSource.

Specified by:
getPage in interface IRequestCycle
See Also:
IPageSource.getPage(IRequestCycle, String, IMonitor)

getPageRecorder

protected IPageRecorder getPageRecorder(java.lang.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.


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

isRewound

public boolean isRewound(IComponent component)
                  throws StaleLinkException
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
Throws:
StaleLinkException

removeAttribute

public void removeAttribute(java.lang.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

renderPage

public void renderPage(IMarkupWriter writer)
Renders the page by invoking IPage.renderPage(IMarkupWriter, IRequestCycle). This clears all attributes.

Specified by:
renderPage in interface IRequestCycle

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
Since:
1.0.2

rewindPage

public void rewindPage(java.lang.String targetActionId,
                       IComponent targetComponent)
Deprecated. To be removed in 4.1 with no replacement.

Rewinds the page by invoking IPage.renderPage(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 ApplicationRuntimeExceptionis thrown.

This clears all attributes.

Specified by:
rewindPage in interface IRequestCycle
See Also:
IAction, ActionLink

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.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

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(java.lang.String name)
As of 4.0, just a synonym for forgetPage(String).

Specified by:
discardPage in interface IRequestCycle
Since:
2.0.2

getServiceParameters

public java.lang.Object[] getServiceParameters()
Description copied from interface: IRequestCycle
Returns parameters previously stored by IRequestCycle.setServiceParameters(Object[]).

Through release 2.1, the return type was String[]. This is an incompatible change in 2.2.

Specified by:
getServiceParameters in interface IRequestCycle
Since:
2.0.3 *

setServiceParameters

public void setServiceParameters(java.lang.Object[] serviceParameters)
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.getServiceParameters().

Through release 2.1, parameters was of type String[]. This is an incompatible change in 2.2.

Specified by:
setServiceParameters in interface IRequestCycle
Since:
2.0.3 *
See Also:
DirectService

getListenerParameters

public java.lang.Object[] getListenerParameters()
Description copied from interface: IRequestCycle
Returns parameters previously stored by IRequestCycle.setListenerParameters(Object[]).

Specified by:
getListenerParameters in interface IRequestCycle
Since:
4.0

setListenerParameters

public void setListenerParameters(java.lang.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
Since:
4.0
See Also:
DirectService

activate

public void activate(java.lang.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
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
Since:
3.0

getParameter

public java.lang.String getParameter(java.lang.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
Since:
4.0

getParameters

public java.lang.String[] getParameters(java.lang.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
Since:
4.0

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
Since:
3.0

getAbsoluteURL

public java.lang.String getAbsoluteURL(java.lang.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
Since:
4.0

forgetPage

public void forgetPage(java.lang.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
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
Since:
4.0

getRequestContext

public RequestContext getRequestContext()
Description copied from interface: IRequestCycle
Returns the RequestContext. This is provided to ease the upgrade from Tapestry 3.0.

Specified by:
getRequestContext in interface IRequestCycle

getUniqueId

public java.lang.String getUniqueId(java.lang.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

sendRedirect

public void sendRedirect(java.lang.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
Since:
4.0