Chapter 25. The javax.servlet Package

The javax.servlet package is the core of the Servlet API. It contains the classes necessary for a standard, protocol-independent servlet. Every servlet must implement the Servlet interface in one form or another. The abstract GenericServlet class provides the framework for developing basic servlets. The package also includes a variety of utility classes that communicate with the server and the client. Figure 25-1 shows the class hierarchy of this package.

Figure 25-1. The javax.servlet package

GenericServlet

Servlets 1.0

javax.servlet

serializable

The GenericServlet class provides a basic implementation of the Servlet and ServletConfig interfaces. If you are creating a protocol-independent servlet, you probably want to subclass this class rather than implement the Servlet interface directly. Note that the service() method is declared as abstract; this is the only method you have to override to implement a generic servlet.

GenericServlet includes basic implementations of the init() and destroy() methods, which perform basic setup and cleanup tasks, respectively. The init() method that takes a ServletConfig object stores that object for later use. This means that if you override the method and fail to call the super.init(ServletConfig) method, you won't be able to use the ServletConfig methods later. In Version 2.1 of the Servlet API, you can override a no-argument version of init() that is dispatched by the default init(ServletConfig) method of GenericServlet.

public abstract class GenericServlet implements Servlet, ServletConfig, Serializable {
//	Public Constructors
	public GenericServlet ();
//	Public Instance Methods
2.1	public void init () throws ServletException;	empty
	public void log (String msg);
2.1	public void log (String message, Throwable t);
//	Methods implementing Servlet
	public void destroy ();
	public ServletConfig getServletConfig ();
	public String getServletInfo ();
	public void init (ServletConfig config) throws ServletException;
	public abstract void service (ServletRequest req, ServletResponse res) throws ServletException, IOException;
//	Methods implementing ServletConfig
	public String getInitParameter (String name);
	public java.util.Enumeration getInitParameterNames ();
	public ServletContext getServletContext ();
}

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

Subclasses: javax.servlet.http.HttpServlet

RequestDispatcher

Servlets 2.1

javax.servlet

RequestDispatcher allows a servlet to delegate some or all of the processing of a request to another resource on the web server. A RequestDispatcher object is retrieved by calling the getRequestDispatcher() method on the ServletContext object. The forward() method passes a request on to another servlet for processing, while the include() method includes the output of another servlet in the output of the current servlet.

public interface RequestDispatcher {
//	Public Instance Methods
	public abstract void forward (ServletRequest request, ServletResponse response) throws ServletException, IOException;
	public abstract void include (ServletRequest request, ServletResponse response) throws ServletException, IOException;
}

Returned By: ServletContext.getRequestDispatcher()

Servlet

Servlets 1.0

javax.servlet

The Servlet interface defines the basic structure of a servlet. All servlets implement this interface, either directly or by subclassing a class that does. The interface declares the basic servlet functionality: initializing a servlet, handling client requests, and destroying a servlet.

init() is called when the servlet is first initialized. Since init() creates resources the servlet can reuse, it is guaranteed to finish executing before the servlet handles any client requests. The server calls the service() method for each client request. The servlet interacts with the client via ServletRequest and ServletResponse objects passed to service(). destroy() is called to clean up resources (such as database connections) or save state when the server shuts down. The getServletInfo() method should return a String that describes a servlet, and the getServletConfig() method should return the ServletConfig object that was passed to the init() method.

public interface Servlet {
//	Public Instance Methods
	public abstract void destroy ();
	public abstract ServletConfig getServletConfig ();
	public abstract String getServletInfo ();
	public abstract void init (ServletConfig config) throws ServletException;
	public abstract void service (ServletRequest req, ServletResponse res) throws ServletException, IOException;
}

Implementations: GenericServlet

Passed To: UnavailableException.UnavailableException()

Returned By: ServletContext.getServlet(), UnavailableException.getServlet()

ServletConfig

Servlets 1.0

javax.servlet

A ServletConfig object passes configuration information from the server to a servlet. ServletConfig supports initialization parameters (also known simply as init parameters) defined by the server administrator for a particular servlet. These parameters are accessed via the getInitParameter() and getInitParameterNames() methods. ServletConfig also includes a ServletContext object, accessible via getServletContext(), for direct interaction with the server.

public interface ServletConfig {
//	Public Instance Methods
	public abstract String getInitParameter (String name);
	public abstract java.util.Enumeration getInitParameterNames ();
	public abstract ServletContext getServletContext ();
}

Implementations: GenericServlet

Passed To: GenericServlet.init(), Servlet.init()

Returned By: GenericServlet.getServletConfig(), Servlet.getServletConfig()

ServletContext

Servlets 1.0

javax.servlet

ServletContext defines methods that allow a servlet to interact with the host server. This includes reading server-specific attributes, finding information about particular files located on the server, and writing to the server log files. If there are several virtual servers running, each one may return a different ServletContext.

Servlets can also use ServletContext to interact with other servlets loaded on the same server. In Version 1.0 of the Servlet API, this was done via the getServlets() method. In Version 2.0, getServlets() was deprecated in favor of getServlet() and getServletNames(). In Version 2.1, getServlet() and getServletNames() were both deprecated in favor of the new setAttribute() and getAttribute() methods.

public interface ServletContext {
//	Public Instance Methods
	public abstract Object getAttribute (String name);
2.1	public abstract java.util.Enumeration getAttributeNames ();
2.1	public abstract ServletContext getContext (String uripath);
2.1	public abstract int getMajorVersion ();
	public abstract String getMimeType (String file);
2.1	public abstract int getMinorVersion ();
	public abstract String getRealPath (String path);
2.1	public abstract RequestDispatcher getRequestDispatcher (String urlpath);
2.1	public abstract java.net.URL getResource (String path) throws java.net.MalformedURLException;
2.1	public abstract java.io.InputStream getResourceAsStream (String path);
	public abstract String getServerInfo ();
	public abstract void log (String msg);
2.1	public abstract void log (String message, Throwable throwable);
2.1	public abstract void removeAttribute (String name);
2.1	public abstract void setAttribute (String name, Object object);
//	Deprecated Public Methods
#	public abstract Servlet getServlet (String name) throws ServletException;
2.0#	public abstract java.util.Enumeration getServletNames ();
#	public abstract java.util.Enumeration getServlets ();
2.0#	public abstract void log (Exception exception, String msg);
}

Returned By: GenericServlet.getServletContext(), ServletConfig.getServletContext(), ServletContext.getContext()

ServletException

Servlets 1.0

javax.servlet

serializable checked

A generic Exception class used for basic servlet errors. In version 2.1, a servlet can specify a Throwable root cause for this exception (using the constructors that accept Throwable parameters). The root cause can be retrieved with the getRootCause() method.

public class ServletException extends Exception {
//	Public Constructors
2.0	public ServletException ();
2.1	public ServletException (Throwable rootCause);
	public ServletException (String message);
2.1	public ServletException (String message, Throwable rootCause);
//	Public Instance Methods
2.1	public Throwable getRootCause ();	default:null
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ServletException

Subclasses: UnavailableException

Thrown By: GenericServlet.{init(), service()}, RequestDispatcher.{forward(), include()}, Servlet.{init(), service()}, ServletContext.getServlet(), javax.servlet.http.HttpServlet.{doDelete(), doGet(), doOptions(), doPost(), doPut(), doTrace(), service()}

ServletInputStream

Servlets 1.0

javax.servlet

ServletInputStream provides an input stream for reading data from a client request. A servlet can get a ServletInputStream by calling the getInputStream() method of ServletRequest. While ServletInputStream does contain a readLine() method for reading textual data one line at a time, this functionality was taken over by BufferedReader objects and the getReader() method of ServletRequest in Version 2.0 of the Servlet API. Thus, ServletInputStream should be used only to read binary data, generally in the context of a filtering servlet.

public abstract class ServletInputStream extends java.io.InputStream {
//	Protected Constructors
	protected ServletInputStream ();
//	Public Instance Methods
	public int readLine (byte ] b, int off, int len) throws IOException;
}

Hierarchy: Object-->java.io.InputStream-->ServletInputStream

Passed To: javax.servlet.http.HttpUtils.parsePostData()

Returned By: ServletRequest.getInputStream()

ServletOutputStream

Servlets 1.0

javax.servlet

ServletOutputStream provides an output stream for sending binary data back to a client. A servlet can get a ServletOutputStream by calling the getOutputStream() method of ServletResponse. ServletOutputStream was the only available output method in Version 1.0 of the Servlet API. For text and HTML output, it has been supplanted by PrintWriter objects produced by the getWriter() method of ServletResponse. The various print() and println() methods should therefore be regarded as legacies.

public abstract class ServletOutputStream extends java.io.OutputStream {
//	Protected Constructors
	protected ServletOutputStream ();
//	Public Instance Methods
	public void print (long l) throws IOException;
	public void print (float f) throws IOException;
	public void print (double d) throws IOException;
	public void print (int i) throws IOException;
	public void print (String s) throws IOException;
	public void print (boolean b) throws IOException;
	public void print (char c) throws IOException;
	public void println () throws IOException;
	public void println (long l) throws IOException;
	public void println (float f) throws IOException;
	public void println (double d) throws IOException;
	public void println (int i) throws IOException;
	public void println (String s) throws IOException;
	public void println (boolean b) throws IOException;
	public void println (char c) throws IOException;
}

Hierarchy: Object-->java.io.OutputStream-->ServletOutputStream

Returned By: ServletResponse.getOutputStream()

ServletRequest

Servlets 1.0

javax.servlet

A ServletRequest object encapsulates information about a client request. The server passes a ServletRequest object to the service() method of a servlet. ServletRequest provides access to request parameters, such as form values or other request-specific parameters. These are accessed using the getParameterNames(), getParameter(), and getParameterValues() methods. Raw request data can be read by the getReader() method (for textual data) and the getInputStream() method (for binary data). The getContentType(), getContentLength(), and getCharacterEncoding() methods can help retrieve this information. Other methods provide information about the client (getRemoteAddr(), getRemoteHost()), the request itself (getScheme(), getProtocol()), and the server (getServerName(), getServerPort()). Version 2.1 also adds the getAttribute() and setAttribute() methods, which are generally used with the new RequestDispatcher interface.

public interface ServletRequest {
//	Public Instance Methods
	public abstract Object getAttribute (String name);
2.1	public abstract java.util.Enumeration getAttributeNames ();
2.0	public abstract String getCharacterEncoding ();
	public abstract int getContentLength ();
	public abstract String getContentType ();
	public abstract ServletInputStream getInputStream () throws IOException;
	public abstract String getParameter (String name);
	public abstract java.util.Enumeration getParameterNames ();
	public abstract String[ ] getParameterValues (String name);
	public abstract String getProtocol ();
2.0	public abstract BufferedReader getReader () throws IOException;
	public abstract String getRemoteAddr ();
	public abstract String getRemoteHost ();
	public abstract String getScheme ();
	public abstract String getServerName ();
	public abstract int getServerPort ();
2.1	public abstract void setAttribute (String key, Object o);
//	Deprecated Public Methods
#	public abstract String getRealPath (String path);
}

Implementations: javax.servlet.http.HttpServletRequest

Passed To: GenericServlet.service(), RequestDispatcher.{forward(), include()}, Servlet.service(), javax.servlet.http.HttpServlet.service()

ServletResponse

Servlets 1.0

javax.servlet

The ServletResponse object sends MIME-encoded data back to the client. The interface defines a getOutputStream() method that returns a ServletOutputStream for sending binary data and a getWriter() method that returns a PrintWriter for sending textual data. The setContentType() and setContentLength() methods can explicitly set the content type and content length (often necessary for keep-alive connections and other tasks). If you call setContentType(), you should do so before you call getWriter(), as getWriter() consults the content type to determine which charset to use.

public interface ServletResponse {
//	Public Instance Methods
2.0	public abstract String getCharacterEncoding ();
	public abstract ServletOutputStream getOutputStream () throws IOException;
2.0	public abstract PrintWriter getWriter () throws IOException;
	public abstract void setContentLength (int len);
	public abstract void setContentType (String type);
}

Implementations: javax.servlet.http.HttpServletResponse

Passed To: GenericServlet.service(), RequestDispatcher.{forward(), include()}, Servlet.service(), javax.servlet.http.HttpServlet.service()

SingleThreadModel

Servlets 2.0

javax.servlet

SingleThreadModel is a tag interface that tells the server to create a pool of servlet instances to serve individual requests. In this case, the server ensures that each instance of the servlet handles only one service request at a time. SingleThreadModel provides easy thread safety, but imposes performance penalties.

public interface SingleThreadModel {
}

UnavailableException

Servlets 1.0

javax.servlet

serializable checked

An UnavailableException indicates that a servlet is unable to handle client requests, either temporarily or permanently. To specify temporary unavailability, use the three-argument constructor and specify the duration of the servlet's downtime. If a servlet specifies temporary unavailability, the server may (but is not required to) attempt to reload the servlet after the specified interval.

public class UnavailableException extends ServletException {
//	Public Constructors
	public UnavailableException (Servlet servlet, String msg);
	public UnavailableException (int seconds, Servlet servlet, String msg);
//	Public Instance Methods
	public Servlet getServlet ();
	public int getUnavailableSeconds ();
	public boolean isPermanent ();
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ServletException-->UnavailableException