Servlet Exception Classes

---

The servlet container normally manages exceptions that occur in servlets. Many exceptions, such as ServletException and IOException (or subclasses of these) are caught and handled by the servlet container, but it is still important to understand the exception handling process and why they may be thrown. Often if a client closes a connection prematurely, before the servlet has finished handling the request, an IOException will be thrown and caught by the servlet container.

Occasionally, when a server is under a heavy load, it may be unable to fulfill requests and may throw an UnavailableException (which is a subclass of ServletException). The servlet container will then return an error to the client indicating whether this problem is permanent or temporary. Reasons for a permanent UnavailableException might include that the resource is configured incorrectly, while a temporary UnavailableException may occur if resources (for example database connections or disk space) are unavailable.

While we are unlikely to throw ServletExceptions directly, we may want to throw UnavailableExceptions when our servlet is unable to access a resource needed to complete the request. We then can indicate how long the client should wait before retrying their request.

We may also create custom exception classes extending from the standard java.lang.Exception or ServletException classes (as appropriate), which we can use in our web application.

The ServletException Class

The ServletException class provides the four constructors shown below to instantiate a ServletException:

    public ServletException()    public ServletException(String message)    public ServletException(String message, java.lang.Throwable rootCause)    public ServletException(java.lang.Throwable rootCause) 

It also provides a getRootCause() method to determine the cause of the ServletException:

    public java.lang.Throwable getRootCause() 

The UnavailableException Class

The UnavailableException class provides two useful constructors. The first specifies the reason, and is used for a permanently unavailable status. The second is used for a temporary problem, and takes a second parameter indicating the time (in seconds) that the servlet is expected to be unavailable:

    public UnavailableException(String msg)    public UnavailableException(String msg, int seconds) 

The following method returns the expected time that the resource will be unavailable. The number will be negative if there is no estimate, or if it is expected to be permanently unavailable:

    public int getUnavailableSeconds() 

Finally, the isPermanent() method indicates if the problem causing the UnavailableException is a permanent or temporary condition:

    public boolean isPermanent() 

---