javax.servlet
Class UnavailableException

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--javax.servlet.ServletException
                    |
                    +--javax.servlet.UnavailableException

public class UnavailableException

extends ServletException

Defines an exception that a servlet throws to indicate that it is permanently or temporarily unavailable.

When a servlet is permanently unavailable, something is wrong with the servlet, and it cannot handle requests until some action is taken. For example, the servlet might be configured incorrectly, or its state may be corrupted. A servlet should log both the error and the corrective action that is needed.

A servlet is temporarily unavailable if it cannot handle requests momentarily due to some system-wide problem. For example, a third-tier server might not be accessible, or there may be insufficient memory or disk storage to handle requests. A system administrator may need to take corrective action.

Servlet engines can safely treat both types of unavailable exceptions in the same way. However, treating temporary unavailability effectively makes the servlet engine more robust. Specifically, the servlet engine might block requests to the servlet for a period of time suggested by the servlet, rather than rejecting them until the servlet engine restarts.

Version:

$Version$

Author:

Various

See Also:

Serialized Form

Constructor Summary

UnavailableException(int seconds, Servlet servlet, java.lang.String msg)
Constructs a new exception with a descriptive message indicating that the servlet is temporarily unavailable and giving an estimate of how long it will be unavailable.

UnavailableException(Servlet servlet, java.lang.String msg)
Constructs a new exception with a descriptive message indicating that the servlet is permanently unavailable.

Method Summary

Servlet	getServlet() Returns the servlet that is reporting its unavailability.
int	getUnavailableSeconds() Returns the number of seconds the servlet expects to be temporarily unavailable.
boolean	isPermanent() Returns a boolean primitive type indicating whether the servlet is permanently unavailable.

Methods inherited from class javax.servlet.ServletException

getRootCause

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnavailableException

public UnavailableException(Servlet servlet,
                            java.lang.String msg)

Constructs a new exception with a descriptive message indicating that the servlet is permanently unavailable.

Parameters:

servlet - the Servlet instance that is unavailable

msg - a String specifying the descriptive message

UnavailableException

public UnavailableException(int seconds,
                            Servlet servlet,
                            java.lang.String msg)

Constructs a new exception with a descriptive message indicating that the servlet is temporarily unavailable and giving an estimate of how long it will be unavailable.

In some cases, the servlet cannot make an estimate. For example, the servlet might know that a server it needs is not running, but not be able to report how long it will take to be restored to functionality. You can indicate that the servlet can't estimate a time by entering a negative or zero value for the seconds argument.

Parameters:

seconds - an integer specifying the number of seconds the servlet expects to be unavailable; if zero or negative, indicates that the servlet can't make an estimate

servlet - the Servlet that is unavailable

msg - a String specifying the descriptive message, which can be written to a log file or displayed for the user.

Method Detail

isPermanent

public boolean isPermanent()

Returns a boolean primitive type indicating whether the servlet is permanently unavailable. If so, something is wrong with the servlet, and the system administrator must take some corrective action.

Returns:

true if the servlet is permanently unavailable; false if the servlet is available or temporarily unavailable

getServlet

public Servlet getServlet()

Returns the servlet that is reporting its unavailability.

Returns:

the Servlet object that is throwing the UnavailableException

getUnavailableSeconds

public int getUnavailableSeconds()

Returns the number of seconds the servlet expects to be temporarily unavailable.

If this method returns a negative number, the servlet is permanently unavailable or cannot provide an estimate of how long it will be unavailable. No effort is made to correct for the time elapsed since the exception was first reported.

Returns:

an integer specifying the number of seconds the servlet will be temporarily unavailable, or a negative number if the servlet is permanently unavailable or cannot make an estimate