1. /*
  2. * The Apache Software License, Version 1.1
  3. *
  4. * Copyright (c) 1999 The Apache Software Foundation. All rights
  5. * reserved.
  6. *
  7. * Redistribution and use in source and binary forms, with or without
  8. * modification, are permitted provided that the following conditions
  9. * are met:
  10. *
  11. * 1. Redistributions of source code must retain the above copyright
  12. * notice, this list of conditions and the following disclaimer.
  13. *
  14. * 2. Redistributions in binary form must reproduce the above copyright
  15. * notice, this list of conditions and the following disclaimer in
  16. * the documentation and/or other materials provided with the
  17. * distribution.
  18. *
  19. * 3. The end-user documentation included with the redistribution, if
  20. * any, must include the following acknowlegement:
  21. * "This product includes software developed by the
  22. * Apache Software Foundation (http://www.apache.org/)."
  23. * Alternately, this acknowlegement may appear in the software itself,
  24. * if and wherever such third-party acknowlegements normally appear.
  25. *
  26. * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  27. * Foundation" must not be used to endorse or promote products derived
  28. * from this software without prior written permission. For written
  29. * permission, please contact apache@apache.org.
  30. *
  31. * 5. Products derived from this software may not be called "Apache"
  32. * nor may "Apache" appear in their names without prior written
  33. * permission of the Apache Group.
  34. *
  35. * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38. * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39. * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42. * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44. * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46. * SUCH DAMAGE.
  47. * ====================================================================
  48. *
  49. * This software consists of voluntary contributions made by many
  50. * individuals on behalf of the Apache Software Foundation. For more
  51. * information on the Apache Software Foundation, please see
  52. * <http://www.apache.org/>.
  53. *
  54. * ====================================================================
  55. *
  56. * This source code implements specifications defined by the Java
  57. * Community Process. In order to remain compliant with the specification
  58. * DO NOT add / change / or delete method signatures!
  59. */
  60. package javax.servlet;
  61. /**
  62. * Defines an exception that a servlet or filter throws to indicate
  63. * that it is permanently or temporarily unavailable.
  64. *
  65. * <p>When a servlet or filter is permanently unavailable, something is wrong
  66. * with the it, and it cannot handle
  67. * requests until some action is taken. For example, a servlet
  68. * might be configured incorrectly, or a filter's state may be corrupted.
  69. * The component should log both the error and the corrective action
  70. * that is needed.
  71. *
  72. * <p>A servlet or filter is temporarily unavailable if it cannot handle
  73. * requests momentarily due to some system-wide problem. For example,
  74. * a third-tier server might not be accessible, or there may be
  75. * insufficient memory or disk storage to handle requests. A system
  76. * administrator may need to take corrective action.
  77. *
  78. * <p>Servlet containers can safely treat both types of unavailable
  79. * exceptions in the same way. However, treating temporary unavailability
  80. * effectively makes the servlet container more robust. Specifically,
  81. * the servlet container might block requests to the servlet or filter for a period
  82. * of time suggested by the exception, rather than rejecting them until
  83. * the servlet container restarts.
  84. *
  85. *
  86. * @author Various
  87. * @version $Version$
  88. *
  89. */
  90. public class UnavailableException
  91. extends ServletException {
  92. private Servlet servlet; // what's unavailable
  93. private boolean permanent; // needs admin action?
  94. private int seconds; // unavailability estimate
  95. /**
  96. *
  97. * @deprecated As of Java Servlet API 2.2, use {@link
  98. * #UnavailableException(String)} instead.
  99. *
  100. * @param servlet the <code>Servlet</code> instance that is
  101. * unavailable
  102. *
  103. * @param msg a <code>String</code> specifying the
  104. * descriptive message
  105. *
  106. */
  107. public UnavailableException(Servlet servlet, String msg) {
  108. super(msg);
  109. this.servlet = servlet;
  110. permanent = true;
  111. }
  112. /**
  113. * @deprecated As of Java Servlet API 2.2, use {@link
  114. * #UnavailableException(String, int)} instead.
  115. *
  116. * @param seconds an integer specifying the number of seconds
  117. * the servlet expects to be unavailable; if
  118. * zero or negative, indicates that the servlet
  119. * can't make an estimate
  120. *
  121. * @param servlet the <code>Servlet</code> that is unavailable
  122. *
  123. * @param msg a <code>String</code> specifying the descriptive
  124. * message, which can be written to a log file or
  125. * displayed for the user.
  126. *
  127. */
  128. public UnavailableException(int seconds, Servlet servlet, String msg) {
  129. super(msg);
  130. this.servlet = servlet;
  131. if (seconds <= 0)
  132. this.seconds = -1;
  133. else
  134. this.seconds = seconds;
  135. permanent = false;
  136. }
  137. /**
  138. *
  139. * Constructs a new exception with a descriptive
  140. * message indicating that the servlet is permanently
  141. * unavailable.
  142. *
  143. * @param msg a <code>String</code> specifying the
  144. * descriptive message
  145. *
  146. */
  147. public UnavailableException(String msg) {
  148. super(msg);
  149. permanent = true;
  150. }
  151. /**
  152. * Constructs a new exception with a descriptive message
  153. * indicating that the servlet is temporarily unavailable
  154. * and giving an estimate of how long it will be unavailable.
  155. *
  156. * <p>In some cases, the servlet cannot make an estimate. For
  157. * example, the servlet might know that a server it needs is
  158. * not running, but not be able to report how long it will take
  159. * to be restored to functionality. This can be indicated with
  160. * a negative or zero value for the <code>seconds</code> argument.
  161. *
  162. * @param msg a <code>String</code> specifying the
  163. * descriptive message, which can be written
  164. * to a log file or displayed for the user.
  165. *
  166. * @param seconds an integer specifying the number of seconds
  167. * the servlet expects to be unavailable; if
  168. * zero or negative, indicates that the servlet
  169. * can't make an estimate
  170. *
  171. */
  172. public UnavailableException(String msg, int seconds) {
  173. super(msg);
  174. if (seconds <= 0)
  175. this.seconds = -1;
  176. else
  177. this.seconds = seconds;
  178. permanent = false;
  179. }
  180. /**
  181. *
  182. * Returns a <code>boolean</code> indicating
  183. * whether the servlet is permanently unavailable.
  184. * If so, something is wrong with the servlet, and the
  185. * system administrator must take some corrective action.
  186. *
  187. * @return <code>true</code> if the servlet is
  188. * permanently unavailable; <code>false</code>
  189. * if the servlet is available or temporarily
  190. * unavailable
  191. *
  192. */
  193. public boolean isPermanent() {
  194. return permanent;
  195. }
  196. /**
  197. * @deprecated As of Java Servlet API 2.2, with no replacement.
  198. *
  199. * Returns the servlet that is reporting its unavailability.
  200. *
  201. * @return the <code>Servlet</code> object that is
  202. * throwing the <code>UnavailableException</code>
  203. *
  204. */
  205. public Servlet getServlet() {
  206. return servlet;
  207. }
  208. /**
  209. * Returns the number of seconds the servlet expects to
  210. * be temporarily unavailable.
  211. *
  212. * <p>If this method returns a negative number, the servlet
  213. * is permanently unavailable or cannot provide an estimate of
  214. * how long it will be unavailable. No effort is
  215. * made to correct for the time elapsed since the exception was
  216. * first reported.
  217. *
  218. * @return an integer specifying the number of seconds
  219. * the servlet will be temporarily unavailable,
  220. * or a negative number if the servlet is permanently
  221. * unavailable or cannot make an estimate
  222. *
  223. */
  224. public int getUnavailableSeconds() {
  225. return permanent ? -1 : seconds;
  226. }
  227. }