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    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet;
027    
028    /**
029     * Defines an exception that a servlet or filter throws to indicate
030     * that it is permanently or temporarily unavailable.
031     *
032     * <p>When a servlet or filter is permanently unavailable, something is wrong
033     * with it, and it cannot handle
034     * requests until some action is taken. For example, a servlet
035     * might be configured incorrectly, or a filter's state may be corrupted.
036     * The component should log both the error and the corrective action
037     * that is needed.
038     *
039     * <p>A servlet or filter is temporarily unavailable if it cannot handle
040     * requests momentarily due to some system-wide problem. For example,
041     * a third-tier server might not be accessible, or there may be
042     * insufficient memory or disk storage to handle requests. A system
043     * administrator may need to take corrective action.
044     *
045     * <p>Servlet containers can safely treat both types of unavailable
046     * exceptions in the same way. However, treating temporary unavailability
047     * effectively makes the servlet container more robust. Specifically,
048     * the servlet container might block requests to the servlet or filter for a period
049     * of time suggested by the exception, rather than rejecting them until
050     * the servlet container restarts.
051     *
052     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
053     */
054    public class UnavailableException extends ServletException {
055        /**
056         * What is unavailable
057         */
058        private Servlet servlet;
059        /**
060         * Does this need an admin action?
061         */
062        private boolean permanent;
063        /**
064         * Estimate of how long the resource will be unavaile.
065         */
066        private int seconds;
067    
068        /**
069         * @deprecated As of Java Servlet API 2.2, use {@link
070         * #UnavailableException(String)} instead.
071         *
072         * @param servlet the <code>Servlet</code> instance that is unavailable
073         *
074         * @param msg a <code>String</code> specifying the descriptive message
075         */
076        public UnavailableException(Servlet servlet, String msg) {
077            super(msg);
078            this.servlet = servlet;
079            permanent = true;
080        }
081    
082        /**
083         * @deprecated As of Java Servlet API 2.2, use {@link
084         * #UnavailableException(String, int)} instead.
085         *
086         * @param seconds an integer specifying the number of seconds
087         * the servlet expects to be unavailable; if zero or negative,
088         * indicates that the servlet can't make an estimate
089         *
090         * @param servlet the <code>Servlet</code> that is unavailable
091         *
092         * @param msg a <code>String</code> specifying the descriptive
093         * message, which can be written to a log file or displayed for
094         * the user.
095         */
096        public UnavailableException(int seconds, Servlet servlet, String msg) {
097            super(msg);
098            this.servlet = servlet;
099            if (seconds <= 0) {
100                this.seconds = -1;
101            } else {
102                this.seconds = seconds;
103            }
104            permanent = false;
105        }
106    
107        /**
108         * Constructs a new exception with a descriptive
109         * message indicating that the servlet is permanently
110         * unavailable.
111         *
112         * @param msg a <code>String</code> specifying the descriptive message
113         */
114        public UnavailableException(String msg) {
115            super(msg);
116    
117            permanent = true;
118        }
119    
120        /**
121         * Constructs a new exception with a descriptive message
122         * indicating that the servlet is temporarily unavailable
123         * and giving an estimate of how long it will be unavailable.
124         *
125         * <p>In some cases, the servlet cannot make an estimate. For
126         * example, the servlet might know that a server it needs is
127         * not running, but not be able to report how long it will take
128         * to be restored to functionality. This can be indicated with
129         * a negative or zero value for the <code>seconds</code> argument.
130         *
131         * @param msg a <code>String</code> specifying the descriptive
132         * message, which can be written to a log file or displayed for
133         * the user.
134         *
135         * @param seconds an integer specifying the number of seconds
136         * the servlet expects to be unavailable; if zero or negative,
137         * indicates that the servlet can't make an estimate
138         */
139        public UnavailableException(String msg, int seconds) {
140            super(msg);
141    
142            if (seconds <= 0) {
143                this.seconds = -1;
144            } else {
145                this.seconds = seconds;
146            }
147            permanent = false;
148        }
149    
150        /**
151         * Returns a <code>boolean</code> indicating
152         * whether the servlet is permanently unavailable.
153         * If so, something is wrong with the servlet, and the
154         * system administrator must take some corrective action.
155         *
156         * @return <code>true</code> if the servlet is
157         * permanently unavailable; <code>false</code>
158         * if the servlet is available or temporarily unavailable
159         */
160        public boolean isPermanent() {
161            return permanent;
162        }
163    
164        /**
165         * @deprecated As of Java Servlet API 2.2, with no replacement.
166         *
167         * Returns the servlet that is reporting its unavailability.
168         *
169         * @return the <code>Servlet</code> object that is
170         * throwing the <code>UnavailableException</code>
171         */
172        public Servlet getServlet() {
173            return servlet;
174        }
175    
176        /**
177         * Returns the number of seconds the servlet expects to
178         * be temporarily unavailable.
179         *
180         * <p>If this method returns a negative number, the servlet
181         * is permanently unavailable or cannot provide an estimate of
182         * how long it will be unavailable. No effort is
183         * made to correct for the time elapsed since the exception was
184         * first reported.
185         *
186         * @return an integer specifying the number of seconds
187         * the servlet will be temporarily unavailable, or a negative
188         * number if the servlet is permanently unavailable or cannot
189         * make an estimate
190         */
191        public int getUnavailableSeconds() {
192            return permanent ? -1 : seconds;
193        }
194    }