001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.servlet;
021
022 /**
023 * Defines an exception that a servlet or filter throws to indicate
024 * that it is permanently or temporarily unavailable.
025 * <p/>
026 * <p>When a servlet or filter is permanently unavailable, something is wrong
027 * with it, and it cannot handle
028 * requests until some action is taken. For example, a servlet
029 * might be configured incorrectly, or a filter's state may be corrupted.
030 * The component should log both the error and the corrective action
031 * that is needed.
032 * <p/>
033 * <p>A servlet or filter is temporarily unavailable if it cannot handle
034 * requests momentarily due to some system-wide problem. For example,
035 * a third-tier server might not be accessible, or there may be
036 * insufficient memory or disk storage to handle requests. A system
037 * administrator may need to take corrective action.
038 * <p/>
039 * <p>Servlet containers can safely treat both types of unavailable
040 * exceptions in the same way. However, treating temporary unavailability
041 * effectively makes the servlet container more robust. Specifically,
042 * the servlet container might block requests to the servlet or filter for a period
043 * of time suggested by the exception, rather than rejecting them until
044 * the servlet container restarts.
045 *
046 * @version $Rev: 835965 $ $Date: 2009-11-13 14:40:44 -0500 (Fri, 13 Nov 2009) $
047 */
048
049 public class UnavailableException extends ServletException {
050
051 private final Servlet servlet; // what's unavailable
052 private final boolean permanent; // needs admin action?
053 private final int seconds; // unavailability estimate
054
055 /**
056 * @param servlet the <code>Servlet</code> instance that is
057 * unavailable
058 * @param msg a <code>String</code> specifying the
059 * descriptive message
060 * @deprecated As of Java Servlet API 2.2, use {@link
061 * #UnavailableException(String)} instead.
062 */
063 public UnavailableException(Servlet servlet, String msg) {
064 super(msg);
065 this.servlet = servlet;
066 permanent = true;
067 seconds = -1;
068 }
069
070 /**
071 * @param seconds an integer specifying the number of seconds
072 * the servlet expects to be unavailable; if
073 * zero or negative, indicates that the servlet
074 * can't make an estimate
075 * @param servlet the <code>Servlet</code> that is unavailable
076 * @param msg a <code>String</code> specifying the descriptive
077 * message, which can be written to a log file or
078 * displayed for the user.
079 * @deprecated As of Java Servlet API 2.2, use {@link
080 * #UnavailableException(String, int)} instead.
081 */
082 public UnavailableException(int seconds, Servlet servlet, String msg) {
083 super(msg);
084 this.servlet = servlet;
085 if (seconds <= 0)
086 this.seconds = -1;
087 else
088 this.seconds = seconds;
089 permanent = false;
090 }
091
092 /**
093 * Constructs a new exception with a descriptive
094 * message indicating that the servlet is permanently
095 * unavailable.
096 *
097 * @param msg a <code>String</code> specifying the
098 * descriptive message
099 */
100 public UnavailableException(String msg) {
101 super(msg);
102 servlet = null;
103 permanent = true;
104 seconds = -1;
105 }
106
107 /**
108 * Constructs a new exception with a descriptive message
109 * indicating that the servlet is temporarily unavailable
110 * and giving an estimate of how long it will be unavailable.
111 * <p/>
112 * <p>In some cases, the servlet cannot make an estimate. For
113 * example, the servlet might know that a server it needs is
114 * not running, but not be able to report how long it will take
115 * to be restored to functionality. This can be indicated with
116 * a negative or zero value for the <code>seconds</code> argument.
117 *
118 * @param msg a <code>String</code> specifying the
119 * descriptive message, which can be written
120 * to a log file or displayed for the user.
121 * @param seconds an integer specifying the number of seconds
122 * the servlet expects to be unavailable; if
123 * zero or negative, indicates that the servlet
124 * can't make an estimate
125 */
126 public UnavailableException(String msg, int seconds) {
127 super(msg);
128 servlet = null;
129 if (seconds <= 0)
130 this.seconds = -1;
131 else
132 this.seconds = seconds;
133
134 permanent = false;
135 }
136
137 /**
138 * Returns a <code>boolean</code> indicating
139 * whether the servlet is permanently unavailable.
140 * If so, something is wrong with the servlet, and the
141 * system administrator must take some corrective action.
142 *
143 * @return <code>true</code> if the servlet is
144 * permanently unavailable; <code>false</code>
145 * if the servlet is available or temporarily
146 * unavailable
147 */
148 public boolean isPermanent() {
149 return permanent;
150 }
151
152 /**
153 * @deprecated As of Java Servlet API 2.2, with no replacement.
154 * <p/>
155 * Returns the servlet that is reporting its unavailability.
156 * @return the <code>Servlet</code> object that is
157 * throwing the <code>UnavailableException</code>
158 */
159 public Servlet getServlet() {
160 return servlet;
161 }
162
163 /**
164 * Returns the number of seconds the servlet expects to
165 * be temporarily unavailable.
166 * <p/>
167 * <p>If this method returns a negative number, the servlet
168 * is permanently unavailable or cannot provide an estimate of
169 * how long it will be unavailable. No effort is
170 * made to correct for the time elapsed since the exception was
171 * first reported.
172 *
173 * @return an integer specifying the number of seconds
174 * the servlet will be temporarily unavailable,
175 * or a negative number if the servlet is permanently
176 * unavailable or cannot make an estimate
177 */
178 public int getUnavailableSeconds() {
179 return permanent ? -1 : seconds;
180 }
181
182 }