home *** CD-ROM | disk | FTP | other *** search
/ PC World 2002 May / PCWorld_2002-05_cd.bin / Komunik / sambar / sambar51p.exe / lib / javaeng.jar / javax / servlet / UnavailableException.java < prev   
Encoding:
Java Source  |  2001-10-22  |  8.8 KB  |  250 lines
  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.  
  61. package javax.servlet;
  62.  
  63.  
  64. /**
  65.  * Defines an exception that a servlet throws to indicate
  66.  * that it is permanently or temporarily unavailable. 
  67.  *
  68.  * <p>When a servlet is permanently unavailable, something is wrong
  69.  * with the servlet, and it cannot handle
  70.  * requests until some action is taken. For example, the servlet
  71.  * might be configured incorrectly, or its state may be corrupted.
  72.  * A servlet should log both the error and the corrective action
  73.  * that is needed.
  74.  *
  75.  * <p>A servlet is temporarily unavailable if it cannot handle
  76.  * requests momentarily due to some system-wide problem. For example,
  77.  * a third-tier server might not be accessible, or there may be 
  78.  * insufficient memory or disk storage to handle requests. A system
  79.  * administrator may need to take corrective action.
  80.  *
  81.  * <p>Servlet containers can safely treat both types of unavailable
  82.  * exceptions in the same way. However, treating temporary unavailability
  83.  * effectively makes the servlet container more robust. Specifically,
  84.  * the servlet container might block requests to the servlet for a period
  85.  * of time suggested by the servlet, rather than rejecting them until
  86.  * the servlet container restarts.
  87.  *
  88.  *
  89.  * @author     Various
  90.  * @version     $Version$
  91.  *
  92.  */
  93.  
  94. public class UnavailableException
  95. extends ServletException {
  96.  
  97.     private Servlet     servlet;           // what's unavailable
  98.     private boolean     permanent;         // needs admin action?
  99.     private int         seconds;           // unavailability estimate
  100.  
  101.     /**
  102.      * 
  103.      * @deprecated    As of Java Servlet API 2.2, use {@link
  104.      *             #UnavailableException(String)} instead.
  105.      *
  106.      * @param servlet     the <code>Servlet</code> instance that is
  107.      *                  unavailable
  108.      *
  109.      * @param msg     a <code>String</code> specifying the
  110.      *                  descriptive message
  111.      *
  112.      */
  113.  
  114.     public UnavailableException(Servlet servlet, String msg) {
  115.     super(msg);
  116.     this.servlet = servlet;
  117.     permanent = true;
  118.     }
  119.  
  120.     /**
  121.      * @deprecated    As of Java Servlet API 2.2, use {@link
  122.      *            #UnavailableException(String, int)} instead.
  123.      *
  124.      * @param seconds    an integer specifying the number of seconds
  125.      *             the servlet expects to be unavailable; if
  126.      *            zero or negative, indicates that the servlet
  127.      *            can't make an estimate
  128.      *
  129.      * @param servlet    the <code>Servlet</code> that is unavailable
  130.      * 
  131.      * @param msg    a <code>String</code> specifying the descriptive 
  132.      *            message, which can be written to a log file or 
  133.      *            displayed for the user.
  134.      *
  135.      */
  136.     
  137.     public UnavailableException(int seconds, Servlet servlet, String msg) {
  138.     super(msg);
  139.     this.servlet = servlet;
  140.     if (seconds <= 0)
  141.         this.seconds = -1;
  142.     else
  143.         this.seconds = seconds;
  144.     permanent = false;
  145.     }
  146.  
  147.     /**
  148.      * 
  149.      * Constructs a new exception with a descriptive
  150.      * message indicating that the servlet is permanently
  151.      * unavailable.
  152.      *
  153.      * @param msg     a <code>String</code> specifying the
  154.      *                  descriptive message
  155.      *
  156.      */
  157.  
  158.     public UnavailableException(String msg) {
  159.     super(msg);
  160.  
  161.     permanent = true;
  162.     }
  163.  
  164.     /**
  165.      * Constructs a new exception with a descriptive message
  166.      * indicating that the servlet is temporarily unavailable
  167.      * and giving an estimate of how long it will be unavailable.
  168.      * 
  169.      * <p>In some cases, the servlet cannot make an estimate. For
  170.      * example, the servlet might know that a server it needs is
  171.      * not running, but not be able to report how long it will take
  172.      * to be restored to functionality. This can be indicated with
  173.      * a negative or zero value for the <code>seconds</code> argument.
  174.      *
  175.      * @param msg    a <code>String</code> specifying the
  176.      *                  descriptive message, which can be written
  177.      *                  to a log file or displayed for the user.
  178.      *
  179.      * @param seconds    an integer specifying the number of seconds
  180.      *             the servlet expects to be unavailable; if
  181.      *            zero or negative, indicates that the servlet
  182.      *            can't make an estimate
  183.      *
  184.      */
  185.     
  186.     public UnavailableException(String msg, int seconds) {
  187.     super(msg);
  188.  
  189.     if (seconds <= 0)
  190.         this.seconds = -1;
  191.     else
  192.         this.seconds = seconds;
  193.  
  194.     permanent = false;
  195.     }
  196.  
  197.     /**
  198.      *
  199.      * Returns a <code>boolean</code> indicating
  200.      * whether the servlet is permanently unavailable.
  201.      * If so, something is wrong with the servlet, and the
  202.      * system administrator must take some corrective action.
  203.      *
  204.      * @return        <code>true</code> if the servlet is
  205.      *            permanently unavailable; <code>false</code>
  206.      *            if the servlet is available or temporarily
  207.      *            unavailable
  208.      *
  209.      */
  210.      
  211.     public boolean isPermanent() {
  212.     return permanent;
  213.     }
  214.   
  215.     /**
  216.      * @deprecated    As of Java Servlet API 2.2, with no replacement.
  217.      *
  218.      * Returns the servlet that is reporting its unavailability.
  219.      * 
  220.      * @return        the <code>Servlet</code> object that is 
  221.      *            throwing the <code>UnavailableException</code>
  222.      *
  223.      */
  224.      
  225.     public Servlet getServlet() {
  226.     return servlet;
  227.     }
  228.  
  229.     /**
  230.      * Returns the number of seconds the servlet expects to 
  231.      * be temporarily unavailable.  
  232.      *
  233.      * <p>If this method returns a negative number, the servlet
  234.      * is permanently unavailable or cannot provide an estimate of
  235.      * how long it will be unavailable. No effort is
  236.      * made to correct for the time elapsed since the exception was
  237.      * first reported.
  238.      *
  239.      * @return        an integer specifying the number of seconds
  240.      *            the servlet will be temporarily unavailable,
  241.      *            or a negative number if the servlet is permanently
  242.      *            unavailable or cannot make an estimate
  243.      *
  244.      */
  245.      
  246.     public int getUnavailableSeconds() {
  247.     return permanent ? -1 : seconds;
  248.     }
  249. }
  250.