[ Team LiB ] Previous Section Next Section

The HttpServletRequest Class

The HttpServletRequest interfaces add HTTP-specific capabilities to the existing ServletRequest interface. If your servlet is an HttpServlet, you receive an HttpServletRequest object in your servlet's service method, or in any of the doGet, doPost, doPut, and other methods. In a JSP, the request object is an HttpServletRequest object.

Getting Header Values

You sometimes need to examine header values sent in the request. The getHeaderNames method returns an enumeration of all the possible header values:

public java.util.Enumeration getHeaderNames()

You can retrieve the header objects as strings, using either getHeader for a single value or getHeaders to get all the values for a particular header name:

public String getHeader(String name)
public java.util.Enumeration getHeaders(String name)

Sometimes a header contains a number or a date. Instead of parsing the value yourself, you can let the request use either getIntHeader or getDateHeader to parse the value:

public int getIntHeader(String name)
public long getDateHeader(String name)

The value that getDateHeader returns is the number of milliseconds since January 1, 1970. If you need a date object, you can create an instance of date like this:

Date d = new Date(getDateHeader("If-Modified-Since"));

The Unix Epoch


Midnight on January 1, 1970, is known as the UNIX epoch—it's the beginning of time for UNIX systems. There's no special reason for having chosen that date, but all time is measured in seconds relative to it.

The UNIX epoch ends GMT 03:14:07, Tuesday, January 19, 2038, when it will overflow the 32-bit type given it by most systems.

In Case of Trouble


If you are having trouble retrieving header values, see the "Q&A" section at the end of this hour.

Getting the HTTP Method

As you have seen, there are several different kinds of HTTP requests. When a browser just requests a page, it uses a GET method. When the browser needs to send form data in the request body instead of the URL, it uses the POST method.

When the browser uploads a file to the server it uses the PUT method. You can find out what method was used to make the request by calling getMethod:

public String getMethod()

Obtaining Information About the Request URI

Occasionally, you might want to access different portions of the URL used to invoke the servlet. For example, in the last hour, you learned that a servlet's context can be identified by inspecting the URL—the context is added as a prefix. getContextPath returns the portion of the URL that identifies the context of the request.

public String getContextPath()

In addition to the context, you can get information about the path that follows a servlet mapping, either as requested or as translated to a real path:

public java.lang.String getPathInfo()
public java.lang.String getPathTranslated()

To get to the portion that directed the container to the servlet, you can use getServletPath:

public java.lang.String getServletPath()

Finally, to obtain the URI or URL, which includes everything but the query string, you use:

public java.lang.String getRequestURI()
public java.lang.StringBuffer getRequestURL()

Accessing the Query String

The list of parameters added to the end of a URL is referred to as the query string. You can retrieve the query string, just as it was originally sent, by calling getQueryString:

public String getQueryString()

Don't forget—even if the browser uses the POST method, it can still pass parameters on the query string. The query string doesn't have to be in the name=value format. You can put any string in a request's query string.

Getting Session Information

HTTP is a stateless protocol, which means that the protocol doesn't remember anything about clients or their transactions between requests. HTTP delegates this responsibility to the application. Applications use sessions to group related requests together and to associate them with a client. Whenever you use a Web application that is able to recall your interactions, such as displaying items you added to a shopping cart, you can be certain that the application is using sessions.

Sessions are an integral part of servlets and JSPs. In Hours 12 and 13, you will learn how to use sessions in more detail.

The getSession method returns the session associated with the client and optionally creates a session if one doesn't already exist:

public Session getSession()
public Session getSession(boolean create)

If the create flag is true, getSession creates a new session if one doesn't exist. If a session doesn't exist and create is false, getSession returns null. Calling getSession with no parameter is the same as calling it with a value of true for the create flag.

Several mechanisms exist that are used to manage sessions. You are probably familiar with cookies, which make it possible to deposit a small amount of information with a client. Cookies can be used to store a session identifier. A session identifier may also be encoded into the request URI. Fortunately, using sessions with JSPs or servlets doesn't require specialized handling by a method.

Although a session identifier is usually stored in a cookie, the servlet API provides a way to keep track of sessions by passing the session ID as a form variable in the URL. You can determine whether the session ID comes from a cookie or from the URL by calling isRequestedSessionIdFromCookie or isRequestedSessionIdFromURL:

public boolean isRequestedSessionIdFromCookie()
public boolean isRequestedSessionIdFromURL()

If you need to see whether the session ID is still valid, call isRequestedSessionIdValid:

public boolean isRequestedSessionIdValid()

You can also find out the session ID that the client requested by using getRequestedSessionId:

public java.lang.String getRequestedSessionId()

Retrieving Cookies

Beyond providing support for sessions, cookies can be used to store up to 4KB of data. They are often used to save user preferences.

The getCookies method returns an array of cookie objects passed in from the client:

public Cookie[] getCookies()

Cookies are discussed in detail at the end of this hour.

    [ Team LiB ] Previous Section Next Section