KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > UnavailableException


1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 package javax.servlet;
19
20
21 /**
22  * Defines an exception that a servlet or filter throws to indicate
23  * that it is permanently or temporarily unavailable.
24  *
25  * <p>When a servlet or filter is permanently unavailable, something is wrong
26  * with it, and it cannot handle
27  * requests until some action is taken. For example, a servlet
28  * might be configured incorrectly, or a filter's state may be corrupted.
29  * The component should log both the error and the corrective action
30  * that is needed.
31  *
32  * <p>A servlet or filter is temporarily unavailable if it cannot handle
33  * requests momentarily due to some system-wide problem. For example,
34  * a third-tier server might not be accessible, or there may be
35  * insufficient memory or disk storage to handle requests. A system
36  * administrator may need to take corrective action.
37  *
38  * <p>Servlet containers can safely treat both types of unavailable
39  * exceptions in the same way. However, treating temporary unavailability
40  * effectively makes the servlet container more robust. Specifically,
41  * the servlet container might block requests to the servlet or filter for a period
42  * of time suggested by the exception, rather than rejecting them until
43  * the servlet container restarts.
44  *
45  *
46  * @author Various
47  * @version $Version$
48  *
49  */
50
51 public class UnavailableException
52 extends ServletException JavaDoc {
53
54     private Servlet JavaDoc servlet; // what's unavailable
55 private boolean permanent; // needs admin action?
56 private int seconds; // unavailability estimate
57
58     /**
59      *
60      * @deprecated As of Java Servlet API 2.2, use {@link
61      * #UnavailableException(String)} instead.
62      *
63      * @param servlet the <code>Servlet</code> instance that is
64      * unavailable
65      *
66      * @param msg a <code>String</code> specifying the
67      * descriptive message
68      *
69      */
70
71     public UnavailableException(Servlet JavaDoc servlet, String JavaDoc msg) {
72     super(msg);
73     this.servlet = servlet;
74     permanent = true;
75     }
76  
77     /**
78      * @deprecated As of Java Servlet API 2.2, use {@link
79      * #UnavailableException(String, int)} instead.
80      *
81      * @param seconds an integer specifying the number of seconds
82      * the servlet expects to be unavailable; if
83      * zero or negative, indicates that the servlet
84      * can't make an estimate
85      *
86      * @param servlet the <code>Servlet</code> that is unavailable
87      *
88      * @param msg a <code>String</code> specifying the descriptive
89      * message, which can be written to a log file or
90      * displayed for the user.
91      *
92      */
93     
94     public UnavailableException(int seconds, Servlet JavaDoc servlet, String JavaDoc msg) {
95     super(msg);
96     this.servlet = servlet;
97     if (seconds <= 0)
98         this.seconds = -1;
99     else
100         this.seconds = seconds;
101     permanent = false;
102     }
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
111      * descriptive message
112      *
113      */
114
115     public UnavailableException(String JavaDoc msg) {
116     super(msg);
117
118     permanent = true;
119     }
120
121     /**
122      * Constructs a new exception with a descriptive message
123      * indicating that the servlet is temporarily unavailable
124      * and giving an estimate of how long it will be unavailable.
125      *
126      * <p>In some cases, the servlet cannot make an estimate. For
127      * example, the servlet might know that a server it needs is
128      * not running, but not be able to report how long it will take
129      * to be restored to functionality. This can be indicated with
130      * a negative or zero value for the <code>seconds</code> argument.
131      *
132      * @param msg a <code>String</code> specifying the
133      * descriptive message, which can be written
134      * to a log file or displayed for the user.
135      *
136      * @param seconds an integer specifying the number of seconds
137      * the servlet expects to be unavailable; if
138      * zero or negative, indicates that the servlet
139      * can't make an estimate
140      *
141      */
142     
143     public UnavailableException(String JavaDoc msg, int seconds) {
144     super(msg);
145
146     if (seconds <= 0)
147         this.seconds = -1;
148     else
149         this.seconds = seconds;
150
151     permanent = false;
152     }
153
154     /**
155      *
156      * Returns a <code>boolean</code> indicating
157      * whether the servlet is permanently unavailable.
158      * If so, something is wrong with the servlet, and the
159      * system administrator must take some corrective action.
160      *
161      * @return <code>true</code> if the servlet is
162      * permanently unavailable; <code>false</code>
163      * if the servlet is available or temporarily
164      * unavailable
165      *
166      */
167      
168     public boolean isPermanent() {
169     return permanent;
170     }
171   
172     /**
173      * @deprecated As of Java Servlet API 2.2, with no replacement.
174      *
175      * Returns the servlet that is reporting its unavailability.
176      *
177      * @return the <code>Servlet</code> object that is
178      * throwing the <code>UnavailableException</code>
179      *
180      */
181      
182     public Servlet JavaDoc getServlet() {
183     return servlet;
184     }
185
186     /**
187      * Returns the number of seconds the servlet expects to
188      * be temporarily unavailable.
189      *
190      * <p>If this method returns a negative number, the servlet
191      * is permanently unavailable or cannot provide an estimate of
192      * how long it will be unavailable. No effort is
193      * made to correct for the time elapsed since the exception was
194      * first reported.
195      *
196      * @return an integer specifying the number of seconds
197      * the servlet will be temporarily unavailable,
198      * or a negative number if the servlet is permanently
199      * unavailable or cannot make an estimate
200      *
201      */
202      
203     public int getUnavailableSeconds() {
204     return permanent ? -1 : seconds;
205     }
206 }
207
Popular Tags