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 }