1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * 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
19
20
21
22
23
24 package javax.servlet;
25
26 /**
27 * Defines an exception that a servlet or filter throws to indicate
28 * that it is permanently or temporarily unavailable.
29 *
30 * <p>When a servlet or filter is permanently unavailable, something is wrong
31 * with it, and it cannot handle
32 * requests until some action is taken. For example, a servlet
33 * might be configured incorrectly, or a filter's state may be corrupted.
34 * The component should log both the error and the corrective action
35 * that is needed.
36 *
37 * <p>A servlet or filter is temporarily unavailable if it cannot handle
38 * requests momentarily due to some system-wide problem. For example,
39 * a third-tier server might not be accessible, or there may be
40 * insufficient memory or disk storage to handle requests. A system
41 * administrator may need to take corrective action.
42 *
43 * <p>Servlet containers can safely treat both types of unavailable
44 * exceptions in the same way. However, treating temporary unavailability
45 * effectively makes the servlet container more robust. Specifically,
46 * the servlet container might block requests to the servlet or filter for a period
47 * of time suggested by the exception, rather than rejecting them until
48 * the servlet container restarts.
49 *
50 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
51 */
52 public class UnavailableException extends ServletException {
53 /**
54 * What is unavailable
55 */
56 private Servlet servlet;
57 /**
58 * Does this need an admin action?
59 */
60 private boolean permanent;
61 /**
62 * Estimate of how long the resource will be unavaile.
63 */
64 private int seconds;
65
66 /**
67 * @deprecated As of Java Servlet API 2.2, use {@link
68 * #UnavailableException(String)} instead.
69 *
70 * @param servlet the <code>Servlet</code> instance that is unavailable
71 *
72 * @param msg a <code>String</code> specifying the descriptive message
73 */
74 public UnavailableException(Servlet servlet, String msg) {
75 super(msg);
76 this.servlet = servlet;
77 permanent = true;
78 }
79
80 /**
81 * @deprecated As of Java Servlet API 2.2, use {@link
82 * #UnavailableException(String, int)} instead.
83 *
84 * @param seconds an integer specifying the number of seconds
85 * the servlet expects to be unavailable; if zero or negative,
86 * indicates that the servlet can't make an estimate
87 *
88 * @param servlet the <code>Servlet</code> that is unavailable
89 *
90 * @param msg a <code>String</code> specifying the descriptive
91 * message, which can be written to a log file or displayed for
92 * the user.
93 */
94 public UnavailableException(int seconds, Servlet servlet, String msg) {
95 super(msg);
96 this.servlet = servlet;
97 if (seconds <= 0) {
98 this.seconds = -1;
99 } 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 }