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 }