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