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 }