Book Home Java Enterprise in a Nutshell Search this book

Chapter 26. The javax.servlet.http Package

The javax.servlet.http package supports the development of servlets that use the HTTP protocol. The classes in this package extend the basic servlet functionality to support various HTTP specific features, including request and response headers, different request methods, and cookies. The abstract HttpServlet class extends javax.servlet.GenericServlet and serves as the base class for HTTP servlets. HttpServlet-Request and HttpServletResponse allow additional interaction with the client. Finally, since the HTTP protocol is inherently stateless, the package also includes HttpSession and some related classes to support session tracking. Figure 26-1 shows the class hierarchy of this package.

figure

Figure 26-1. The javax.servlet.http package

CookieServlets 2.0
javax.servlet.httpcloneable

The Cookie class provides servlets with an easy way to read, create, and manipulate HTTP-style cookies. Cookies provide a way to store a small amount of information on the client and are typically used for session tracking or storing user-configuration information. The getCookies() method of HttpServletRequest returns an array of Cookie objects. To set a new cookie on the client, a servlet creates a new Cookie object and uses the addCookie() method of HttpServletResponse. This must be done before sending any other content, since cookies are created within the HTTP header stream. The various methods of the Cookie class allow a servlet to set and get various attributes of a Cookie object, such as its path and domain.

public class Cookie implements Cloneable {
// Public Constructors
public Cookie (String name, String value);
// Public Instance Methods
public String getComment ();
public String getDomain ();
public int getMaxAge ();
public String getName ();
public String getPath ();
public boolean getSecure ();
public String getValue ();
public int getVersion ();
public void setComment (String purpose);
public void setDomain (String pattern);
public void setMaxAge (int expiry);
public void setPath (String uri);
public void setSecure (boolean flag);
public void setValue (String newValue);
public void setVersion (int v);
// Public methods overriding Object
public Object clone ();
}

Hierarchy: Object-->Cookie(Cloneable)

Passed To: HttpServletResponse.addCookie()

Returned By: HttpServletRequest.getCookies()

HttpServletServlets 1.0
javax.servlet.httpserializable

The abstract HttpServlet class serves as a framework for servlets that generate content for the World Wide Web using the HTTP protocol. Rather than overriding the service() method, you should override one or more of the method-specific request handlers (doGet(), doPost(), doPut(), etc.). The default service() implementation dispatches incoming requests to the appropriate methods, and so should not be overridden. The default implementations of doGet(), doPost(), doDelete(), and doPut() all return an HTTP BAD_REQUEST error, so if you want to handle one of these kinds of requests, you must override the appropriate method.

A web server calls getLastModified() in response to conditional GET requests. The default implementation returns -1. If you know when the output of your servlet last changed, you can return that time, specified in milliseconds since midnight, January 1, 1970 GMT, instead. This allows web browsers to cache your servlet's response.

public abstract class HttpServlet extends GenericServletimplements Serializable {
// Public Constructors
public HttpServlet ();
// Public methods overriding GenericServlet
public void service (ServletRequest req, ServletResponse res) throws ServletException, IOException;
// Protected Instance Methods
2.0protected void doDelete (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
protected void doGet (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
2.0protected void doOptions (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
protected void doPost (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
2.0protected void doPut (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
2.0protected void doTrace (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
protected long getLastModified (HttpServletRequest req);
protected void service (HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
}

Hierarchy: Object-->GenericServlet(Servlet,ServletConfig,Serializable)-->HttpServlet(Serializable)

HttpServletRequestServlets 1.0
javax.servlet.http

HttpServletRequest extends javax.servlet.ServletRequest and provides a number of methods that make it easy to access specific information related to an HTTP request. This includes methods for directly accessing HTTP headers: getHeader(), getIntHeader(), getDateHeader(), and getHeaderNames(). Other methods return various information about the request, including getMethod(), which returns the request method (GET, POST, etc), getPathInfo(), which returns any extra path information attached to the request, getPathTranslated(), which translates the extra path information into a filesystem path, and getServletPath(), which returns the URI pointing to the current servlet, minus any extra path information. The interface also includes the getCookies() method for retrieving cookie data and getSession() for accessing the current HttpSession object.

public interface HttpServletRequest extends ServletRequest {
// Public Instance Methods
public abstract String getAuthType ();
2.0public abstract Cookie[ ] getCookies ();
public abstract long getDateHeader (String name);
public abstract String getHeader (String name);
public abstract java.util.Enumeration getHeaderNames ();
public abstract int getIntHeader (String name);
public abstract String getMethod ();
public abstract String getPathInfo ();
public abstract String getPathTranslated ();
public abstract String getQueryString ();
public abstract String getRemoteUser ();
2.0public abstract String getRequestedSessionId ();
public abstract String getRequestURI ();
public abstract String getServletPath ();
2.1public abstract HttpSession getSession ();
2.0public abstract HttpSession getSession (boolean create);
2.0public abstract boolean isRequestedSessionIdFromCookie ();
2.1public abstract boolean isRequestedSessionIdFromURL ();
2.0public abstract boolean isRequestedSessionIdValid ();
// Deprecated Public Methods
2.0#public abstract boolean isRequestedSessionIdFromUrl ();
}

Hierarchy: (HttpServletRequest(ServletRequest))

Passed To: HttpServlet.{doDelete(), doGet(), doOptions(), doPost(), doPut(), doTrace(), getLastModified(), service()}, HttpUtils.getRequestURL()

HttpServletResponseServlets 1.0
javax.servlet.http

HttpServletResponse extends javax.servlet.ServletResponse and provides additional methods for HTTP-specific actions and a set of HTTP response code constants. The containsHeader(), setHeader(), setDateHeader(), and setIntHeader() methods allow servlets to set and update specific HTTP response headers. The addCookie() method writes a cookie, represented by a Cookie object, to the client. The sendError() and setStatus() methods allow servlets to set specific HTTP result codes, along with an optional customized error message. The encodeUrl() and encodeRedirectUrl() methods (deprecated in 2.1 in favor of encodeURL() and encodeRedirectURL()) methods support session tracking without the use of cookies. The sendRedirect() method handles an HTTP page redirect.

public interface HttpServletResponse extends ServletResponse {
// Public Constants
public static final int SC_ACCEPTED ; =202
public static final int SC_BAD_GATEWAY ; =502
public static final int SC_BAD_REQUEST ; =400
2.0public static final int SC_CONFLICT ; =409
2.0public static final int SC_CONTINUE ; =100
public static final int SC_CREATED ; =201
public static final int SC_FORBIDDEN ; =403
2.0public static final int SC_GATEWAY_TIMEOUT ; =504
2.0public static final int SC_GONE ; =410
2.0public static final int SC_HTTP_VERSION_NOT_SUPPORTED ; =505
public static final int SC_INTERNAL_SERVER_ERROR ; =500
2.0public static final int SC_LENGTH_REQUIRED ; =411
2.0public static final int SC_METHOD_NOT_ALLOWED ; =405
public static final int SC_MOVED_PERMANENTLY ; =301
public static final int SC_MOVED_TEMPORARILY ; =302
2.0public static final int SC_MULTIPLE_CHOICES ; =300
public static final int SC_NO_CONTENT ; =204
2.0public static final int SC_NON_AUTHORITATIVE_INFORMATION ; =203
2.0public static final int SC_NOT_ACCEPTABLE ; =406
public static final int SC_NOT_FOUND ; =404
public static final int SC_NOT_IMPLEMENTED ; =501
public static final int SC_NOT_MODIFIED ; =304
public static final int SC_OK ; =200
2.0public static final int SC_PARTIAL_CONTENT ; =206
2.0public static final int SC_PAYMENT_REQUIRED ; =402
2.0public static final int SC_PRECONDITION_FAILED ; =412
2.0public static final int SC_PROXY_AUTHENTICATION_REQUIRED ; =407
2.0public static final int SC_REQUEST_ENTITY_TOO_LARGE ; =413
2.0public static final int SC_REQUEST_TIMEOUT ; =408
2.0public static final int SC_REQUEST_URI_TOO_LONG ; =414
2.0public static final int SC_RESET_CONTENT ; =205
2.0public static final int SC_SEE_OTHER ; =303
public static final int SC_SERVICE_UNAVAILABLE ; =503
2.0public static final int SC_SWITCHING_PROTOCOLS ; =101
public static final int SC_UNAUTHORIZED ; =401
2.0public static final int SC_UNSUPPORTED_MEDIA_TYPE ; =415
2.0public static final int SC_USE_PROXY ; =305
// Public Instance Methods
2.0public abstract void addCookie (Cookie cookie);
public abstract boolean containsHeader (String name);
2.1public abstract String encodeRedirectURL (String url);
2.1public abstract String encodeURL (String url);
public abstract void sendError (int sc) throws IOException;
public abstract void sendError (int sc, String msg) throws IOException;
public abstract void sendRedirect (String location) throws IOException;
public abstract void setDateHeader (String name, long date);
public abstract void setHeader (String name, String value);
public abstract void setIntHeader (String name, int value);
public abstract void setStatus (int sc);
// Deprecated Public Methods
2.0#public abstract String encodeRedirectUrl (String url);
2.0#public abstract String encodeUrl (String url);
#public abstract void setStatus (int sc, String sm);
}

Hierarchy: (HttpServletResponse(ServletResponse))

Passed To: HttpServlet.{doDelete(), doGet(), doOptions(), doPost(), doPut(), doTrace(), service()}

HttpSessionServlets 2.0
javax.servlet.http

The HttpSession interface is the core of the session tracking functionality introduced in Version 2.0 of the Servlet API. A servlet obtains an HttpSession objects from the getSession() method of HttpServletRequest. The putValue() and removeValue() methods bind Java objects to a particular session. When possible, bound objects should be (but do not need to be) serializable. getValueNames() returns a String array that contains the names of all objects bound to the session.

public interface HttpSession {
// Public Instance Methods
public abstract long getCreationTime ();
public abstract String getId ();
public abstract long getLastAccessedTime ();
2.1public abstract int getMaxInactiveInterval ();
public abstract Object getValue (String name);
public abstract String[ ] getValueNames ();
public abstract void invalidate ();
public abstract boolean isNew ();
public abstract void putValue (String name, Object value);
public abstract void removeValue (String name);
2.1public abstract void setMaxInactiveInterval (int interval);
// Deprecated Public Methods
#public abstract HttpSessionContext getSessionContext ();
}

Passed To: HttpSessionBindingEvent.HttpSessionBindingEvent()

Returned By: HttpServletRequest.getSession(), HttpSessionBindingEvent.getSession(), HttpSessionContext.getSession()

HttpSessionBindingEventServlets 2.0
javax.servlet.httpserializable event

An HttpSessionBindingEvent is passed to the appropriate method of an HttpSessionBindingListener when an object is bound to or unbound from an HttpSession. The getName() method returns the name to which the bound object has been assigned, and the getSession() method provides a reference to the session the object is being bound to.

public class HttpSessionBindingEvent extends java.util.EventObject {
// Public Constructors
public HttpSessionBindingEvent (HttpSession session, String name);
// Public Instance Methods
public String getName ();
public HttpSession getSession ();
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->HttpSessionBindingEvent

Passed To: HttpSessionBindingListener.{valueBound(), valueUnbound()}

HttpSessionBindingListenerServlets 2.0
javax.servlet.httpevent listener

An object that implements HttpSessionBindingListener is notified with calls to valueBound() and valueUnbound() when it is bound to and unbound from an HttpSession, respectively. The valueUnbound() method is also called when a session is deleted for inactivity or at server shutdown.

public interface HttpSessionBindingListener extends java.util.EventListener {
// Public Instance Methods
public abstract void valueBound (HttpSessionBindingEvent event);
public abstract void valueUnbound (HttpSessionBindingEvent event);
}

Hierarchy: (HttpSessionBindingListener(java.util.EventListener))

HttpSessionContextServlets 2.0; Deprecated in Servlets 2.1
javax.servlet.http

HttpSessionContext provides access to all of the currently active sessions on the server. Note that this class is deprecated as of Version 2.1 of the Servlet API, due to a minor security risk whereby a servlet could expose all the session IDs in use on the server.

public interface HttpSessionContext {
// Deprecated Public Methods
#public abstract java.util.Enumeration getIds ();
#public abstract HttpSession getSession (String sessionId);
}

Returned By: HttpSession.getSessionContext()

HttpUtilsServlets 1.0
javax.servlet.http

The HttpUtils class contains three static methods that perform useful HTTP-related tasks. getRequestURL() forms a functional approximation of the original request URL, including scheme, server name, server port, extra path information, and query string, based on an HttpServletRequest object. The parsePostData() and parseQueryString() methods parse URL-encoded form variables from an InputStream or a String. In most cases, a servlet should use the getParameter(), getParameterValues(), and getParameterNames() methods of HttpServletRequest instead.

public class HttpUtils {
// Public Constructors
public HttpUtils ();
// Public Class Methods
public static StringBuffer getRequestURL (HttpServletRequest req);
public static java.util.Hashtable parsePostData (int len, ServletInputStream in);
public static java.util.Hashtable parseQueryString (String s);
}


Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.