001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 //
021 // This source code implements specifications defined by the Java
022 // Community Process. In order to remain compliant with the specification
023 // DO NOT add / change / or delete method signatures!
024 //
025
026 package javax.servlet;
027
028 /**
029 * Defines an exception that a servlet or filter throws to indicate
030 * that it is permanently or temporarily unavailable.
031 *
032 * <p>When a servlet or filter is permanently unavailable, something is wrong
033 * with it, and it cannot handle
034 * requests until some action is taken. For example, a servlet
035 * might be configured incorrectly, or a filter's state may be corrupted.
036 * The component should log both the error and the corrective action
037 * that is needed.
038 *
039 * <p>A servlet or filter is temporarily unavailable if it cannot handle
040 * requests momentarily due to some system-wide problem. For example,
041 * a third-tier server might not be accessible, or there may be
042 * insufficient memory or disk storage to handle requests. A system
043 * administrator may need to take corrective action.
044 *
045 * <p>Servlet containers can safely treat both types of unavailable
046 * exceptions in the same way. However, treating temporary unavailability
047 * effectively makes the servlet container more robust. Specifically,
048 * the servlet container might block requests to the servlet or filter for a period
049 * of time suggested by the exception, rather than rejecting them until
050 * the servlet container restarts.
051 *
052 * @version $Rev: 467553 $ $Date: 2006-10-24 21:01:51 -0700 (Tue, 24 Oct 2006) $
053 */
054 public class UnavailableException extends ServletException {
055 /**
056 * What is unavailable
057 */
058 private Servlet servlet;
059 /**
060 * Does this need an admin action?
061 */
062 private boolean permanent;
063 /**
064 * Estimate of how long the resource will be unavaile.
065 */
066 private int seconds;
067
068 /**
069 * @deprecated As of Java Servlet API 2.2, use {@link
070 * #UnavailableException(String)} instead.
071 *
072 * @param servlet the <code>Servlet</code> instance that is unavailable
073 *
074 * @param msg a <code>String</code> specifying the descriptive message
075 */
076 public UnavailableException(Servlet servlet, String msg) {
077 super(msg);
078 this.servlet = servlet;
079 permanent = true;
080 }
081
082 /**
083 * @deprecated As of Java Servlet API 2.2, use {@link
084 * #UnavailableException(String, int)} instead.
085 *
086 * @param seconds an integer specifying the number of seconds
087 * the servlet expects to be unavailable; if zero or negative,
088 * indicates that the servlet can't make an estimate
089 *
090 * @param servlet the <code>Servlet</code> that is unavailable
091 *
092 * @param msg a <code>String</code> specifying the descriptive
093 * message, which can be written to a log file or displayed for
094 * the user.
095 */
096 public UnavailableException(int seconds, Servlet servlet, String msg) {
097 super(msg);
098 this.servlet = servlet;
099 if (seconds <= 0) {
100 this.seconds = -1;
101 } else {
102 this.seconds = seconds;
103 }
104 permanent = false;
105 }
106
107 /**
108 * Constructs a new exception with a descriptive
109 * message indicating that the servlet is permanently
110 * unavailable.
111 *
112 * @param msg a <code>String</code> specifying the descriptive message
113 */
114 public UnavailableException(String msg) {
115 super(msg);
116
117 permanent = true;
118 }
119
120 /**
121 * Constructs a new exception with a descriptive message
122 * indicating that the servlet is temporarily unavailable
123 * and giving an estimate of how long it will be unavailable.
124 *
125 * <p>In some cases, the servlet cannot make an estimate. For
126 * example, the servlet might know that a server it needs is
127 * not running, but not be able to report how long it will take
128 * to be restored to functionality. This can be indicated with
129 * a negative or zero value for the <code>seconds</code> argument.
130 *
131 * @param msg a <code>String</code> specifying the descriptive
132 * message, which can be written to a log file or displayed for
133 * the user.
134 *
135 * @param seconds an integer specifying the number of seconds
136 * the servlet expects to be unavailable; if zero or negative,
137 * indicates that the servlet can't make an estimate
138 */
139 public UnavailableException(String msg, int seconds) {
140 super(msg);
141
142 if (seconds <= 0) {
143 this.seconds = -1;
144 } else {
145 this.seconds = seconds;
146 }
147 permanent = false;
148 }
149
150 /**
151 * Returns a <code>boolean</code> indicating
152 * whether the servlet is permanently unavailable.
153 * If so, something is wrong with the servlet, and the
154 * system administrator must take some corrective action.
155 *
156 * @return <code>true</code> if the servlet is
157 * permanently unavailable; <code>false</code>
158 * if the servlet is available or temporarily unavailable
159 */
160 public boolean isPermanent() {
161 return permanent;
162 }
163
164 /**
165 * @deprecated As of Java Servlet API 2.2, with no replacement.
166 *
167 * Returns the servlet that is reporting its unavailability.
168 *
169 * @return the <code>Servlet</code> object that is
170 * throwing the <code>UnavailableException</code>
171 */
172 public Servlet getServlet() {
173 return servlet;
174 }
175
176 /**
177 * Returns the number of seconds the servlet expects to
178 * be temporarily unavailable.
179 *
180 * <p>If this method returns a negative number, the servlet
181 * is permanently unavailable or cannot provide an estimate of
182 * how long it will be unavailable. No effort is
183 * made to correct for the time elapsed since the exception was
184 * first reported.
185 *
186 * @return an integer specifying the number of seconds
187 * the servlet will be temporarily unavailable, or a negative
188 * number if the servlet is permanently unavailable or cannot
189 * make an estimate
190 */
191 public int getUnavailableSeconds() {
192 return permanent ? -1 : seconds;
193 }
194 }