UnavailableException.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package javax.servlet;

  18. /**
  19.  * Defines an exception that a servlet or filter throws to indicate that it is permanently or temporarily unavailable.
  20.  * <p>
  21.  * When a servlet or filter is permanently unavailable, something is wrong with it, and it cannot handle requests until
  22.  * some action is taken. For example, a servlet might be configured incorrectly, or a filter's state may be corrupted.
  23.  * The component should log both the error and the corrective action that is needed.
  24.  * <p>
  25.  * A servlet or filter is temporarily unavailable if it cannot handle requests momentarily due to some system-wide
  26.  * problem. For example, a third-tier server might not be accessible, or there may be insufficient memory or disk
  27.  * storage to handle requests. A system administrator may need to take corrective action.
  28.  * <p>
  29.  * Servlet containers can safely treat both types of unavailable exceptions in the same way. However, treating temporary
  30.  * unavailability effectively makes the servlet container more robust. Specifically, the servlet container might block
  31.  * requests to the servlet or filter for a period of time suggested by the exception, rather than rejecting them until
  32.  * the servlet container restarts.
  33.  */
  34. public class UnavailableException extends ServletException {

  35.     private static final long serialVersionUID = 1L;

  36.     /**
  37.      * The Servlet that is unavailable.
  38.      */
  39.     private final Servlet servlet;

  40.     /**
  41.      * Is the issue permanent - i.e. is administrator action required?
  42.      */
  43.     private final boolean permanent;

  44.     /**
  45.      * The estimate of how long the Servlet will be unavailable.
  46.      */
  47.     private final int seconds;

  48.     /**
  49.      * @param servlet the <code>Servlet</code> instance that is unavailable
  50.      * @param msg     a <code>String</code> specifying the descriptive message
  51.      *
  52.      * @deprecated As of Java Servlet API 2.2, use {@link #UnavailableException(String)} instead.
  53.      */
  54.     @Deprecated
  55.     public UnavailableException(Servlet servlet, String msg) {
  56.         super(msg);
  57.         this.servlet = servlet;
  58.         permanent = true;
  59.         this.seconds = 0;
  60.     }

  61.     /**
  62.      * @param seconds an integer specifying the number of seconds the servlet expects to be unavailable; if zero or
  63.      *                    negative, indicates that the servlet can't make an estimate
  64.      * @param servlet the <code>Servlet</code> that is unavailable
  65.      * @param msg     a <code>String</code> specifying the descriptive message, which can be written to a log file or
  66.      *                    displayed for the user.
  67.      *
  68.      * @deprecated As of Java Servlet API 2.2, use {@link #UnavailableException(String, int)} instead.
  69.      */
  70.     @Deprecated
  71.     public UnavailableException(int seconds, Servlet servlet, String msg) {
  72.         super(msg);
  73.         this.servlet = servlet;
  74.         if (seconds <= 0) {
  75.             this.seconds = -1;
  76.         } else {
  77.             this.seconds = seconds;
  78.         }
  79.         permanent = false;
  80.     }

  81.     /**
  82.      * Constructs a new exception with a descriptive message indicating that the servlet is permanently unavailable.
  83.      *
  84.      * @param msg a <code>String</code> specifying the descriptive message
  85.      */
  86.     public UnavailableException(String msg) {
  87.         super(msg);
  88.         seconds = 0;
  89.         servlet = null;
  90.         permanent = true;
  91.     }

  92.     /**
  93.      * Constructs a new exception with a descriptive message indicating that the servlet is temporarily unavailable and
  94.      * giving an estimate of how long it will be unavailable.
  95.      * <p>
  96.      * In some cases, the servlet cannot make an estimate. For example, the servlet might know that a server it needs is
  97.      * not running, but not be able to report how long it will take to be restored to functionality. This can be
  98.      * indicated with a negative or zero value for the <code>seconds</code> argument.
  99.      *
  100.      * @param msg     a <code>String</code> specifying the descriptive message, which can be written to a log file or
  101.      *                    displayed for the user.
  102.      * @param seconds an integer specifying the number of seconds the servlet expects to be unavailable; if zero or
  103.      *                    negative, indicates that the servlet can't make an estimate
  104.      */
  105.     public UnavailableException(String msg, int seconds) {
  106.         super(msg);

  107.         if (seconds <= 0) {
  108.             this.seconds = -1;
  109.         } else {
  110.             this.seconds = seconds;
  111.         }
  112.         servlet = null;
  113.         permanent = false;
  114.     }

  115.     /**
  116.      * Returns a <code>boolean</code> indicating whether the servlet is permanently unavailable. If so, something is
  117.      * wrong with the servlet, and the system administrator must take some corrective action.
  118.      *
  119.      * @return <code>true</code> if the servlet is permanently unavailable; <code>false</code> if the servlet is
  120.      *             available or temporarily unavailable
  121.      */
  122.     public boolean isPermanent() {
  123.         return permanent;
  124.     }

  125.     /**
  126.      * Returns the servlet that is reporting its unavailability.
  127.      *
  128.      * @return the <code>Servlet</code> object that is throwing the <code>UnavailableException</code>
  129.      *
  130.      * @deprecated As of Java Servlet API 2.2, with no replacement.
  131.      */
  132.     @Deprecated
  133.     public Servlet getServlet() {
  134.         return servlet;
  135.     }

  136.     /**
  137.      * Returns the number of seconds the servlet expects to be temporarily unavailable.
  138.      * <p>
  139.      * If this method returns a negative number, the servlet is permanently unavailable or cannot provide an estimate of
  140.      * how long it will be unavailable. No effort is made to correct for the time elapsed since the exception was first
  141.      * reported.
  142.      *
  143.      * @return an integer specifying the number of seconds the servlet will be temporarily unavailable, or a negative
  144.      *             number if the servlet is permanently unavailable or cannot make an estimate
  145.      */
  146.     public int getUnavailableSeconds() {
  147.         return permanent ? -1 : seconds;
  148.     }
  149. }