Method Detail

getAttribute

Returns the value of the named attribute as an Object,
or null if no attribute of the given name exists.

Attributes can be set two ways. The servlet container may set
attributes to make available custom information about a request.
For example, for requests made using HTTPS, the attribute
javax.servlet.request.X509Certificate can be used to
retrieve information on the certificate of the client. Attributes
can also be set programatically using
setAttribute(java.lang.String, java.lang.Object). This allows information to be
embedded into a request before a RequestDispatcher call.

Attribute names should follow the same conventions as package
names. This specification reserves names matching java.*,
javax.*, and sun.*.

Parameters:

name - a String specifying the name of the attribute

Returns:

an Object containing the value of the attribute,
or null if the attribute does not exist

setCharacterEncoding

Overrides the name of the character encoding used in the body of this
request. This method must be called prior to reading request parameters
or reading input using getReader(). Otherwise, it has no effect.

Parameters:

env - String containing the name of
the character encoding.

Throws:

UnsupportedEncodingException - if this ServletRequest is still
in a state where a character encoding may be set,
but the specified encoding is invalid

getContentLength

int getContentLength()

Returns the length, in bytes, of the request body and made available by
the input stream, or -1 if the length is not known ir is greater than
Integer.MAX_VALUE. For HTTP servlets,
same as the value of the CGI variable CONTENT_LENGTH.

Returns:

an integer containing the length of the request body or -1 if
the length is not known or is greater than Integer.MAX_VALUE.

getContentLengthLong

long getContentLengthLong()

Returns the length, in bytes, of the request body and made available by
the input stream, or -1 if the length is not known. For HTTP servlets,
same as the value of the CGI variable CONTENT_LENGTH.

Returns:

a long containing the length of the request body or -1L if
the length is not known

getParameter

Returns the value of a request parameter as a String,
or null if the parameter does not exist. Request parameters
are extra information sent with the request. For HTTP servlets,
parameters are contained in the query string or posted form data.

If you use this method with a multivalued
parameter, the value returned is equal to the first value
in the array returned by getParameterValues.

If the parameter data was sent in the request body, such as occurs
with an HTTP POST request, then reading the body directly via getInputStream() or getReader() can interfere
with the execution of this method.

getParameterMap

Request parameters are extra information sent with the request.
For HTTP servlets, parameters are contained in the query string or
posted form data.

Returns:

an immutable java.util.Map containing parameter names as
keys and parameter values as map values. The keys in the parameter
map are of type String. The values in the parameter map are of type
String array.

getProtocol

Returns the name and version of the protocol the request uses
in the form protocol/majorVersion.minorVersion, for
example, HTTP/1.1. For HTTP servlets, the value
returned is the same as the value of the CGI variable
SERVER_PROTOCOL.

getReader

Retrieves the body of the request as character data using
a BufferedReader. The reader translates the character
data according to the character encoding used on the body.
Either this method or getInputStream() may be called to read the
body, not both.

getRemoteHost

Returns the fully qualified name of the client
or the last proxy that sent the request.
If the engine cannot or chooses not to resolve the hostname
(to improve performance), this method returns the dotted-string form of
the IP address. For HTTP servlets, same as the value of the CGI variable
REMOTE_HOST.

Returns:

a String containing the fully
qualified name of the client

setAttribute

Stores an attribute in this request.
Attributes are reset between requests. This method is most
often used in conjunction with RequestDispatcher.

Attribute names should follow the same conventions as
package names. Names beginning with java.*,
javax.*, and com.sun.*, are
reserved for use by Sun Microsystems.
If the object passed in is null, the effect is the same as
calling removeAttribute(java.lang.String).
It is warned that when the request is dispatched from the
servlet resides in a different web application by
RequestDispatcher, the object set by this method
may not be correctly retrieved in the caller servlet.

getLocale

Returns the preferred Locale that the client will
accept content in, based on the Accept-Language header.
If the client request doesn't provide an Accept-Language header,
this method returns the default locale for the server.

Returns:

the preferred Locale for the client

getLocales

Returns an Enumeration of Locale objects
indicating, in decreasing order starting with the preferred locale, the
locales that are acceptable to the client based on the Accept-Language
header.
If the client request doesn't provide an Accept-Language header,
this method returns an Enumeration containing one
Locale, the default locale for the server.

Returns:

an Enumeration of preferred
Locale objects for the client

isSecure

boolean isSecure()

Returns a boolean indicating whether this request was made using a
secure channel, such as HTTPS.

Returns:

a boolean indicating if the request was made using a
secure channel

getRequestDispatcher

Returns a RequestDispatcher object that acts as a wrapper for
the resource located at the given path.
A RequestDispatcher object can be used to forward
a request to the resource or to include the resource in a response.
The resource can be dynamic or static.

The pathname specified may be relative, although it cannot extend
outside the current servlet context. If the path begins with
a "/" it is interpreted as relative to the current context root.
This method returns null if the servlet container
cannot return a RequestDispatcher.

startAsync

Puts this request into asynchronous mode, and initializes its
AsyncContext with the original (unwrapped) ServletRequest
and ServletResponse objects.

Calling this method will cause committal of the associated
response to be delayed until AsyncContext.complete() is
called on the returned AsyncContext, or the asynchronous
operation has timed out.

Calling AsyncContext.hasOriginalRequestAndResponse() on
the returned AsyncContext will return true. Any filters
invoked in the outbound direction after this request was put
into asynchronous mode may use this as an indication that any request
and/or response wrappers that they added during their inbound
invocation need not stay around for the duration of the asynchronous
operation, and therefore any of their associated resources may be
released.

This method clears the list of AsyncListener instances
(if any) that were registered with the AsyncContext returned by the
previous call to one of the startAsync methods, after calling each
AsyncListener at its onStartAsync
method.

Subsequent invocations of this method, or its overloaded
variant, will return the same AsyncContext instance, reinitialized
as appropriate.

Returns:

the (re)initialized AsyncContext

Throws:

IllegalStateException - if this request is within the scope of
a filter or servlet that does not support asynchronous operations
(that is, isAsyncSupported() returns false),
or if this method is called again without any asynchronous dispatch
(resulting from one of the AsyncContext.dispatch() methods),
is called outside the scope of any such dispatch, or is called again
within the scope of the same dispatch, or if the response has
already been closed

startAsync

Puts this request into asynchronous mode, and initializes its
AsyncContext with the given request and response objects.

The ServletRequest and ServletResponse arguments must be
the same instances, or instances of ServletRequestWrapper and
ServletResponseWrapper that wrap them, that were passed to the
service method of the Servlet or the
doFilter method of the Filter, respectively,
in whose scope this method is being called.

Calling this method will cause committal of the associated
response to be delayed until AsyncContext.complete() is
called on the returned AsyncContext, or the asynchronous
operation has timed out.

Calling AsyncContext.hasOriginalRequestAndResponse() on
the returned AsyncContext will return false,
unless the passed in ServletRequest and ServletResponse arguments
are the original ones or do not carry any application-provided wrappers.
Any filters invoked in the outbound direction after this
request was put into asynchronous mode may use this as an indication
that some of the request and/or response wrappers that they added
during their inbound invocation may need to stay in place for
the duration of the asynchronous operation, and their associated
resources may not be released.
A ServletRequestWrapper applied during the inbound
invocation of a filter may be released by the outbound
invocation of the filter only if the given servletRequest,
which is used to initialize the AsyncContext and will be returned by
a call to AsyncContext.getRequest(), does not contain said
ServletRequestWrapper. The same holds true for ServletResponseWrapper
instances.

This method clears the list of AsyncListener instances
(if any) that were registered with the AsyncContext returned by the
previous call to one of the startAsync methods, after calling each
AsyncListener at its onStartAsync
method.

Subsequent invocations of this method, or its zero-argument
variant, will return the same AsyncContext instance, reinitialized
as appropriate. If a call to this method is followed by a call to its
zero-argument variant, the specified (and possibly wrapped) request
and response objects will remain locked in on the returned
AsyncContext.

Parameters:

servletRequest - the ServletRequest used to initialize the
AsyncContext

servletResponse - the ServletResponse used to initialize the
AsyncContext

Returns:

the (re)initialized AsyncContext

Throws:

IllegalStateException - if this request is within the scope of
a filter or servlet that does not support asynchronous operations
(that is, isAsyncSupported() returns false),
or if this method is called again without any asynchronous dispatch
(resulting from one of the AsyncContext.dispatch() methods),
is called outside the scope of any such dispatch, or is called again
within the scope of the same dispatch, or if the response has
already been closed

true if this request has been put into asynchronous mode,
false otherwise

Since:

Servlet 3.0

isAsyncSupported

boolean isAsyncSupported()

Checks if this request supports asynchronous operation.

Asynchronous operation is disabled for this request if this request
is within the scope of a filter or servlet that has not been annotated
or flagged in the deployment descriptor as being able to support
asynchronous handling.

getDispatcherType

The dispatcher type of a request is used by the container
to select the filters that need to be applied to the request:
Only filters with matching dispatcher type and url patterns will
be applied.

Allowing a filter that has been configured for multiple
dispatcher types to query a request for its dispatcher type
allows the filter to process the request differently depending on
its dispatcher type.