org.apache.wicket
Class RequestCycle

java.lang.Object
  org.apache.wicket.RequestCycle

Direct Known Subclasses:

WebRequestCycle

public abstract class RequestCycle
extends Object

Represents the processing of a request. It is responsible for instructing the request cycle processor to execute the various steps there are in the handling of a request (resolving the kind of work that needs to be done, handling of events and generating a response), and it holds the intended request target, which is an abstraction for e.g. the processing of a bookmarkable page.

The abstract urlFor() methods are implemented by subclasses of RequestCycle and return encoded page URLs. The URL returned depends on the kind of page being linked to. Pages broadly fall into two categories:

1.

A page that does not yet exist in a user Session may be encoded as a URL that references the not-yet-created page by class name. A set of PageParameters can also be encoded into the URL, and these parameters will be passed to the page constructor if the page later needs to be instantiated. Any page of this type is bookmarkable, and a hint to that effect is given to the user in the URL: /[Application]?bookmarkablePage=[classname]&[param]=[value] [...] Bookmarkable pages must either implement a constructor that takes a PageParameters argument or a default constructor. If a Page has both constructors the constructor with the PageParameters argument will be used. Links to bookmarkable pages are created by calling the urlFor(Class, PageParameters) method, where Class is the page class and PageParameters are the parameters to encode into the URL.

2.

Stateful pages (that have already been requested by a user) will be present in the user's Session and can be referenced securely with a session-relative number: /[Application]?wicket:interface=[pageMapName]:[pageId]: ... Often, the reason to access an existing session page is due to some kind of "postback" (either a link click or a form submit) from a page (possibly accessed with the browser's back button or possibly not). A call to a registered listener is dispatched like so: /[Application]?wicket:interface=[pageMapName]:[pageId]:[componentPath]:[version]:[interfaceName] For example: /[Application]?wicket:interface=:3:signInForm:submit::IFormSubmitListener

URLs for stateful pages (those that already exist in the session map) are created by calling the urlFor(Component, Class) method, where Component is the component being linked to and Class is the interface on the component to call.

For pages falling into the second category, listener interfaces cannot be invoked unless they have first been registered via the static registerSecureInterface() method. This method ensures basic security by restricting the set of interfaces that outsiders can call via GET and POST requests. Each listener interface has a single method which takes only a RequestCycle parameter. Currently, the following classes register the following kinds of listener interfaces:

Class	Interface	Purpose
Form	IFormSubmitListener	Handle form submits
Image	IResourceListener	Respond to image resource requests
Link	ILinkListener	Respond to link clicks
Page	IRedirectListener	Respond to redirects

The redirectToInterceptPage() and continueToOriginalDestination() methods can be used to temporarily redirect a user to some page. This is mainly intended for use in signing in users who have bookmarked a page inside a site that requires the user be authenticated before they can access the page. When it is discovered that the user is not signed in, the user is redirected to the sign-in page with redirectToInterceptPage(). When the user has signed in, they are sent on their way with continueToOriginalDestination(). These methods could also be useful in "interstitial" advertising or other kinds of "intercepts".

Author:

Jonathan Locke, Eelco Hillenius, Igor Vaynberg (ivaynberg)

Field Summary

protected Application	application The application object.
protected IRequestCycleProcessor	processor The processor for this request.
protected Request	request The current request.
protected Response	response The current response.

Constructor Summary

protected

RequestCycle(Application application, Request request, Response response) Constructor.

Method Summary

void	detach() Clean up the request cycle.
static RequestCycle	get() Gets request cycle for calling thread.
Application	getApplication() Gets the application object.
ClientInfo	getClientInfo() Gets the new agent info object for this session.
<T> T	getMetaData(MetaDataKey<T> key) Gets metadata for this request cycle using the given key.
Response	getOriginalResponse() Get the original response the request was created with.
PageParameters	getPageParameters() Any set page parameters.
abstract IRequestCycleProcessor	getProcessor() Gets the processor for delegated request cycle handling.
boolean	getRedirect() Deprecated. Use isRedirect() instead
Request	getRequest() Gets the request.
IRequestTarget	getRequestTarget() Gets the current request target.
Response	getResponse() Gets the response.
Page	getResponsePage() Gets the page that is to be rendered for this request in case the last set request target is of type PageRequestTarget.
Class<? extends Page>	getResponsePageClass() Gets the page class that is to be instantiated and rendered for this request in case the last set request target is of type BookmarkablePageRequestTarget.
Session	getSession() Gets the session.
long	getStartTime()
boolean	isRedirect() Gets whether the page for this request should be redirected.
boolean	isUrlForNewWindowEncoding()
protected void	logRuntimeException(RuntimeException e) Called when an unrecoverable runtime exception during request cycle handling occurred, which will result in displaying a user facing error page.
protected abstract ClientInfo	newClientInfo() Creates a new agent info object based on this request.
protected void	onAfterTargetsDetached() Called when the request cycle object has detached all request targets.
protected void	onBeginRequest() Called when the request cycle object is beginning its response
protected void	onEndRequest() Called when the request cycle object has finished its response
protected void	onExceptionLoop(RuntimeException e) Called when we catch a RuntimeException while already handling another
protected void	onRequestTargetSet(IRequestTarget requestTarget) Called when a request target is set on the request cycle
Page	onRuntimeException(Page page, RuntimeException e) Template method that is called when a runtime exception is thrown, just before the actual handling of the runtime exception.
abstract void	redirectTo(Page page) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
void	request() THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
void	request(Component component) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
void	request(IRequestTarget target) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
protected static void	set(RequestCycle cycle) Sets the request cycle for the calling thread.
void	setAutomaticallyClearFeedbackMessages(boolean automaticallyClearFeedbackMessages) Permit clients like testers to examine feedback messages after processing.
<T> void	setMetaData(MetaDataKey<T> key, T object) Sets the metadata for this request cycle using the given key.
void	setRedirect(boolean redirect) Sets whether the page for this request should be redirected.
void	setRequest(Request request)
void	setRequestTarget(IRequestTarget requestTarget) Sets the request target as the current.
Response	setResponse(Response response) Sets response.
<C extends Page> void	setResponsePage(Class<C> pageClass) Convenience method that sets page class as the response.
<C extends Page> void	setResponsePage(Class<C> pageClass, PageParameters pageParameters) Sets the page class with optionally the page parameters as the render target of this request.
<C extends Page> void	setResponsePage(Class<C> pageClass, PageParameters pageParameters, String pageMapName) Sets the page class with optionally the page parameters and page map name as the render target of this request.
void	setResponsePage(Page page) Sets the page as the render target of this request.
void	setUrlForNewWindowEncoding() Indicate if the next to be encoded url is targeting a new window (ModalWindow, Pop-up, tab).
String	toString()
<C extends Page> CharSequence	urlFor(Class<C> pageClass, PageParameters parameters) Returns a bookmarkable URL that references a given page class using a given set of page parameters.
CharSequence	urlFor(Component component, IBehavior behaviour, RequestListenerInterface listener) Returns a URL that references a given interface on a given behavior of a component.
CharSequence	urlFor(Component component, RequestListenerInterface listener) Returns a URL that references a given interface on a component.
CharSequence	urlFor(Component component, RequestListenerInterface listener, ValueMap params) Returns a URL that references a given interface on a component.
<C extends Page> CharSequence	urlFor(IPageMap pageMap, Class<C> pageClass, PageParameters parameters) Returns a bookmarkable URL that references a given page class using a given set of page parameters.
CharSequence	urlFor(IRequestTarget requestTarget) Returns a URL that references the given request target.
CharSequence	urlFor(Page page) Returns a URL that references the given page.
CharSequence	urlFor(PageReference id) Returns a URL that references the page pointed to by id
CharSequence	urlFor(ResourceReference resourceReference) Returns a URL that references a shared resource through the provided resource reference.
CharSequence	urlFor(ResourceReference resourceReference, ValueMap parameters) Returns a URL that references a shared resource through the provided resource reference.
boolean	wasHandled() INTERNAL.

Methods inherited from class java.lang.Object

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

Field Detail

application

protected final Application application

The application object.

processor

protected final IRequestCycleProcessor processor

The processor for this request.

request

protected Request request

The current request.

response

protected Response response

The current response.

Constructor Detail

RequestCycle

protected RequestCycle(Application application,
                       Request request,
                       Response response)

Constructor. This instance will be set as the current one for this thread.

Parameters:

application - The application

request - The request

response - The response

Method Detail

get

public static RequestCycle get()

Gets request cycle for calling thread.

Returns:

Request cycle for calling thread

set

protected static void set(RequestCycle cycle)

Sets the request cycle for the calling thread. You typically DO NOT NEED to call this method, as the request cycle is set to current for you in the constructor. However, if you have a very special need to set it to something else, you can expose this method.

Parameters:

cycle - The request cycle to set current

getApplication

public final Application getApplication()

Gets the application object.

Returns:

Application interface

getClientInfo

public final ClientInfo getClientInfo()

Gets the new agent info object for this session. This method calls Session.getClientInfo(), which may or may not cache the client info object and typically calls newClientInfo() when no client info object was cached.

Returns:

the agent info object based on this request

getOriginalResponse

public final Response getOriginalResponse()

Get the original response the request was created with. Access may be necessary with the response has temporarily being replaced but your components requires access to lets say the cookie methods of a WebResponse.

Returns:

The original response object.

getPageParameters

public final PageParameters getPageParameters()

Any set page parameters. Typically only available when a request to a bookmarkable page with a Page.Page(PageParameters) constructor was made.

Returns:

the page parameters or null

getProcessor

public abstract IRequestCycleProcessor getProcessor()

Gets the processor for delegated request cycle handling.

Returns:

the processor for delegated request cycle handling

getRedirect

@Deprecated
public final boolean getRedirect()

Deprecated. Use isRedirect() instead

Gets whether the page for this request should be redirected.

Returns:

whether the page for this request should be redirected

getRequest

public final Request getRequest()

Gets the request.

Returns:

Request object

getRequestTarget

public final IRequestTarget getRequestTarget()

Gets the current request target. May be null.

Returns:

the current request target, null if none was set yet.

getResponse

public final Response getResponse()

Gets the response.

Returns:

Response object

getResponsePage

public final Page getResponsePage()

Gets the page that is to be rendered for this request in case the last set request target is of type PageRequestTarget.

Returns:

the page or null

getResponsePageClass

public final Class<? extends Page> getResponsePageClass()

Gets the page class that is to be instantiated and rendered for this request in case the last set request target is of type BookmarkablePageRequestTarget.

Returns:

the page class or null

getSession

public final Session getSession()

Gets the session.

Returns:

Session object

getStartTime

public final long getStartTime()

Returns:

The start time for this request

isRedirect

public boolean isRedirect()

Gets whether the page for this request should be redirected.

Returns:

whether the page for this request should be redirected

onRuntimeException

public Page onRuntimeException(Page page,
                               RuntimeException e)

Template method that is called when a runtime exception is thrown, just before the actual handling of the runtime exception. This is called by AbstractRequestCycleProcessor.respond(RuntimeException, RequestCycle).

Parameters:

page - Any page context where the exception was thrown

e - The exception

Returns:

Any error page to redirect to

redirectTo

public abstract void redirectTo(Page page)

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

Redirects browser to the given page. Don't use this method directly, but use setResponsePage(Page) instead.

Parameters:

page - The page to redirect to

request

public final void request()

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

Responds to a request.

request

public final void request(Component component)

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

Responds to a request to re-render a single component.

NOTE: This method is typically only used for testing purposes.

Parameters:

component - to be re-rendered

request

public final void request(IRequestTarget target)

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

Responds to a request with the request target.

Parameters:

target - request target

setAutomaticallyClearFeedbackMessages

public void setAutomaticallyClearFeedbackMessages(boolean automaticallyClearFeedbackMessages)

Permit clients like testers to examine feedback messages after processing.

Parameters:

automaticallyClearFeedbackMessages - True to automatically detach request cycle at end of processing

setRedirect

public final void setRedirect(boolean redirect)

Sets whether the page for this request should be redirected.

Parameters:

redirect - True if the page for this request cycle should be redirected to rather than directly rendered.

setRequest

public final void setRequest(Request request)

Parameters:

request - The request to set.

setRequestTarget

public final void setRequestTarget(IRequestTarget requestTarget)

Sets the request target as the current.

Parameters:

requestTarget - the request target to set as current

setResponse

public final Response setResponse(Response response)

Sets response.

Parameters:

response - The response

Returns:

the original response

setResponsePage

public final <C extends Page> void setResponsePage(Class<C> pageClass)

Convenience method that sets page class as the response. This will generate a redirect to the page with a bookmarkable url

Type Parameters:

C -

Parameters:

pageClass - The page class to render as a response

setResponsePage

public final <C extends Page> void setResponsePage(Class<C> pageClass,
                                                   PageParameters pageParameters)

Sets the page class with optionally the page parameters as the render target of this request.

Type Parameters:

C -

Parameters:

pageClass - The page class to render as a response

pageParameters - The page parameters that gets appended to the bookmarkable url,

setResponsePage

public final <C extends Page> void setResponsePage(Class<C> pageClass,
                                                   PageParameters pageParameters,
                                                   String pageMapName)

Sets the page class with optionally the page parameters and page map name as the render target of this request.

Type Parameters:

C -

Parameters:

pageClass - The page class to render as a response

pageParameters - The page parameters that gets appended to the bookmarkable url,

pageMapName - The Pagemap in which the response page should be created

setResponsePage

public final void setResponsePage(Page page)

Sets the page as the render target of this request.

Parameters:

page - The page to render as a response

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

isUrlForNewWindowEncoding

public final boolean isUrlForNewWindowEncoding()

Returns:

true if the next to be encoded url is targeting a new window (ModalWindow, Pop-up, tab).

setUrlForNewWindowEncoding

public final void setUrlForNewWindowEncoding()

Indicate if the next to be encoded url is targeting a new window (ModalWindow, Pop-up, tab). This temporary flag is specifically needed for Portlet-support as then such a page needs a special target (Resource) url. After each urlFor call, this flag is reset to false.

urlFor

public final <C extends Page> CharSequence urlFor(Class<C> pageClass,
                                                  PageParameters parameters)

Returns a bookmarkable URL that references a given page class using a given set of page parameters. Since the URL which is returned contains all information necessary to instantiate and render the page, it can be stored in a user's browser as a stable bookmark.

Type Parameters:

C -

Parameters:

pageClass - Class of page

parameters - Parameters to page

Returns:

Bookmarkable URL to page

urlFor

public final CharSequence urlFor(Component component,
                                 IBehavior behaviour,
                                 RequestListenerInterface listener)

Returns a URL that references a given interface on a given behavior of a component. When the URL is requested from the server at a later time, the interface on the behavior will be called. A URL returned by this method will not be stable across sessions and cannot be bookmarked by a user.

Parameters:

component - The component to reference

behaviour - The behavior to reference

listener - The listener interface on the component

Returns:

A URL that encodes a page, component, behavior and interface to call

urlFor

public final CharSequence urlFor(Component component,
                                 RequestListenerInterface listener,
                                 ValueMap params)

Returns a URL that references a given interface on a component. When the URL is requested from the server at a later time, the interface will be called. A URL returned by this method will not be stable across sessions and cannot be bookmarked by a user.

Parameters:

component - The component to reference

listener - The listener interface on the component

params - Additional parameters to pass to the page

Returns:

A URL that encodes a page, component and interface to call

urlFor

public final CharSequence urlFor(Component component,
                                 RequestListenerInterface listener)

Returns a URL that references a given interface on a component. When the URL is requested from the server at a later time, the interface will be called. A URL returned by this method will not be stable across sessions and cannot be bookmarked by a user.

Parameters:

component - The component to reference

listener - The listener interface on the component

Returns:

A URL that encodes a page, component and interface to call

urlFor

public final <C extends Page> CharSequence urlFor(IPageMap pageMap,
                                                  Class<C> pageClass,
                                                  PageParameters parameters)

Returns a bookmarkable URL that references a given page class using a given set of page parameters. Since the URL which is returned contains all information necessary to instantiate and render the page, it can be stored in a user's browser as a stable bookmark.

Type Parameters:

C -

Parameters:

pageMap - Pagemap to use. If null is passed the default page map will be used

pageClass - Class of page

parameters - Parameters to page

Returns:

Bookmarkable URL to page

urlFor

public final CharSequence urlFor(IRequestTarget requestTarget)

Returns a URL that references the given request target.

Parameters:

requestTarget - the request target to reference

Returns:

a URL that references the given request target

urlFor

public final CharSequence urlFor(Page page)

Returns a URL that references the given page. It also touches the page in the session so that it is put in the front of the page stack. Use this method only if you plan to use it the next request.

Parameters:

page - The page

Returns:

The url pointing to the provided page

urlFor

public final CharSequence urlFor(PageReference id)

Returns a URL that references the page pointed to by id

Parameters:

id - page id

Returns:

url pointing to the page

See Also:

for more details

urlFor

public final CharSequence urlFor(ResourceReference resourceReference)

Returns a URL that references a shared resource through the provided resource reference.

Parameters:

resourceReference - The resource reference where a url must be generated for.

Returns:

The url for the shared resource

urlFor

public final CharSequence urlFor(ResourceReference resourceReference,
                                 ValueMap parameters)

Returns a URL that references a shared resource through the provided resource reference.

Parameters:

resourceReference - The resource reference where a url must be generated for.

parameters - The parameters to pass to the resource.

Returns:

The url for the shared resource

detach

public void detach()

Clean up the request cycle. Please note that you (the user of Wicket) will probably never have a need to call detach() yourself. It is used Wicket internally only. But you may subclass RequestCycle in order to execute additional code during detach. Do not forget to call super.detach() in or subclass.

onExceptionLoop

protected void onExceptionLoop(RuntimeException e)

Called when we catch a RuntimeException while already handling another

wasHandled

public boolean wasHandled()

INTERNAL. THIS METHOD IS NOT PART OF PUBLIC WICKET API. Do not call it. Returns whether wicket handled this request or not (i.e. when no request target was found).

Returns:

true if wicket handled this request, false otherwise

logRuntimeException

protected void logRuntimeException(RuntimeException e)

Called when an unrecoverable runtime exception during request cycle handling occurred, which will result in displaying a user facing error page. Clients can override this method in case they want to customize logging. NOT called for page expired exceptions.

Parameters:

e - the runtime exception

newClientInfo

protected abstract ClientInfo newClientInfo()

Creates a new agent info object based on this request. Typically, this method is called once by the session and the returned object will be cached in the session after that call; we can expect the client to stay the same for the whole session, and implementations of newClientInfo() might be relatively expensive.

Returns:

the agent info object based on this request

onBeginRequest

protected void onBeginRequest()

Called when the request cycle object is beginning its response

onAfterTargetsDetached

protected void onAfterTargetsDetached()

Called when the request cycle object has detached all request targets.

onEndRequest

protected void onEndRequest()

Called when the request cycle object has finished its response

onRequestTargetSet

protected void onRequestTargetSet(IRequestTarget requestTarget)

Called when a request target is set on the request cycle

Parameters:

requestTarget -

setMetaData

public final <T> void setMetaData(MetaDataKey<T> key,
                                  T object)

Sets the metadata for this request cycle using the given key. If the metadata object is not of the correct type for the metadata key, an IllegalArgumentException will be thrown. For information on creating MetaDataKeys, see MetaDataKey.

Type Parameters:

T -

Parameters:

key - The singleton key for the metadata

object - The metadata object

Throws:

IllegalArgumentException

See Also:

MetaDataKey

getMetaData

public final <T> T getMetaData(MetaDataKey<T> key)

Gets metadata for this request cycle using the given key.

Type Parameters:

T - The type of the metadata

Parameters:

key - The key for the data

Returns:

The metadata or null if no metadata was found for the given key

See Also:

MetaDataKey