View Javadoc

    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 }