View Javadoc

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 }