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 }