org.apache.tapestry.web
Interface WebRequest

All Superinterfaces:

AttributeHolder, Describable

All Known Implementing Classes:

PortletWebRequest, ServletWebRequest

public interface WebRequest
extends AttributeHolder, Describable

Contains information about the current request, including URLs, schemes, parameters, properties and attributes. This is essentially a generic version of HttpServletRequest. In some cases, certain methods will be unsupported in some implementations (such as getHeader(String) for Portlet Tapestry).

Since:

4.0

Author:

Howard M. Lewis Ship

Method Summary

void	forward(String URL) Redirects to the indicated URL.
String	getActivationPath() Returns the path of the resource which activated this request (this is the equivalent of the servlet path for a servlet request).
String	getContextPath() Returns the portion of the request URI that indicates the context of the request.
long	getDateHeader(String name) Returns the value of the specified request header as a long value that represents a Date object.
String	getHeader(String name) Returns the value of the specified request header.
int	getIntHeader(String name) Returns the value of the specified request header as an int.
Locale	getLocale() Returns the preferred locale to which content should be localized, as specified by the client or by the container.
List	getParameterNames() Returns the names of all query parameters for this request.
String	getParameterValue(String parameterName) Returns a parameter value.
String[]	getParameterValues(String parameterName) Returns all parameter values for a particular parameter name.
String	getPathInfo() Return any additional path info beyond the servlet path itself.
String	getRemoteUser() Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.
String	getRequestURI() Returns the path portion of the request which triggered this request.
String	getScheme() Returns the name of the scheme used to make this request.
String	getServerName() Returns the host name of the server that received the request.
int	getServerPort() Returns the port number on which this request was received.
WebSession	getSession(boolean create) Returns the current WebSessionassociated with this request, possibly creating it if it does not already exist.
Principal	getUserPrincipal() Returns a java.security.Principal object containing the name of the current authenticated user.
boolean	isSecure() Taken from HttpServletRequest.
boolean	isUserInRole(String role) * Returns a boolean indicating whether the authenticated user is included in the specified logical "role".

Methods inherited from interface org.apache.tapestry.web.AttributeHolder

getAttribute, getAttributeNames, setAttribute

Methods inherited from interface org.apache.tapestry.describe.Describable

describeTo

Method Detail

getParameterNames

List getParameterNames()

Returns the names of all query parameters for this request. Note that this may return an empty list if an HTML form submission uploads files (with a request encoding of multipart/form-data). Accessing query parameters in such an event requires parsing of the request input stream.

Returns:

List of Strings, in ascending alphabetical order

getParameterValue

String getParameterValue(String parameterName)

Returns a parameter value. If the parameter was submitted with multiple values, then the first submitted value is returned. May return null if no parameter was submitted with the given name.

Parameters:

parameterName - name of parameter to obtain

Returns:

the corresponding value, or null if a value for the parameter was not submitted in the request

See Also:

getParameterValues(String)

getParameterValues

String[] getParameterValues(String parameterName)

Returns all parameter values for a particular parameter name. May return null.

The caller should not modify the returned value.

Parameters:

parameterName - name of parameter to obtain

Returns:

the corresponding values, or null if no values for the parameter were submitted in the request

See Also:

getParameterValue(String)

getContextPath

String getContextPath()

Returns the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character.

Returns:

The servlet context path.

getSession

WebSession getSession(boolean create)

Returns the current WebSessionassociated with this request, possibly creating it if it does not already exist. If create is false and the request has no valid session, this method returns null. To make sure the session is properly maintained, you must call this method before the response is committed.

Parameters:

create - if true, the session will be created and returned if it does not already exist

Returns:

The session, or null if it does not exist (and create is false)

getScheme

String getScheme()

Returns the name of the scheme used to make this request. For example, http, https, or ftp. Different schemes have different rules for constructing URLs, as noted in RFC 1738.

Returns:

The scheme.

getServerName

String getServerName()

Returns the host name of the server that received the request. Note that behind a firewall, this may be obscured (i.e., it may be the name of the firewall server, which is not necessarily visible to clients outside the firewall).

Returns:

The name of the server.

See Also:

IRequestDecoder

getServerPort

int getServerPort()

Returns the port number on which this request was received.

Returns:

The port number this request is acting on.

getRequestURI

String getRequestURI()

Returns the path portion of the request which triggered this request. Query parameters, scheme, server and port are omitted.

Note: portlets do not know their request URI.

Returns:

The requested URI.

forward

void forward(String URL)

Redirects to the indicated URL. If the URL is local, then a forward occurs. Otherwise, a client side redirect is returned to the client browser.

Parameters:

URL - The url to forward the request to.

getActivationPath

String getActivationPath()

Returns the path of the resource which activated this request (this is the equivalent of the servlet path for a servlet request). The activation path will not end with a slash.

Returns:

The full servlet path (for servlet requests), or a blank string (for portlet requests).

getPathInfo

String getPathInfo()

Return any additional path info beyond the servlet path itself. Path info, if non-null, begins with a path.

Returns:

path info, or null if no path info

getLocale

Locale getLocale()

Returns the preferred locale to which content should be localized, as specified by the client or by the container. May return null.

Returns:

The locale associated with the request, may be null.

getHeader

String getHeader(String name)

Returns the value of the specified request header.

Parameters:

name - the name of the header to retrieve

Returns:

the header value as a string, or null if the header is not in the request.

getDateHeader

long getDateHeader(String name)

Returns the value of the specified request header as a long value that represents a Date object. Use this method with headers that contain dates, such as If-Modified-Since.

The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case insensitive.

If the request did not have a header of the specified name, this method returns -1. If the header can't be converted to a date, the method throws an IllegalArgumentException.

Parameters:

name - a String specifying the name of the header

Returns:

a long value representing the date specified in the header expressed as the number of milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest

Throws:

IllegalArgumentException - If the header value can't be converted to a date

getIntHeader

int getIntHeader(String name)

Returns the value of the specified request header as an int. If the request does not have a header of the specified name, this method returns -1. If the header cannot be converted to an integer, this method throws a NumberFormatException.

The header name is case insensitive.

Parameters:

name - a String specifying the name of a request header

Returns:

an integer expressing the value of the request header or -1 if the request doesn't have a header of this name

Throws:

NumberFormatException - If the header value can't be converted to an int

getRemoteUser

String getRemoteUser()

Returns the login of the user making this request, if the user has been authenticated, or null if the user has not been authenticated.

Returns:

a String specifying the login of the user making this request, or null if the user login is not known.

getUserPrincipal

Principal getUserPrincipal()

Returns a java.security.Principal object containing the name of the current authenticated user.

Returns:

a java.security.Principal containing the name of the user making this request, or null if the user has not been authenticated.

isUserInRole

boolean isUserInRole(String role)

* Returns a boolean indicating whether the authenticated user is included in the specified logical "role". Roles and role membership can be defined using deployment descriptors. If the user has not been authenticated, the method returns false.

Parameters:

role - a String specifying the name of the role

Returns:

a boolean indicating whether the user making this request belongs to a given role; false if the user has not been authenticated.

isSecure

boolean isSecure()

Taken from HttpServletRequest. Indicates if this request is coming in on a SSL/secure connection.

Returns:

True if secure, false otherwise.