1
2
3 /*
4 * The contents of this file are subject to the terms
5 * of the Common Development and Distribution License
6 * (the "License"). You may not use this file except
7 * in compliance with the License.
8 *
9 * You can obtain a copy of the license at
10 * glassfish/bootstrap/legal/CDDLv1.0.txt or
11 * https://glassfish.dev.java.net/public/CDDLv1.0.html.
12 * See the License for the specific language governing
13 * permissions and limitations under the License.
14 *
15 * When distributing Covered Code, include this CDDL
16 * HEADER in each file and include the License file at
17 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
18 * add the following below this CDDL HEADER, with the
19 * fields enclosed by brackets "[]" replaced with your
20 * own identifying information: Portions Copyright [yyyy]
21 * [name of copyright owner]
22 *
23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
24 *
25 * Portions Copyright Apache Software Foundation.
26 */
27
28 package javax.servlet;
29
30
31 /**
32 * Defines an exception that a servlet or filter throws to indicate
33 * that it is permanently or temporarily unavailable.
34 *
35 * <p>When a servlet or filter is permanently unavailable, something is wrong
36 * with it, and it cannot handle
37 * requests until some action is taken. For example, a servlet
38 * might be configured incorrectly, or a filter's state may be corrupted.
39 * The component should log both the error and the corrective action
40 * that is needed.
41 *
42 * <p>A servlet or filter is temporarily unavailable if it cannot handle
43 * requests momentarily due to some system-wide problem. For example,
44 * a third-tier server might not be accessible, or there may be
45 * insufficient memory or disk storage to handle requests. A system
46 * administrator may need to take corrective action.
47 *
48 * <p>Servlet containers can safely treat both types of unavailable
49 * exceptions in the same way. However, treating temporary unavailability
50 * effectively makes the servlet container more robust. Specifically,
51 * the servlet container might block requests to the servlet or filter for a period
52 * of time suggested by the exception, rather than rejecting them until
53 * the servlet container restarts.
54 *
55 *
56 * @author Various
57 *
58 */
59
60 public class UnavailableException
61 extends ServletException {
62
63 private Servlet servlet; // what's unavailable
64 private boolean permanent; // needs admin action?
65 private int seconds; // unavailability estimate
66
67 /**
68 *
69 * @deprecated As of Java Servlet API 2.2, use {@link
70 * #UnavailableException(String)} instead.
71 *
72 * @param servlet the <code>Servlet</code> instance that is
73 * unavailable
74 *
75 * @param msg a <code>String</code> specifying the
76 * descriptive message
77 *
78 */
79
80 public UnavailableException(Servlet servlet, String msg) {
81 super(msg);
82 this.servlet = servlet;
83 permanent = true;
84 }
85
86 /**
87 * @deprecated As of Java Servlet API 2.2, use {@link
88 * #UnavailableException(String, int)} instead.
89 *
90 * @param seconds an integer specifying the number of seconds
91 * the servlet expects to be unavailable; if
92 * zero or negative, indicates that the servlet
93 * can't make an estimate
94 *
95 * @param servlet the <code>Servlet</code> that is unavailable
96 *
97 * @param msg a <code>String</code> specifying the descriptive
98 * message, which can be written to a log file or
99 * displayed for the user.
100 *
101 */
102
103 public UnavailableException(int seconds, Servlet servlet, String msg) {
104 super(msg);
105 this.servlet = servlet;
106 if (seconds <= 0)
107 this.seconds = -1;
108 else
109 this.seconds = seconds;
110 permanent = false;
111 }
112
113 /**
114 *
115 * Constructs a new exception with a descriptive
116 * message indicating that the servlet is permanently
117 * unavailable.
118 *
119 * @param msg a <code>String</code> specifying the
120 * descriptive message
121 *
122 */
123
124 public UnavailableException(String msg) {
125 super(msg);
126
127 permanent = true;
128 }
129
130 /**
131 * Constructs a new exception with a descriptive message
132 * indicating that the servlet is temporarily unavailable
133 * and giving an estimate of how long it will be unavailable.
134 *
135 * <p>In some cases, the servlet cannot make an estimate. For
136 * example, the servlet might know that a server it needs is
137 * not running, but not be able to report how long it will take
138 * to be restored to functionality. This can be indicated with
139 * a negative or zero value for the <code>seconds</code> argument.
140 *
141 * @param msg a <code>String</code> specifying the
142 * descriptive message, which can be written
143 * to a log file or displayed for the user.
144 *
145 * @param seconds an integer specifying the number of seconds
146 * the servlet expects to be unavailable; if
147 * zero or negative, indicates that the servlet
148 * can't make an estimate
149 *
150 */
151
152 public UnavailableException(String msg, int seconds) {
153 super(msg);
154
155 if (seconds <= 0)
156 this.seconds = -1;
157 else
158 this.seconds = seconds;
159
160 permanent = false;
161 }
162
163 /**
164 *
165 * Returns a <code>boolean</code> indicating
166 * whether the servlet is permanently unavailable.
167 * If so, something is wrong with the servlet, and the
168 * system administrator must take some corrective action.
169 *
170 * @return <code>true</code> if the servlet is
171 * permanently unavailable; <code>false</code>
172 * if the servlet is available or temporarily
173 * unavailable
174 *
175 */
176
177 public boolean isPermanent() {
178 return permanent;
179 }
180
181 /**
182 * @deprecated As of Java Servlet API 2.2, with no replacement.
183 *
184 * Returns the servlet that is reporting its unavailability.
185 *
186 * @return the <code>Servlet</code> object that is
187 * throwing the <code>UnavailableException</code>
188 *
189 */
190
191 public Servlet getServlet() {
192 return servlet;
193 }
194
195 /**
196 * Returns the number of seconds the servlet expects to
197 * be temporarily unavailable.
198 *
199 * <p>If this method returns a negative number, the servlet
200 * is permanently unavailable or cannot provide an estimate of
201 * how long it will be unavailable. No effort is
202 * made to correct for the time elapsed since the exception was
203 * first reported.
204 *
205 * @return an integer specifying the number of seconds
206 * the servlet will be temporarily unavailable,
207 * or a negative number if the servlet is permanently
208 * unavailable or cannot make an estimate
209 *
210 */
211
212 public int getUnavailableSeconds() {
213 return permanent ? -1 : seconds;
214 }
215 }