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 package javax.servlet;
021
022 /**
023 * Defines an exception that a servlet or filter throws to indicate
024 * that it is permanently or temporarily unavailable.
025 *
026 * <p>When a servlet or filter is permanently unavailable, something is wrong
027 * with it, and it cannot handle
028 * requests until some action is taken. For example, a servlet
029 * might be configured incorrectly, or a filter's state may be corrupted.
030 * The component should log both the error and the corrective action
031 * that is needed.
032 *
033 * <p>A servlet or filter is temporarily unavailable if it cannot handle
034 * requests momentarily due to some system-wide problem. For example,
035 * a third-tier server might not be accessible, or there may be
036 * insufficient memory or disk storage to handle requests. A system
037 * administrator may need to take corrective action.
038 *
039 * <p>Servlet containers can safely treat both types of unavailable
040 * exceptions in the same way. However, treating temporary unavailability
041 * effectively makes the servlet container more robust. Specifically,
042 * the servlet container might block requests to the servlet or filter for a period
043 * of time suggested by the exception, rather than rejecting them until
044 * the servlet container restarts.
045 *
046 *
047 * @author Various
048 * @version $Version$
049 *
050 */
051
052 public class UnavailableException
053 extends ServletException {
054
055 private Servlet servlet; // what's unavailable
056 private boolean permanent; // needs admin action?
057 private int seconds; // unavailability estimate
058
059 /**
060 *
061 * @deprecated As of Java Servlet API 2.2, use {@link
062 * #UnavailableException(String)} instead.
063 *
064 * @param servlet the <code>Servlet</code> instance that is
065 * unavailable
066 *
067 * @param msg a <code>String</code> specifying the
068 * descriptive message
069 *
070 */
071
072 public UnavailableException(Servlet servlet, String msg) {
073 super(msg);
074 this.servlet = servlet;
075 permanent = true;
076 }
077
078 /**
079 * @deprecated As of Java Servlet API 2.2, use {@link
080 * #UnavailableException(String, int)} instead.
081 *
082 * @param seconds an integer specifying the number of seconds
083 * the servlet expects to be unavailable; if
084 * zero or negative, indicates that the servlet
085 * can't make an estimate
086 *
087 * @param servlet the <code>Servlet</code> that is unavailable
088 *
089 * @param msg a <code>String</code> specifying the descriptive
090 * message, which can be written to a log file or
091 * displayed for the user.
092 *
093 */
094
095 public UnavailableException(int seconds, Servlet servlet, String msg) {
096 super(msg);
097 this.servlet = servlet;
098 if (seconds <= 0)
099 this.seconds = -1;
100 else
101 this.seconds = seconds;
102 permanent = false;
103 }
104
105 /**
106 *
107 * Constructs a new exception with a descriptive
108 * message indicating that the servlet is permanently
109 * unavailable.
110 *
111 * @param msg a <code>String</code> specifying the
112 * descriptive message
113 *
114 */
115
116 public UnavailableException(String msg) {
117 super(msg);
118
119 permanent = true;
120 }
121
122 /**
123 * Constructs a new exception with a descriptive message
124 * indicating that the servlet is temporarily unavailable
125 * and giving an estimate of how long it will be unavailable.
126 *
127 * <p>In some cases, the servlet cannot make an estimate. For
128 * example, the servlet might know that a server it needs is
129 * not running, but not be able to report how long it will take
130 * to be restored to functionality. This can be indicated with
131 * a negative or zero value for the <code>seconds</code> argument.
132 *
133 * @param msg a <code>String</code> specifying the
134 * descriptive message, which can be written
135 * to a log file or displayed for the user.
136 *
137 * @param seconds an integer specifying the number of seconds
138 * the servlet expects to be unavailable; if
139 * zero or negative, indicates that the servlet
140 * can't make an estimate
141 *
142 */
143
144 public UnavailableException(String msg, int seconds) {
145 super(msg);
146
147 if (seconds <= 0)
148 this.seconds = -1;
149 else
150 this.seconds = seconds;
151
152 permanent = false;
153 }
154
155 /**
156 *
157 * Returns a <code>boolean</code> indicating
158 * whether the servlet is permanently unavailable.
159 * If so, something is wrong with the servlet, and the
160 * system administrator must take some corrective action.
161 *
162 * @return <code>true</code> if the servlet is
163 * permanently unavailable; <code>false</code>
164 * if the servlet is available or temporarily
165 * unavailable
166 *
167 */
168
169 public boolean isPermanent() {
170 return permanent;
171 }
172
173 /**
174 * @deprecated As of Java Servlet API 2.2, with no replacement.
175 *
176 * Returns the servlet that is reporting its unavailability.
177 *
178 * @return the <code>Servlet</code> object that is
179 * throwing the <code>UnavailableException</code>
180 *
181 */
182
183 public Servlet getServlet() {
184 return servlet;
185 }
186
187 /**
188 * Returns the number of seconds the servlet expects to
189 * be temporarily unavailable.
190 *
191 * <p>If this method returns a negative number, the servlet
192 * is permanently unavailable or cannot provide an estimate of
193 * how long it will be unavailable. No effort is
194 * made to correct for the time elapsed since the exception was
195 * first reported.
196 *
197 * @return an integer specifying the number of seconds
198 * the servlet will be temporarily unavailable,
199 * or a negative number if the servlet is permanently
200 * unavailable or cannot make an estimate
201 *
202 */
203
204 public int getUnavailableSeconds() {
205 return permanent ? -1 : seconds;
206 }
207 }