The javax.servlet Package

---

The javax.servlet package provides the contract between the servlet/web application and the web container. It allows the servlet container vendor to focus on developing the container in the manner most suited to their requirements (or those of their customers), so long as they provide the specified implementations of the servlet interfaces for the web application. From the developer's perspective, the package provides a standard library to process client requests and develop servlet-based web applications.

Here is a class diagram of the classes and interfaces present in the javax.servlet package:

At the heart of the javax.servlet package is the Servlet interface that defines the core structure of a servlet. This is the basis for all servlet implementations, although for most servlet implementations, we subclass from a defined implementation of this interface that provides the basis for our web applications.

The additional interfaces and classes provide additional services to the developer. An example of such a service would be the servlet container providing the servlet with access to the client request through a standard interface. The javax.servlet package therefore provides the basis for developing a cross platform, cross servlet container web application, allowing the programmers to focus on the development of a web application.

Developers sometimes tend to focus on the javax.servlet.http package, but understanding the javax.servlet package will help you use both packages optimally. Additionally, should you need to, you can use this package to build your own servlet implementation that makes use of a different protocol to HTTP that is more suitable for your application. For example, we could extend from the javax.servlet package to implement an SMTP (Simple Mail Transfer Protocol) servlet that provides e-mail services to clients.

Let's now take a look at the interfaces, classes, and exception classes of the javax.servlet package.

The javax.servlet Interfaces

The javax.servlet package is composed of twelve interfaces. The servlet container provides the implementation of the seven interfaces below:

• ServletConfig

• ServletContext

• ServletRequest

• ServletResponse

• RequestDispatcher

• FilterChain

• FilterConfig

These are objects that the container must provide to the servlet to provide services to the web application. They are provided as interfaces so that the vendor can decide the most suitable implementation for their container.

The programmer building the web application implements the remaining five interfaces:

• Servlet

• ServletContextListener

• ServletContextAttributeListener

• SingleThreadModel

• Filter

The purpose behind defining these programmer interfaces is that the container may invoke the implementations using the methods defined in the interface. Hence, the servlet container only needs to know about the methods defined in the interface, while the details of the implementation are up to the developer.

The Servlet interface defines the lifecycle methods of the basic servlet: initialization, service, and destruction. The interface also includes the getServletConfig() method, which the servlet can use to access the ServletConfig object. The servlet container uses a ServletConfig object to pass initialization information to the servlet.

Probably the most important method of the ServletConfig interface is the getServletContext() method. This method returns the ServletContext object. The ServletContext object is used to communicate with the servlet container when we want to perform actions such as writing to a log file or dispatching requests. There is only one ServletContext object per web application (per JVM). This is initialized when the web application is started and destroyed only when the web application is being shutdown.

The ServletContextListener interface is a lifecycle interface that programmers implement to listen for changes to the ServletContext. This means that lifecycle events such as the initialization and destruction of the ServletContext trigger a ServletContextListener implementation listening to this web application. A ServletContextAttributeListener objects performs a similar function, but listens for changes to the attribute list on the ServletContext.

RequestDispatcher defines an object that manages client requests by directing them to the appropriate resource on the server.

The servlet container provides classes that implement the ServletRequest and ServletResponse interfaces. These classes provide the client request information to the servlet and the object used to send a response to the client.

The SingleThreadModel interface has no methods and is used to ensure that a servlet can only handle one request at a time.

Filter, FilterChain, and FilterConfig are new to version 2.3 of the API. They make up the filtering functionality now available to developers. A Filter can be used to filter both requests and responses to and from a servlet.

Filtering has a wide range of uses including authentication, logging, and localization. We will cover it in detail in Chapter 7.

The javax.servlet Classes

There are seven classes contained in this package (plus two exception classes that we'll cover in a moment):

• GenericServlet

• ServletContextEvent

• ServletContextAttributeEvent

• ServletInputStream

• ServletOutputStream

• ServletRequestWrapper

• ServletResponseWrapper

The GenericServlet abstract class can be used to develop protocol-independent servlets, and requires only that we implement the service() method. Although it is more common to use the HttpServlet class (from the javax.servlet.http package) instead for use on the web over the HTTP protocol, it is relatively straightforward to extend from GenericServlet and implement our own protocol-based servlet. The biggest headache would be ensuring that the protocol was fully and accurately implemented.

The two classes ServletContextEvent and ServletContextAttributeEvent are the event classes used for notification about changes to the ServletContext and to the attributes of it respectively.

The ServletInputStream and the ServletOutputStream classes provide input and output streams for reading or sending binary data to and from the client.

Finally, the new wrapper classes (ServletRequestWrapper and ServletResponseWrapper) provide useful implementations of the ServletRequest and ServletResponse interfaces. This implementation can then be subclassed, to allow programmers to adapt or enhance the functionality of the wrapped object for their own web application. This might be done to implement a basic protocol agreed between the client and server, or to transparently adapt requests or responses to a specific format required by the web application.

The javax.servlet Exception Classes

There are two exceptions contained in the javax.servlet package:

• ServletException

• UnavailableException

ServletException is a general exception that a servlet can throw if it hits problems and has to give up. This might be thrown to indicate a problem with the user's request, processing the request, or sending the response.

This exception is thrown to the servlet container, and at this point the application loses control of the request being processed. The servlet container then has the responsibility of cleaning up the request and returning a response to the client. Depending upon the container's implementation and configuration, the container may return an error page to the user indicating a server problem.

Generally though, it is best only to throw ServletExceptions as a last resort. The preferred mechanism for dealing with an 'insurmountable problem' is to handle the problem, and then return an indication of the problem to the client.

The UnavailableException should be thrown when a filter or servlet is temporarily or permanently unavailable. This could apply to resources required by the servlet to process requests (such as a database, a Domain Name Server, or another servlet) not being available, or it may simply be that the servlet load factor is too high.

---