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 / Servlet.java < prev    next >
Encoding:
Java Source  |  2001-10-22  |  8.7 KB  |  233 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. import java.io.IOException;
  64.  
  65.  
  66. /**
  67.  * Defines methods that all servlets must implement.
  68.  *
  69.  * <p>A servlet is a small Java program that runs within a Web server.
  70.  * Servlets receive and respond to requests from Web clients,
  71.  * usually across HTTP, the HyperText Transfer Protocol. 
  72.  *
  73.  * <p>To implement this interface, you can write a generic servlet
  74.  * that extends
  75.  * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that
  76.  * extends <code>javax.servlet.http.HttpServlet</code>.
  77.  *
  78.  * <p>This interface defines methods to initialize a servlet,
  79.  * to service requests, and to remove a servlet from the server.
  80.  * These are known as life-cycle methods and are called in the
  81.  * following sequence:
  82.  * <ol>
  83.  * <li>The servlet is constructed, then initialized with the <code>init</code> method.
  84.  * <li>Any calls from clients to the <code>service</code> method are handled.
  85.  * <li>The servlet is taken out of service, then destroyed with the 
  86.  * <code>destroy</code> method, then garbage collected and finalized.
  87.  * </ol>
  88.  *
  89.  * <p>In addition to the life-cycle methods, this interface
  90.  * provides the <code>getServletConfig</code> method, which the servlet 
  91.  * can use to get any startup information, and the <code>getServletInfo</code>
  92.  * method, which allows the servlet to return basic information about itself,
  93.  * such as author, version, and copyright.
  94.  *
  95.  * @author     Various
  96.  * @version     $Version$
  97.  *
  98.  * @see     GenericServlet
  99.  * @see     javax.servlet.http.HttpServlet
  100.  *
  101.  */
  102.  
  103.  
  104. public interface Servlet {
  105.  
  106.     /**
  107.      * Called by the servlet container to indicate to a servlet that the 
  108.      * servlet is being placed into service.
  109.      *
  110.      * <p>The servlet container calls the <code>init</code>
  111.      * method exactly once after instantiating the servlet.
  112.      * The <code>init</code> method must complete successfully
  113.      * before the servlet can receive any requests.
  114.      *
  115.      * <p>The servlet container cannot place the servlet into service
  116.      * if the <code>init</code> method
  117.      * <ol>
  118.      * <li>Throws a <code>ServletException</code>
  119.      * <li>Does not return within a time period defined by the Web server
  120.      * </ol>
  121.      *
  122.      *
  123.      * @param config            a <code>ServletConfig</code> object 
  124.      *                    containing the servlet's
  125.      *                     configuration and initialization parameters
  126.      *
  127.      * @exception ServletException     if an exception has occurred that
  128.      *                    interferes with the servlet's normal
  129.      *                    operation
  130.      *
  131.      * @see                 UnavailableException
  132.      * @see                 #getServletConfig
  133.      *
  134.      */
  135.  
  136.     public void init(ServletConfig config) throws ServletException;
  137.     
  138.     
  139.  
  140.     /**
  141.      *
  142.      * Returns a {@link ServletConfig} object, which contains
  143.      * initialization and startup parameters for this servlet.
  144.      * The <code>ServletConfig</code> object returned is the one 
  145.      * passed to the <code>init</code> method. 
  146.      *
  147.      * <p>Implementations of this interface are responsible for storing the 
  148.      * <code>ServletConfig</code> object so that this 
  149.      * method can return it. The {@link GenericServlet}
  150.      * class, which implements this interface, already does this.
  151.      *
  152.      * @return        the <code>ServletConfig</code> object
  153.      *            that initializes this servlet
  154.      *
  155.      * @see         #init
  156.      *
  157.      */
  158.  
  159.     public ServletConfig getServletConfig();
  160.     
  161.     
  162.  
  163.     /**
  164.      * Called by the servlet container to allow the servlet to respond to 
  165.      * a request.
  166.      *
  167.      * <p>This method is only called after the servlet's <code>init()</code>
  168.      * method has completed successfully.
  169.      * 
  170.      * <p>Servlets typically run inside multithreaded servlet containers
  171.      * that can handle multiple requests concurrently. Developers must 
  172.      * be aware to synchronize access to any shared resources such as files,
  173.      * network connections, and as well as the servlet's class and instance 
  174.      * variables. 
  175.      * More information on multithreaded programming in Java is available in 
  176.      * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">
  177.      * the Java tutorial on multi-threaded programming</a>.
  178.      *
  179.      *
  180.      * @param req     the <code>ServletRequest</code> object that contains
  181.      *            the client's request
  182.      *
  183.      * @param res     the <code>ServletResponse</code> object that contains
  184.      *            the servlet's response
  185.      *
  186.      * @exception ServletException     if an exception occurs that interferes
  187.      *                    with the servlet's normal operation 
  188.      *
  189.      * @exception IOException         if an input or output exception occurs
  190.      *
  191.      */
  192.  
  193.     public void service(ServletRequest req, ServletResponse res)
  194.     throws ServletException, IOException;
  195.     
  196.     
  197.  
  198.     /**
  199.      * Returns information about the servlet, such
  200.      * as author, version, and copyright.
  201.      * 
  202.      * <p>The string that this method returns should
  203.      * be plain text and not markup of any kind (such as HTML, XML,
  204.      * etc.).
  205.      *
  206.      * @return         a <code>String</code> containing servlet information
  207.      *
  208.      */
  209.  
  210.     public String getServletInfo();
  211.     
  212.     
  213.  
  214.     /**
  215.      *
  216.      * Called by the servlet container to indicate to a servlet that the
  217.      * servlet is being taken out of service.  This method is
  218.      * only called once all threads within the servlet's
  219.      * <code>service</code> method have exited or after a timeout
  220.      * period has passed. After the servlet container calls this 
  221.      * method, it will not call the <code>service</code> method again
  222.      * on this servlet.
  223.      *
  224.      * <p>This method gives the servlet an opportunity 
  225.      * to clean up any resources that are being held (for example, memory,
  226.      * file handles, threads) and make sure that any persistent state is
  227.      * synchronized with the servlet's current state in memory.
  228.      *
  229.      */
  230.  
  231.     public void destroy();
  232. }
  233.