The Request

C H A P T E R 4

The Request

The request object encapsulates all information from the client request. In the HTTP protocol, this information is transmitted from the client to the server in the HTTP headers and the message body of the request.

4.1 HTTP Protocol Parameters

Request parameters for the servlet are the strings sent by the client to a servlet container as part of its request. When the request is an HttpServletRequest object, and conditions set out in Section 4.1.1, When Parameters Are Available are met, the container populates the parameters from the URI query string and POST-ed data.

The parameters are stored as a set of name-value pairs. Multiple parameter values can exist for any given parameter name. The following methods of the ServletRequest interface are available to access parameters:

getParameter

getParameterNames

getParameterValues

The getParameterValues method returns an array of String objects containing all the parameter values associated with a parameter name. The value returned from the getParameter method must be the first value in the array of String objects returned by getParameterValues. The getParameterNames method returns a java.util.Enumeration of all the parameter names of the request.

Data from the query string and the post body are aggregated into the request parameter set. Query string data is presented before post body data. For example, if a request is made with a query string of a=hello and a post body of a=goodbye&a=world, the resulting parameter set would be ordered a=(hello, goodbye, world).

Path parameters that are part of a GET request (as defined by HTTP 1.1) are not exposed by these APIs. They must be parsed from the String values returned by the getRequestURI method or the getPathInfo method.

4.1.1 When Parameters Are Available

The following are the conditions that must be met before post form data will be populated to the parameter set:

The request is an HTTP or HTTPS request.

The HTTP method is POST.

The content type is application/x-www-form-urlencoded.

The servlet has made an initial call of any of the getParameter family of methods on the request object.

If the conditions are not met and the post form data is not included in the parameter set, the post data must still be available to the servlet via the request object’s input stream. If the conditions are met, post form data will not be available for reading directly from the request object’s input stream.

4.2 Attributes

Attributes are objects associated with a request. Attributes may be set by the container to express information that otherwise could not be expressed via the API, or may be set by a servlet to communicate information to another servlet (via the RequestDispatcher). Attributes are accessed with the following methods of the ServletRequest interface:

getAttribute

getAttributeNames

setAttribute

Only one attribute value may be associated with an attribute name.

Attribute names beginning with the prefixes of “javacard.” and “javacardx.”, “java.” and “javax.” are reserved for definition by this specification. Similarly, attribute names beginning with the prefixes of “sun.”, and “com.sun.” are reserved for definition by Sun Microsystems. It is suggested that all attributes placed in the attribute set be named in accordance with the reverse domain name convention for package naming suggested by The Java Programming Language Specification, available at http://java.sun.com/docs/books/jls/.

4.3 Headers

A servlet can access the headers of an HTTP request through the following methods of the HttpServletRequest interface:

getHeader

getHeaders

getHeaderNames

The getHeader method returns a header given the name of the header. There can be multiple headers with the same name, for example Cache-Control headers, in an HTTP request. If there are multiple headers with the same name, the getHeader method returns the first header in the request. The getHeaders method allows access to all the header values associated with a particular header name, returning an Enumeration of String objects.

Headers may contain String representations of int or Date data. The following convenience methods of the HttpServletRequest interface provide access to header data in a one of these formats:

getIntHeader

getDateHeader

If the getIntHeader method cannot translate the header value to an int, a NumberFormatException is thrown. If the getDateHeader method cannot translate the header to a Date object, an IllegalArgumentException is thrown.

4.4 Request Path Elements

The request path that leads to a servlet servicing a request is composed of many important sections. The following elements are obtained from the request URI path and exposed via the request object:

Context Path: The path prefix associated with the ServletContext that this servlet is a part of. If this context is the “default” context rooted at the base of the web server’s URL name space, this path will be an empty string. Otherwise, if the context is not rooted at the root of the server’s name space, the path starts with a “/” character but does not end with a “/” character.

Servlet Path: The path section that directly corresponds to the mapping which activated this request. This path starts with a “/” character except in the case where the request is matched with the “/*” pattern, in which case it is an empty string.

Path Info: The part of the request path that is not part of the Context Path or the Servlet Path. It is either null if there is no extra path, or is a string with a leading “/”.

The following methods exist in the HttpServletRequest interface to access this information:

getContextPath

getServletPath

getPathInfo

It is important to note that, except for URL encoding differences between the request URI and the path parts, the following equation is always true:

requestURI = contextPath + servletPath + pathInfo

To give a few examples to clarify the above points, consider the setup shown in TABLE 4-1.

TABLE 4-1 Example Context Setup
Context Path	`/catalog`
Servlet Mapping	`Pattern: /lawn/*` `Servlet: LawnServlet`
Servlet Mapping	`Pattern: /garden/*` `Servlet: GardenServlet`
Servlet Mapping	`Pattern: *.shtml` `Servlet: SHTMLServlet`

The behavior based on the context setup shown in TABLE 4-1 results in the path elements shown in TABLE 4-2.

TABLE 4-2 Observed Path Element Behavior
Request Path	Path Elements
`/catalog/lawn/index.html`	`ContextPath: /catalog` `ServletPath: /lawn` `PathInfo: /index.html`
`/catalog/garden/implements/`	`ContextPath: /catalog` `ServletPath: /garden` `PathInfo: /implements/`
`/catalog/help/feedback.shtml`	`ContextPath: /catalog` `ServletPath: /help/feedback.shtml` `PathInfo: null`

TABLE 4-2 Observed Path Element Behavior

Request Path

Path Elements

/catalog/lawn/index.html

ContextPath: /catalog
ServletPath: /lawn
PathInfo: /index.html

/catalog/garden/implements/

ContextPath: /catalog
ServletPath: /garden
PathInfo: /implements/

/catalog/help/feedback.shtml

ContextPath: /catalog
ServletPath: /help/feedback.shtml
PathInfo: null

4.5 Path Translation Methods

There are two convenience methods in the API that allow the developer to obtain the file system path equivalent to a particular path. These methods are:

ServletContext.getRealPath

HttpServletRequest.getPathTranslated

The getRealPath method takes a String argument and returns a String representation of a file on the local file system to which a path corresponds. The getPathTranslated method computes the real path of the pathInfo of the request.

In situations where the servlet container cannot determine a valid file path for these methods, such as when the web application is executed from an archive, or an in-memory representation, these methods must return null.

4.6 Cookies

The HttpServletRequest interface provides the getCookies method to obtain an array of cookies that are present in the request. These cookies are data sent from the client to the server on every request that the client makes. Typically, the only information that the client sends back as part of a cookie is the cookie name and the cookie value. Other cookie attributes that can be set when the cookie is sent to the browser, such as comments, are not typically returned.

4.7 SSL Attributes

If a request has been transmitted over a secure protocol, such as HTTPS, this information must be exposed via the isSecure method of the ServletRequest interface. The web container must expose the attributes listed in TABLE 4-3 to the servlet programmer.

TABLE 4-3 Protocol Attributes
Attribute	Attribute Name	Java Type
cipher suite	`javax.servlet.request.cipher_suite`	`String`
bit size of the algorithm	`javax.servlet.request.key_size`	`Integer`

In this Java Card Platform version of the specification, if there is an SSL certificate associated with the request, it must be exposed by the servlet container to the servlet programmer as an object of type javax.microedition.pki.Certificate and accessible via a ServletRequest attribute of javacardx.servlet.request.X509Certificate. This certificate corresponds to the web client’s subject certificate.

In this Java Card Platform version of the specification, if there is a TLS PSK identity associated with the request, it must be exposed by the servlet container to the servlet programmer as an object of type java.lang.String and accessible via a ServletRequest attribute of javacardx.servlet.request.PSKIdentity.

4.8 Internationalization

Clients may optionally indicate to a web server the language in which they would prefer the response be given. This information can be communicated from the client using the Accept-Language header along with other mechanisms described in the HTTP/1.1 specification. The following methods are provided in the ServletRequest interface to determine the preferred locale of the sender:

getLocale

getLocales

The getLocale method will return the preferred locale for which the client wants to accept content. See section 14.4 of RFC 2616 (HTTP/1.1) for more information about how the Accept-Language header must interpreted to determine the preferred language of the client.

The getLocales method will return an Enumeration of Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client.

If no preferred locale is specified by the client, the locale returned by the getLocale method must be the default locale for the servlet container and the getLocales method must contain an enumeration of a single Locale element of the default locale.

4.9 Request Data Encoding

Currently, many browsers do not send a char encoding qualifier with the Content-Type header, leaving open the determination of the character encoding for reading HTTP requests. The default encoding of a request the container uses to create the request reader and parse POST data must be “ISO-8859-1” if none has been specified by the client request. However, in order to indicate to the developer in this case the failure of the client to send a character encoding, the container returns null from the getCharacterEncoding method.

Breakage can occur if the client has not set character encoding and the request data is encoded with a different encoding than the default as described above. To remedy this situation, a new method setCharacterEncoding(String enc) has been added to the ServletRequest interface. Developers can override the character encoding supplied by the container by calling this method. It must be called prior to parsing any post data or reading any input from the request. Calling this method once data has been read will not affect the encoding.

4.10 Lifetime of the Request Object

Each request object is valid only within the scope of a servlet’s service method, or within the scope of a filter’s doFilter method. Containers commonly recycle request objects in order to avoid the performance overhead of request object creation. The developer must note that maintaining references to request objects outside the scope described above is not recommended as it may have indeterminate results.

Refer to the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Connected Edition for more details on the lifetime of request objects specific to the Java Card Platform.