HttpServlet must override at least
* one method, usually one of these:
*
* doGet, if the servlet supports HTTP GET requests
* doPost, for HTTP POST requests
* doPut, for HTTP PUT requests
* doDelete, for HTTP DELETE requests
* init and destroy,
* to manage resources that are held for the life of the servlet
* getServletInfo, which the servlet uses to
* provide information about itself
* There's almost no reason to override the service
* method. service handles standard HTTP
* requests by dispatching them to the handler methods
* for each HTTP request type (the doXXX
* methods listed above).
*
*
Likewise, there's almost no reason to override the
* doOptions and doTrace methods.
*
*
Servlets typically run on multithreaded servers,
* so be aware that a servlet must handle concurrent
* requests and be careful to synchronize access to shared resources.
* Shared resources include in-memory data such as
* instance or class variables and external objects
* such as files, database connections, and network
* connections.
* See the
*
* Java Tutorial on Multithreaded Programming for more
* information on handling multiple threads in a Java program.
*
* @author Various
*/
public abstract class HttpServlet extends GenericServlet
implements java.io.Serializable
{
private static final String METHOD_DELETE = "DELETE";
private static final String METHOD_HEAD = "HEAD";
private static final String METHOD_GET = "GET";
private static final String METHOD_OPTIONS = "OPTIONS";
private static final String METHOD_POST = "POST";
private static final String METHOD_PUT = "PUT";
private static final String METHOD_TRACE = "TRACE";
private static final String HEADER_IFMODSINCE = "If-Modified-Since";
private static final String HEADER_LASTMOD = "Last-Modified";
private static final String LSTRING_FILE =
"javax.servlet.http.LocalStrings";
private static ResourceBundle lStrings =
ResourceBundle.getBundle(LSTRING_FILE);
/**
* Does nothing, because this is an abstract class.
*
*/
public HttpServlet() { }
/**
*
* Called by the server (via the service method) to
* allow a servlet to handle a GET request.
*
*
Overriding this method to support a GET request also * automatically supports an HTTP HEAD request. A HEAD * request is a GET request that returns no body in the * response, only the request header fields. * *
When overriding this method, read the request data,
* write the response headers, get the response's writer or
* output stream object, and finally, write the response data.
* It's best to include content type and encoding. When using
* a PrintWriter object to return the response,
* set the content type before accessing the
* PrintWriter object.
*
*
The servlet container must write the headers before * committing the response, because in HTTP the headers must be sent * before the response body. * *
Where possible, set the Content-Length header (with the * {@link javax.servlet.ServletResponse#setContentLength} method), * to allow the servlet container to use a persistent connection * to return its response to the client, improving performance. * The content length is automatically set if the entire response fits * inside the response buffer. * *
When using HTTP 1.1 chunked encoding (which means that the response * has a Transfer-Encoding header), do not set the Content-Length header. * *
The GET method should be safe, that is, without * any side effects for which users are held responsible. * For example, most form queries have no side effects. * If a client request is intended to change stored data, * the request should use some other HTTP method. * *
The GET method should also be idempotent, meaning * that it can be safely repeated. Sometimes making a * method safe also makes it idempotent. For example, * repeating queries is both safe and idempotent, but * buying a product online or modifying data is neither * safe nor idempotent. * *
If the request is incorrectly formatted, doGet
* returns an HTTP "Bad Request" message.
*
*
* @param req an {@link HttpServletRequest} object that
* contains the request the client has made
* of the servlet
*
* @param resp an {@link HttpServletResponse} object that
* contains the response the servlet sends
* to the client
*
* @exception IOException if an input or output error is
* detected when the servlet handles
* the GET request
*
* @exception ServletException if the request for the GET
* could not be handled
*
*
* @see javax.servlet.ServletResponse#setContentType
*
*/
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_get_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
*
* Returns the time the HttpServletRequest
* object was last modified,
* in milliseconds since midnight January 1, 1970 GMT.
* If the time is unknown, this method returns a negative
* number (the default).
*
*
Servlets that support HTTP GET requests and can quickly determine
* their last modification time should override this method.
* This makes browser and proxy caches work more effectively,
* reducing the load on server and network resources.
*
*
* @param req the HttpServletRequest
* object that is sent to the servlet
*
* @return a long integer specifying
* the time the HttpServletRequest
* object was last modified, in milliseconds
* since midnight, January 1, 1970 GMT, or
* -1 if the time is not known
*
*/
protected long getLastModified(HttpServletRequest req) {
return -1;
}
/**
*
*
*
Receives an HTTP HEAD request from the protected
* service method and handles the
* request.
* The client sends a HEAD request when it wants
* to see only the headers of a response, such as
* Content-Type or Content-Length. The HTTP HEAD
* method counts the output bytes in the response
* to set the Content-Length header accurately.
*
*
If you override this method, you can avoid computing
* the response body and just set the response headers
* directly to improve performance. Make sure that the
* doHead method you write is both safe
* and idempotent (that is, protects itself from being
* called multiple times for one HTTP HEAD request).
*
*
If the HTTP HEAD request is incorrectly formatted,
* doHead returns an HTTP "Bad Request"
* message.
*
*
* @param req the request object that is passed
* to the servlet
*
* @param resp the response object that the servlet
* uses to return the headers to the clien
*
* @exception IOException if an input or output error occurs
*
* @exception ServletException if the request for the HEAD
* could not be handled
*/
protected void doHead(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
NoBodyResponse response = new NoBodyResponse(resp);
doGet(req, response);
response.setContentLength();
}
/**
*
* Called by the server (via the service method)
* to allow a servlet to handle a POST request.
*
* The HTTP POST method allows the client to send
* data of unlimited length to the Web server a single time
* and is useful when posting information such as
* credit card numbers.
*
*
When overriding this method, read the request data,
* write the response headers, get the response's writer or output
* stream object, and finally, write the response data. It's best
* to include content type and encoding. When using a
* PrintWriter object to return the response, set the
* content type before accessing the PrintWriter object.
*
*
The servlet container must write the headers before committing the * response, because in HTTP the headers must be sent before the * response body. * *
Where possible, set the Content-Length header (with the * {@link javax.servlet.ServletResponse#setContentLength} method), * to allow the servlet container to use a persistent connection * to return its response to the client, improving performance. * The content length is automatically set if the entire response fits * inside the response buffer. * *
When using HTTP 1.1 chunked encoding (which means that the response * has a Transfer-Encoding header), do not set the Content-Length header. * *
This method does not need to be either safe or idempotent. * Operations requested through POST can have side effects for * which the user can be held accountable, for example, * updating stored data or buying items online. * *
If the HTTP POST request is incorrectly formatted,
* doPost returns an HTTP "Bad Request" message.
*
*
* @param req an {@link HttpServletRequest} object that
* contains the request the client has made
* of the servlet
*
* @param resp an {@link HttpServletResponse} object that
* contains the response the servlet sends
* to the client
*
* @exception IOException if an input or output error is
* detected when the servlet handles
* the request
*
* @exception ServletException if the request for the POST
* could not be handled
*
*
* @see javax.servlet.ServletOutputStream
* @see javax.servlet.ServletResponse#setContentType
*
*
*/
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_post_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
* Called by the server (via the service method)
* to allow a servlet to handle a PUT request.
*
* The PUT operation allows a client to
* place a file on the server and is similar to
* sending a file by FTP.
*
*
When overriding this method, leave intact * any content headers sent with the request (including * Content-Length, Content-Type, Content-Transfer-Encoding, * Content-Encoding, Content-Base, Content-Language, Content-Location, * Content-MD5, and Content-Range). If your method cannot * handle a content header, it must issue an error message * (HTTP 501 - Not Implemented) and discard the request. * For more information on HTTP 1.1, see RFC 2616 * . * *
This method does not need to be either safe or idempotent.
* Operations that doPut performs can have side
* effects for which the user can be held accountable. When using
* this method, it may be useful to save a copy of the
* affected URL in temporary storage.
*
*
If the HTTP PUT request is incorrectly formatted,
* doPut returns an HTTP "Bad Request" message.
*
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet
*
* @param resp the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client
*
* @exception IOException if an input or output error occurs
* while the servlet is handling the
* PUT request
*
* @exception ServletException if the request for the PUT
* cannot be handled
*
*/
protected void doPut(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_put_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
/**
*
* Called by the server (via the service method)
* to allow a servlet to handle a DELETE request.
*
* The DELETE operation allows a client to remove a document
* or Web page from the server.
*
*
This method does not need to be either safe * or idempotent. Operations requested through * DELETE can have side effects for which users * can be held accountable. When using * this method, it may be useful to save a copy of the * affected URL in temporary storage. * *
If the HTTP DELETE request is incorrectly formatted,
* doDelete returns an HTTP "Bad Request"
* message.
*
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet
*
*
* @param resp the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client
*
*
* @exception IOException if an input or output error occurs
* while the servlet is handling the
* DELETE request
*
* @exception ServletException if the request for the
* DELETE cannot be handled
*
*/
protected void doDelete(HttpServletRequest req,
HttpServletResponse resp)
throws ServletException, IOException
{
String protocol = req.getProtocol();
String msg = lStrings.getString("http.method_delete_not_supported");
if (protocol.endsWith("1.1")) {
resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
} else {
resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
}
}
private Method[] getAllDeclaredMethods(Class c) {
if (c.equals(javax.servlet.http.HttpServlet.class)) {
return null;
}
Method[] parentMethods = getAllDeclaredMethods(c.getSuperclass());
Method[] thisMethods = c.getDeclaredMethods();
if ((parentMethods != null) && (parentMethods.length > 0)) {
Method[] allMethods =
new Method[parentMethods.length + thisMethods.length];
System.arraycopy(parentMethods, 0, allMethods, 0,
parentMethods.length);
System.arraycopy(thisMethods, 0, allMethods, parentMethods.length,
thisMethods.length);
thisMethods = allMethods;
}
return thisMethods;
}
/**
* Called by the server (via the service method)
* to allow a servlet to handle a OPTIONS request.
*
* The OPTIONS request determines which HTTP methods
* the server supports and
* returns an appropriate header. For example, if a servlet
* overrides doGet, this method returns the
* following header:
*
*
Allow: GET, HEAD, TRACE, OPTIONS
*
*
There's no need to override this method unless the
* servlet implements new HTTP methods, beyond those
* implemented by HTTP 1.1.
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet
*
*
* @param resp the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client
*
*
* @exception IOException if an input or output error occurs
* while the servlet is handling the
* OPTIONS request
*
* @exception ServletException if the request for the
* OPTIONS cannot be handled
*
*/
protected void doOptions(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
Method[] methods = getAllDeclaredMethods(this.getClass());
boolean ALLOW_GET = false;
boolean ALLOW_HEAD = false;
boolean ALLOW_POST = false;
boolean ALLOW_PUT = false;
boolean ALLOW_DELETE = false;
boolean ALLOW_TRACE = true;
boolean ALLOW_OPTIONS = true;
for (int i=0; iservice method and dispatches
* them to the doXXX methods defined in
* this class. This method is an HTTP-specific version of the
* {@link javax.servlet.Servlet#service} method. There's no
* need to override this method.
*
*
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet
*
*
* @param resp the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client
*
*
* @exception IOException if an input or output error occurs
* while the servlet is handling the
* HTTP request
*
* @exception ServletException if the HTTP request
* cannot be handled
*
* @see javax.servlet.Servlet#service
*
*/
protected void service(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException
{
String method = req.getMethod();
if (method.equals(METHOD_GET)) {
long lastModified = getLastModified(req);
if (lastModified == -1) {
// servlet doesn't support if-modified-since, no reason
// to go through further expensive logic
doGet(req, resp);
} else {
long ifModifiedSince = req.getDateHeader(HEADER_IFMODSINCE);
if (ifModifiedSince < lastModified) {
// If the servlet mod time is later, call doGet()
// Round down to the nearest second for a proper compare
// A ifModifiedSince of -1 will always be less
maybeSetLastModified(resp, lastModified);
doGet(req, resp);
} else {
resp.setStatus(HttpServletResponse.SC_NOT_MODIFIED);
}
}
} else if (method.equals(METHOD_HEAD)) {
long lastModified = getLastModified(req);
maybeSetLastModified(resp, lastModified);
doHead(req, resp);
} else if (method.equals(METHOD_POST)) {
doPost(req, resp);
} else if (method.equals(METHOD_PUT)) {
doPut(req, resp);
} else if (method.equals(METHOD_DELETE)) {
doDelete(req, resp);
} else if (method.equals(METHOD_OPTIONS)) {
doOptions(req,resp);
} else if (method.equals(METHOD_TRACE)) {
doTrace(req,resp);
} else {
//
// Note that this means NO servlet supports whatever
// method was requested, anywhere on this server.
//
String errMsg = lStrings.getString("http.method_not_implemented");
Object[] errArgs = new Object[1];
errArgs[0] = method;
errMsg = MessageFormat.format(errMsg, errArgs);
resp.sendError(HttpServletResponse.SC_NOT_IMPLEMENTED, errMsg);
}
}
/*
* Sets the Last-Modified entity header field, if it has not
* already been set and if the value is meaningful. Called before
* doGet, to ensure that headers are set before response data is
* written. A subclass might have set this header already, so we
* check.
*/
private void maybeSetLastModified(HttpServletResponse resp,
long lastModified) {
if (resp.containsHeader(HEADER_LASTMOD))
return;
if (lastModified >= 0)
resp.setDateHeader(HEADER_LASTMOD, lastModified);
}
/**
*
* Dispatches client requests to the protected
* service method. There's no need to
* override this method.
*
*
* @param req the {@link HttpServletRequest} object that
* contains the request the client made of
* the servlet
*
*
* @param res the {@link HttpServletResponse} object that
* contains the response the servlet returns
* to the client
*
*
* @exception IOException if an input or output error occurs
* while the servlet is handling the
* HTTP request
*
* @exception ServletException if the HTTP request cannot
* be handled
*
*
* @see javax.servlet.Servlet#service
*
*/
public void service(ServletRequest req, ServletResponse res)
throws ServletException, IOException
{
HttpServletRequest request;
HttpServletResponse response;
try {
request = (HttpServletRequest) req;
response = (HttpServletResponse) res;
} catch (ClassCastException e) {
throw new ServletException("non-HTTP request or response");
}
service(request, response);
}
}
/*
* A response that includes no body, for use in (dumb) "HEAD" support.
* This just swallows that body, counting the bytes in order to set
* the content length appropriately. All other methods delegate directly
* to the wrapped HTTP Servlet Response object.
*/
// file private
class NoBodyResponse extends HttpServletResponseWrapper {
private static final ResourceBundle lStrings
= ResourceBundle.getBundle("javax.servlet.http.LocalStrings");
private NoBodyOutputStream noBody;
private PrintWriter writer;
private boolean didSetContentLength;
private boolean usingOutputStream;
// file private
NoBodyResponse(HttpServletResponse r) {
super(r);
noBody = new NoBodyOutputStream();
}
// file private
void setContentLength() {
if (!didSetContentLength) {
if (writer != null) {
writer.flush();
}
setContentLength(noBody.getContentLength());
}
}
public void setContentLength(int len) {
super.setContentLength(len);
didSetContentLength = true;
}
public ServletOutputStream getOutputStream() throws IOException {
if (writer != null) {
throw new IllegalStateException(
lStrings.getString("err.ise.getOutputStream"));
}
usingOutputStream = true;
return noBody;
}
public PrintWriter getWriter() throws UnsupportedEncodingException {
if (usingOutputStream) {
throw new IllegalStateException(
lStrings.getString("err.ise.getWriter"));
}
if (writer == null) {
OutputStreamWriter w = new OutputStreamWriter(
noBody, getCharacterEncoding());
writer = new PrintWriter(w);
}
return writer;
}
}
/*
* Servlet output stream that gobbles up all its data.
*/
// file private
class NoBodyOutputStream extends ServletOutputStream {
private static final String LSTRING_FILE =
"javax.servlet.http.LocalStrings";
private static ResourceBundle lStrings =
ResourceBundle.getBundle(LSTRING_FILE);
private int contentLength = 0;
// file private
NoBodyOutputStream() {}
// file private
int getContentLength() {
return contentLength;
}
public void write(int b) {
contentLength++;
}
public void write(byte buf[], int offset, int len)
throws IOException
{
if (len >= 0) {
contentLength += len;
} else {
// This should have thrown an IllegalArgumentException, but
// changing this would break backwards compatibility
throw new IOException(lStrings.getString("err.io.negativelength"));
}
}
}