1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *  http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  
20  package javax.servlet;
21  
22  /**
23   * Defines an exception that a servlet or filter throws to indicate
24   * that it is permanently or temporarily unavailable. 
25   *
26   * <p>When a servlet or filter is permanently unavailable, something is wrong
27   * with it, and it cannot handle
28   * requests until some action is taken. For example, a servlet
29   * might be configured incorrectly, or a filter's state may be corrupted.
30   * The component should log both the error and the corrective action
31   * that is needed.
32   *
33   * <p>A servlet or filter is temporarily unavailable if it cannot handle
34   * requests momentarily due to some system-wide problem. For example,
35   * a third-tier server might not be accessible, or there may be 
36   * insufficient memory or disk storage to handle requests. A system
37   * administrator may need to take corrective action.
38   *
39   * <p>Servlet containers can safely treat both types of unavailable
40   * exceptions in the same way. However, treating temporary unavailability
41   * effectively makes the servlet container more robust. Specifically,
42   * the servlet container might block requests to the servlet or filter for a period
43   * of time suggested by the exception, rather than rejecting them until
44   * the servlet container restarts.
45   *
46   *
47   * @author 	Various
48   * @version 	$Version$
49   *
50   */
51  
52  public class UnavailableException
53  extends ServletException {
54  
55      private Servlet     servlet;           // what's unavailable
56      private boolean     permanent;         // needs admin action?
57      private int         seconds;           // unavailability estimate
58  
59      /**
60       * 
61       * @deprecated	As of Java Servlet API 2.2, use {@link
62       * 			#UnavailableException(String)} instead.
63       *
64       * @param servlet 	the <code>Servlet</code> instance that is
65       *                  unavailable
66       *
67       * @param msg 	a <code>String</code> specifying the
68       *                  descriptive message
69       *
70       */
71  
72      public UnavailableException(Servlet servlet, String msg) {
73  	super(msg);
74  	this.servlet = servlet;
75  	permanent = true;
76      }
77   
78      /**
79       * @deprecated	As of Java Servlet API 2.2, use {@link
80       *			#UnavailableException(String, int)} instead.
81       *
82       * @param seconds	an integer specifying the number of seconds
83       * 			the servlet expects to be unavailable; if
84       *			zero or negative, indicates that the servlet
85       *			can't make an estimate
86       *
87       * @param servlet	the <code>Servlet</code> that is unavailable
88       * 
89       * @param msg	a <code>String</code> specifying the descriptive 
90       *			message, which can be written to a log file or 
91       *			displayed for the user.
92       *
93       */
94      
95      public UnavailableException(int seconds, Servlet servlet, String msg) {
96  	super(msg);
97  	this.servlet = servlet;
98  	if (seconds <= 0)
99  	    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 }