lib/servlet-api/javax/servlet/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
  18 package javax.servlet;
  19
  20 /**
  21  * Defines an exception that a servlet or filter throws to indicate that it is
  22  * permanently or temporarily unavailable.
  23  * <p>
  24  * When a servlet or filter is permanently unavailable, something is wrong with
  25  * it, and it cannot handle requests until some action is taken. For example, a
  26  * servlet might be configured incorrectly, or a filter's state may be
  27  * corrupted. The component should log both the error and the corrective action
  28  * that is needed.
  29  * <p>
  30  * A servlet or filter is temporarily unavailable if it cannot handle requests
  31  * momentarily due to some system-wide problem. For example, a third-tier server
  32  * might not be accessible, or there may be insufficient memory or disk storage
  33  * to handle requests. A system administrator may need to take corrective
  34  * action.
  35  * <p>
  36  * Servlet containers can safely treat both types of unavailable exceptions in
  37  * the same way. However, treating temporary unavailability effectively makes
  38  * the servlet container more robust. Specifically, the servlet container might
  39  * block requests to the servlet or filter for a period of time suggested by the
  40  * exception, rather than rejecting them until the servlet container restarts.
  41  */
  42 public class UnavailableException extends ServletException {
  43
  44     private static final long serialVersionUID = 1L;
  45
  46     private final Servlet servlet; // what's unavailable
  47     private final boolean permanent; // needs admin action?
  48     private final int seconds; // unavailability estimate
  49
  50     /**
  51      * @param servlet
  52      *            the <code>Servlet</code> instance that is unavailable
  53      * @param msg
  54      *            a <code>String</code> specifying the descriptive message
  55      * @deprecated As of Java Servlet API 2.2, use
  56      *             {@link #UnavailableException(String)} instead.
  57      */
  58     @SuppressWarnings("dep-ann")
  59     // Spec API does not use @Deprecated
  60     public UnavailableException(Servlet servlet, String msg) {
  61         super(msg);
  62         this.servlet = servlet;
  63         permanent = true;
  64         this.seconds = 0;
  65     }
  66
  67     /**
  68      * @param seconds
  69      *            an integer specifying the number of seconds the servlet
  70      *            expects to be unavailable; if zero or negative, indicates that
  71      *            the servlet can't make an estimate
  72      * @param servlet
  73      *            the <code>Servlet</code> that is unavailable
  74      * @param msg
  75      *            a <code>String</code> specifying the descriptive message,
  76      *            which can be written to a log file or displayed for the user.
  77      * @deprecated As of Java Servlet API 2.2, use
  78      *             {@link #UnavailableException(String, int)} instead.
  79      */
  80     @SuppressWarnings("dep-ann")
  81     // Spec API does not use @Deprecated
  82     public UnavailableException(int seconds, Servlet servlet, String msg) {
  83         super(msg);
  84         this.servlet = servlet;
  85         if (seconds <= 0)
  86             this.seconds = -1;
  87         else
  88             this.seconds = seconds;
  89         permanent = false;
  90     }
  91
  92     /**
  93      * Constructs a new exception with a descriptive message indicating that the
  94      * servlet is permanently unavailable.
  95      *
  96      * @param msg
  97      *            a <code>String</code> specifying the descriptive message
  98      */
  99     public UnavailableException(String msg) {
 100         super(msg);
 101         seconds = 0;
 102         servlet = null;
 103         permanent = true;
 104     }
 105
 106     /**
 107      * Constructs a new exception with a descriptive message indicating that the
 108      * servlet is temporarily unavailable and giving an estimate of how long it
 109      * will be unavailable.
 110      * <p>
 111      * In some cases, the servlet cannot make an estimate. For example, the
 112      * servlet might know that a server it needs is not running, but not be able
 113      * to report how long it will take to be restored to functionality. This can
 114      * be indicated with a negative or zero value for the <code>seconds</code>
 115      * argument.
 116      *
 117      * @param msg
 118      *            a <code>String</code> specifying the descriptive message,
 119      *            which can be written to a log file or displayed for the user.
 120      * @param seconds
 121      *            an integer specifying the number of seconds the servlet
 122      *            expects to be unavailable; if zero or negative, indicates that
 123      *            the servlet can't make an estimate
 124      */
 125     public UnavailableException(String msg, int seconds) {
 126         super(msg);
 127
 128         if (seconds <= 0)
 129             this.seconds = -1;
 130         else
 131             this.seconds = seconds;
 132         servlet = null;
 133         permanent = false;
 134     }
 135
 136     /**
 137      * Returns a <code>boolean</code> indicating whether the servlet is
 138      * permanently unavailable. If so, something is wrong with the servlet, and
 139      * the system administrator must take some corrective action.
 140      *
 141      * @return <code>true</code> if the servlet is permanently unavailable;
 142      *         <code>false</code> if the servlet is available or temporarily
 143      *         unavailable
 144      */
 145     public boolean isPermanent() {
 146         return permanent;
 147     }
 148
 149     /**
 150      * Returns the servlet that is reporting its unavailability.
 151      *
 152      * @return the <code>Servlet</code> object that is throwing the
 153      *         <code>UnavailableException</code>
 154      * @deprecated As of Java Servlet API 2.2, with no replacement.
 155      */
 156     @SuppressWarnings("dep-ann")
 157     // Spec API does not use @Deprecated
 158     public Servlet getServlet() {
 159         return servlet;
 160     }
 161
 162     /**
 163      * Returns the number of seconds the servlet expects to be temporarily
 164      * unavailable.
 165      * <p>
 166      * If this method returns a negative number, the servlet is permanently
 167      * unavailable or cannot provide an estimate of how long it will be
 168      * unavailable. No effort is made to correct for the time elapsed since the
 169      * exception was first reported.
 170      *
 171      * @return an integer specifying the number of seconds the servlet will be
 172      *         temporarily unavailable, or a negative number if the servlet is
 173      *         permanently unavailable or cannot make an estimate
 174      */
 175     public int getUnavailableSeconds() {
 176         return permanent ? -1 : seconds;
 177     }
 178 }