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