View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet;
25  
26  import java.io.IOException;
27  
28  /**
29   * Defines methods that all servlets must implement.
30   *
31   * <p>A servlet is a small Java program that runs within a Web server.
32   * Servlets receive and respond to requests from Web clients,
33   * usually across HTTP, the HyperText Transfer Protocol.
34   *
35   * <p>To implement this interface, you can write a generic servlet
36   * that extends
37   * <code>javax.servlet.GenericServlet</code> or an HTTP servlet that
38   * extends <code>javax.servlet.http.HttpServlet</code>.
39   *
40   * <p>This interface defines methods to initialize a servlet,
41   * to service requests, and to remove a servlet from the server.
42   * These are known as life-cycle methods and are called in the
43   * following sequence:
44   * <ol>
45   * <li>The servlet is constructed, then initialized with the <code>init</code> method.
46   * <li>Any calls from clients to the <code>service</code> method are handled.
47   * <li>The servlet is taken out of service, then destroyed with the
48   * <code>destroy</code> method, then garbage collected and finalized.
49   * </ol>
50   *
51   * <p>In addition to the life-cycle methods, this interface
52   * provides the <code>getServletConfig</code> method, which the servlet
53   * can use to get any startup information, and the <code>getServletInfo</code>
54   * method, which allows the servlet to return basic information about itself,
55   * such as author, version, and copyright.
56   *
57   * @see GenericServlet
58   * @see javax.servlet.http.HttpServlet
59   *
60   * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
61   */
62  public interface Servlet {
63      /**
64       * Called by the servlet container to indicate to a servlet that the
65       * servlet is being placed into service.
66       *
67       * <p>The servlet container calls the <code>init</code>
68       * method exactly once after instantiating the servlet.
69       * The <code>init</code> method must complete successfully
70       * before the servlet can receive any requests.
71       *
72       * <p>The servlet container cannot place the servlet into service
73       * if the <code>init</code> method
74       * <ol>
75       * <li>Throws a <code>ServletException</code>
76       * <li>Does not return within a time period defined by the Web server
77       * </ol>
78       *
79       *
80       * @param config a <code>ServletConfig</code> object
81       * containing the servlet's configuration and initialization parameters
82       *
83       * @exception ServletException if an exception has occurred that
84       * interferes with the servlet's normal operation
85       *
86       * @see UnavailableException
87       * @see #getServletConfig
88       */
89      public void init(ServletConfig config) throws ServletException;
90  
91      /**
92       * Returns a {@link ServletConfig} object, which contains
93       * initialization and startup parameters for this servlet.
94       * The <code>ServletConfig</code> object returned is the one
95       * passed to the <code>init</code> method.
96       *
97       * <p>Implementations of this interface are responsible for storing the
98       * <code>ServletConfig</code> object so that this
99       * method can return it. The {@link GenericServlet}
100      * class, which implements this interface, already does this.
101      *
102      * @return the <code>ServletConfig</code> object
103      * that initializes this servlet
104      *
105      * @see #init
106      */
107     public ServletConfig getServletConfig();
108 
109     /**
110      * Called by the servlet container to allow the servlet to respond to
111      * a request.
112      *
113      * <p>This method is only called after the servlet's <code>init()</code>
114      * method has completed successfully.
115      *
116      * <p>  The status code of the response always should be set for a servlet
117      * that throws or sends an error.
118      *
119      * <p>Servlets typically run inside multithreaded servlet containers
120      * that can handle multiple requests concurrently. Developers must
121      * be aware to synchronize access to any shared resources such as files,
122      * network connections, and as well as the servlet's class and instance
123      * variables.
124      * More information on multithreaded programming in Java is available in
125      * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">
126      * the Java tutorial on multi-threaded programming</a>.
127      *
128      *
129      * @param req the <code>ServletRequest</code> object that contains
130      * the client's request
131      *
132      * @param res the <code>ServletResponse</code> object that contains
133      * the servlet's response
134      *
135      * @exception ServletException if an exception occurs that interferes
136      * with the servlet's normal operation
137      *
138      * @exception IOException if an input or output exception occurs
139      */
140     public void service(ServletRequest req, ServletResponse res)
141             throws ServletException, IOException;
142 
143     /**
144      * Returns information about the servlet, such
145      * as author, version, and copyright.
146      *
147      * <p>The string that this method returns should
148      * be plain text and not markup of any kind (such as HTML, XML,
149      * etc.).
150      *
151      * @return a <code>String</code> containing servlet information
152      */
153     public String getServletInfo();
154 
155     /**
156      * Called by the servlet container to indicate to a servlet that the
157      * servlet is being taken out of service.  This method is
158      * only called once all threads within the servlet's
159      * <code>service</code> method have exited or after a timeout
160      * period has passed. After the servlet container calls this
161      * method, it will not call the <code>service</code> method again
162      * on this servlet.
163      *
164      * <p>This method gives the servlet an opportunity
165      * to clean up any resources that are being held (for example, memory,
166      * file handles, threads) and make sure that any persistent state is
167      * synchronized with the servlet's current state in memory.
168      */
169     public void destroy();
170 }