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