In Detail : The Request Object In Servlets

     The request object encapsulates all information from the client request. The information from the clients is transmitted to the server in the form of HTTP headers and the message body of the request through the HTTP protocol.

What are the HTTP Protocol Parameters ? 

     Request parameters for the servlet are nothing but 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 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.
  1. getParameter()
  2. getParameterNames()
  3. getParameterValues()
  4. getParameterMap()
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 first value in the array of String objects returned by getParameterValues. The getParameterMap method returns a java.util.Map of the parameter of the request, which contains names as keys and parameter values as map values.

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 must be parsed from the String values returned by the getRequestURI method or the getPathInfo method.

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.
  1. The HTTP method is POST.
  2. The content type is application / x-www-form-urlencoded
  3. 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 no longer be available for reading directly from the request object's input stream.

File upload :

If a request is of type multipart / form -data and if the servlet handling the request is annotated using the @Multipartconfig , the HttpServletRequest can make available various parts of the multipart request via the following methods.
  1. public Collection<Part> getParts()
  2. public Part getPart(String name).
Each part provides access to the headers, content type related with it and also content via the getInputStream method. 

For parts with form-data as the Content - Disposition , but with out a filename, the string value of the part will also be available via the getParameter / getParameterValues method on HttpServletRequest, using the name of the part. 

Attributes Associated With a Request :

     Attributes are the objects associated with a request. Attributes may be set by the container to express information or may be set by a servlet to communicate information to another servlet ( via the Request Dispatcher). Attributes are accessed with the following methods of the ServletRequest interface. 
  1. getAttribute()
  2. getAttributeNames()
  3. setAttribute()
Only one attribute value may be associated with an attribute name. 

Attribute names begining with the prefixes of java. , javax. , sun. and com.sun. are reserved. It is suggested that all attributes placed in the attribute set be named in accordance with the reverse domain name convention suggested by the Java Programming Specification for package naming. 

The Headers of an HTTP Request :

A servlet can access the headers of an HTTP request through the following method of the HttpservletRequest interface. 
  1. getHeader()
  2. getHeaders()
  3. getHeaderNames()
The getHeader method returns a header given the name of the header. There can be multiple headers with the same name , e.g 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 Stirng objects. 

Headers may contain String representations of int or Date data. The following convenience methods of HttpServletRequest interface provide access to header data in a one of these formats. 
  1. getIntHeader()
  2. 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 Data object, an IllegalArgumentException is thrown.

The Elements Of Request Path URI :

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. 

1. ContextPath : The path prefix associated with the ServletContext in which the servlet is 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. 

2. 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 '/*' or "" pattern, in which case it is an empty string. 

3. PathInfo : 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 :
  1. getContextPath()
  2. getServletPath()
  3. getPathInfo()
It is important to note that, 

request URI = contextPath + servletPath + pathInfo

Few examples to clarify the above points, consider the following.

Example Context Set Up

Context Path /catalog
Servlet Mapping Pattern : /lawn/*
Servlet : LawnServlet
Servlet Mapping Pattern : /garden/*
Servlet : GardenServlet
Servlet Mapping Pattern : *.jsp
Servlet : JSPServlet
The following behavior is observed: Observed Path Element Behavior

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 : /gardem
PathInfo: /implements/
/catalog/help/feedback.jsp ContextPath : /catalog
ServletPath : /help/feedback.jsp
PathInfo: null

How To Get Cookies From The Request Object ? 

    The HttpServletRequest interface provides the getCookies() method to obtain an array of cookies that are present in the request. So what is a cookie ? The cookies are nothing but data sent from the client to the server on every request that 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. The specification also allows for the cookies to be HttpOnly cookies.

Lifetime of the Request Object :

    Each request object is valid only within the scope of a servlet's serviece() method, or within the scope of a filter's doFilter() method, unless the asynchronous processing is enabled for the component and the startAsync() is invoked on the request object. In the case where asynchronous processing occurs, the request object remains valid until complete() invoked on the AsyncContext. Containers commonly recycle request objects in order to avoid the performance overhead of request object creation.