org.apache.tapestry.request
Class RequestContext

java.lang.Object
  org.apache.tapestry.request.RequestContext

All Implemented Interfaces:

IRender

public class RequestContext
extends Object
implements IRender

This class encapsulates all the relevant data for one request cycle of an ApplicationServlet. This includes:

• HttpServletRequest
• HttpServletResponse
• HttpSession
• HttpServlet

It also provides methods for:

• Retrieving the request parameters (even if a file upload is involved)
• Getting, setting and removing request attributes
• Forwarding requests
• Redirecting requests
• Getting and setting Cookies
• Intepreting the request path info
• Writing an HTML description of the RequestContext (for debugging).

If some cases, it is necesary to provide an implementation of IRequestDecoder (often, due to a firewall). If the application specifification provides an extension named org.apache.tapestry.request-decoder then it will be used, instead of a default decoder.

This class is not a component, but does implement IRender. When asked to render (perhaps as the delegate of a Delegator component} it simply invokes write(IMarkupWriter) to display all debugging output.

This class is derived from the original class com.primix.servlet.RequestContext, part of the ServletUtils framework available from The Giant Java Tree.

Version:

$Id: RequestContext.java 243791 2004-02-19 17:38:13Z hlship $

Author:

Howard Lewis Ship

Constructor Summary

RequestContext(ApplicationServlet servlet, HttpServletRequest request, HttpServletResponse response)
Creates a RequestContext from its components.

Method Summary

void	addCookie(Cookie cookie) Adds a Cookie to the response.
void	addCookie(String name, String value) Adds a simple Cookie.
void	cleanup() Invoked at the end of the request cycle to cleanup and temporary resources.
HttpSession	createSession() Like getSession(), but forces the creation of the HttpSession, if necessary.
String	getAbsoluteURL(String URI) Builds an absolute URL from the given URI, using the HttpServletRequest as the source for scheme, server name and port.
String	getAbsoluteURL(String URI, String scheme, String server, int port) Does some easy checks to turn a path (or URI) into an absolute URL.
Object	getAttribute(String name) Convienience method for getting a HttpServletRequest attribute.
Cookie	getCookie(String name) Gets a named Cookie.
String	getCookieValue(String name) Reads the named Cookie and returns its value (if it exists), or null if it does not exist.
String	getParameter(String name) Returns the named parameter from the HttpServletRequest.
String[]	getParameters(String name) For parameters that are, or are possibly, multi-valued, this method returns all the values as an array of Strings.
HttpServletRequest	getRequest() Returns the request which initiated the current request cycle.
String	getRequestURI() Returns the actual request URI, possibly decoded from the request.
HttpServletResponse	getResponse()
String	getScheme() Returns the actual scheme, possibly decoded from the request.
String	getServerName() Returns the actual server name, possibly decoded from the request.
int	getServerPort() Returns the actual server port, possibly decoded from the request.
ApplicationServlet	getServlet()
HttpSession	getSession() Returns the HttpSession, if necessary, invoking HttpServletRequest.getSession(boolean).
IUploadFile	getUploadFile(String name) Returns the named IUploadFile, if it exists, or null if it doesn't.
protected IMultipartDecoder	obtainMultipartDecoder(ApplicationServlet servlet, HttpServletRequest request) Invoked from the constructor to create a DefaultMultipartDecoder instance.
void	redirect(String path) Invokes HttpServletResponse.sendRedirect(String), but massages path, supplying missing elements to make it an absolute URL (i.e., specifying scheme, server, port, etc.).
void	render(IMarkupWriter writer, IRequestCycle cycle) Invokes write(IMarkupWriter), which is used for debugging.
void	setDecoder(IMultipartDecoder decoder) Sets the multipart decoder to be used for the request.
void	write(IMarkupWriter writer) Writes the state of the context to the writer, typically for inclusion in a HTML page returned to the user.

Methods inherited from class java.lang.Object

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

Constructor Detail

RequestContext

public RequestContext(ApplicationServlet servlet,
                      HttpServletRequest request,
                      HttpServletResponse response)
               throws IOException

Creates a RequestContext from its components.

Throws:

IOException

Method Detail

obtainMultipartDecoder

protected IMultipartDecoder obtainMultipartDecoder(ApplicationServlet servlet,
                                                   HttpServletRequest request)
                                            throws IOException

Invoked from the constructor to create a DefaultMultipartDecoder instance. Applications with specific upload needs may need to override this to provide a subclass instance instead. The caller will invoke IMultipartDecoder.decode(HttpServletRequest) on the returned object.

This implementation checks for application extension Tapestry.MULTIPART_DECODER_EXTENSION_NAME. If that is not defined, a shared instance of DefaultMultipartDecoder is returned.

Throws:

IOException

Since:

3.0

See Also:

ApplicationServlet.createRequestContext(HttpServletRequest, HttpServletResponse)

addCookie

public void addCookie(String name,
                      String value)

Adds a simple Cookie. To set a Cookie with attributes, use addCookie(Cookie).

addCookie

public void addCookie(Cookie cookie)

Adds a Cookie to the response. Once added, the Cookie will also be available to getCookie(String) method.

Cookies should only be added before invoking ServletResponse.getWriter()..

getScheme

public String getScheme()

Returns the actual scheme, possibly decoded from the request.

Since:

2.2

See Also:

IRequestDecoder, ServletRequest.getScheme()

getServerName

public String getServerName()

Returns the actual server name, possibly decoded from the request.

Since:

2.2

See Also:

IRequestDecoder, ServletRequest.getServerName()

getServerPort

public int getServerPort()

Returns the actual server port, possibly decoded from the request.

Since:

2.2

See Also:

IRequestDecoder, ServletRequest.getServerPort()

getRequestURI

public String getRequestURI()

Returns the actual request URI, possibly decoded from the request.

Since:

2.2

See Also:

IRequestDecoder, HttpServletRequest.getRequestURI()

getAbsoluteURL

public String getAbsoluteURL(String URI)

Builds an absolute URL from the given URI, using the HttpServletRequest as the source for scheme, server name and port.

See Also:

getAbsoluteURL(String, String, String, int)

getAbsoluteURL

public String getAbsoluteURL(String URI,
                             String scheme,
                             String server,
                             int port)

Does some easy checks to turn a path (or URI) into an absolute URL. We assume

• The presense of a colon means the path is complete already (any other colons in the URI portion should have been converted to %3A).
• A leading pair of forward slashes means the path is simply missing the scheme.
• Otherwise, we assemble the scheme, server, port (if non-zero) and the URI as given.

getCookie

public Cookie getCookie(String name)

Gets a named Cookie.

Parameters:

name - The name of the Cookie.

Returns:

The Cookie, or null if no Cookie with that name exists.

getCookieValue

public String getCookieValue(String name)

Reads the named Cookie and returns its value (if it exists), or null if it does not exist.

getParameter

public String getParameter(String name)

Returns the named parameter from the HttpServletRequest.

Use getParameters(String) for parameters that may include multiple values.

This is the preferred way to obtain parameter values (rather than obtaining the HttpServletRequest itself). For form/multipart-data encoded requests, this method will still work.

getAttribute

public Object getAttribute(String name)

Convienience method for getting a HttpServletRequest attribute.

Since:

2.3

getParameters

public String[] getParameters(String name)

For parameters that are, or are possibly, multi-valued, this method returns all the values as an array of Strings.

See Also:

getParameter(String)

getUploadFile

public IUploadFile getUploadFile(String name)

Returns the named IUploadFile, if it exists, or null if it doesn't. Uploads require an encoding of multipart/form-data (this is specified in the form's enctype attribute). If the encoding type is not so, or if no upload matches the name, then this method returns null.

cleanup

public void cleanup()

Invoked at the end of the request cycle to cleanup and temporary resources. This is chained to the DefaultMultipartDecoder, if there is one.

Since:

2.0.1

getRequest

public HttpServletRequest getRequest()

Returns the request which initiated the current request cycle. Note that the methods getParameter(String) and getParameters(String) should be used, rather than obtaining parameters directly from the request (since the RequestContext handles the differences between normal and multipart/form requests).

getResponse

public HttpServletResponse getResponse()

getServlet

public ApplicationServlet getServlet()

getSession

public HttpSession getSession()

Returns the HttpSession, if necessary, invoking HttpServletRequest.getSession(boolean). However, this method will not create a session.

createSession

public HttpSession createSession()

Like getSession(), but forces the creation of the HttpSession, if necessary.

redirect

public void redirect(String path)
              throws IOException

Invokes HttpServletResponse.sendRedirect(String), but massages path, supplying missing elements to make it an absolute URL (i.e., specifying scheme, server, port, etc.).

The 2.2 Servlet API will do this automatically, and a little more, according to the early documentation.

Throws:

IOException

write

public void write(IMarkupWriter writer)

Writes the state of the context to the writer, typically for inclusion in a HTML page returned to the user. This is useful when debugging. The Inspector uses this as well.

render

public void render(IMarkupWriter writer,
                   IRequestCycle cycle)

Invokes write(IMarkupWriter), which is used for debugging. Does nothing if the cycle is rewinding.

Specified by:

render in interface IRender

setDecoder

public void setDecoder(IMultipartDecoder decoder)

Sets the multipart decoder to be used for the request.

Parameters:

decoder - the multipart decoder

Since:

3.0