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 import java.util.Enumeration;
32 import java.util.ResourceBundle;
33
34 /**
35 *
36 * Defines a generic, protocol-independent
37 * servlet. To write an HTTP servlet for use on the
38 * Web, extend {@link javax.servlet.http.HttpServlet} instead.
39 *
40 * <p><code>GenericServlet</code> implements the <code>Servlet</code>
41 * and <code>ServletConfig</code> interfaces. <code>GenericServlet</code>
42 * may be directly extended by a servlet, although it's more common to extend
43 * a protocol-specific subclass such as <code>HttpServlet</code>.
44 *
45 * <p><code>GenericServlet</code> makes writing servlets
46 * easier. It provides simple versions of the lifecycle methods
47 * <code>init</code> and <code>destroy</code> and of the methods
48 * in the <code>ServletConfig</code> interface. <code>GenericServlet</code>
49 * also implements the <code>log</code> method, declared in the
50 * <code>ServletContext</code> interface.
51 *
52 * <p>To write a generic servlet, you need only
53 * override the abstract <code>service</code> method.
54 *
55 *
56 * @author Various
57 */
58
59
60 public abstract class GenericServlet
61 implements Servlet, ServletConfig, java.io.Serializable
62 {
63 private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
64 private static ResourceBundle lStrings =
65 ResourceBundle.getBundle(LSTRING_FILE);
66
67 private transient ServletConfig config;
68
69
70 /**
71 *
72 * Does nothing. All of the servlet initialization
73 * is done by one of the <code>init</code> methods.
74 *
75 */
76
77 public GenericServlet() { }
78
79
80
81 /**
82 * Called by the servlet container to indicate to a servlet that the
83 * servlet is being taken out of service. See {@link Servlet#destroy}.
84 *
85 *
86 */
87
88 public void destroy() {
89 }
90
91
92
93 /**
94 * Returns a <code>String</code> containing the value of the named
95 * initialization parameter, or <code>null</code> if the parameter does
96 * not exist. See {@link ServletConfig#getInitParameter}.
97 *
98 * <p>This method is supplied for convenience. It gets the
99 * value of the named parameter from the servlet's
100 * <code>ServletConfig</code> object.
101 *
102 * @param name a <code>String</code> specifying the name
103 * of the initialization parameter
104 *
105 * @return String a <code>String</code> containing the value
106 * of the initialization parameter
107 *
108 */
109
110 public String getInitParameter(String name) {
111 ServletConfig sc = getServletConfig();
112 if (sc == null) {
113 throw new IllegalStateException(
114 lStrings.getString("err.servlet_config_not_initialized"));
115 }
116
117 return sc.getInitParameter(name);
118 }
119
120
121
122 /**
123 * Returns the names of the servlet's initialization parameters
124 * as an <code>Enumeration</code> of <code>String</code> objects,
125 * or an empty <code>Enumeration</code> if the servlet has no
126 * initialization parameters. See {@link
127 * ServletConfig#getInitParameterNames}.
128 *
129 * <p>This method is supplied for convenience. It gets the
130 * parameter names from the servlet's <code>ServletConfig</code> object.
131 *
132 *
133 * @return Enumeration an enumeration of <code>String</code>
134 * objects containing the names of
135 * the servlet's initialization parameters
136 *
137 */
138
139 public Enumeration getInitParameterNames() {
140 ServletConfig sc = getServletConfig();
141 if (sc == null) {
142 throw new IllegalStateException(
143 lStrings.getString("err.servlet_config_not_initialized"));
144 }
145
146 return sc.getInitParameterNames();
147 }
148
149
150
151
152
153 /**
154 * Returns this servlet's {@link ServletConfig} object.
155 *
156 * @return ServletConfig the <code>ServletConfig</code> object
157 * that initialized this servlet
158 *
159 */
160
161 public ServletConfig getServletConfig() {
162 return config;
163 }
164
165
166
167
168 /**
169 * Returns a reference to the {@link ServletContext} in which this servlet
170 * is running. See {@link ServletConfig#getServletContext}.
171 *
172 * <p>This method is supplied for convenience. It gets the
173 * context from the servlet's <code>ServletConfig</code> object.
174 *
175 *
176 * @return ServletContext the <code>ServletContext</code> object
177 * passed to this servlet by the <code>init</code>
178 * method
179 *
180 */
181
182 public ServletContext getServletContext() {
183 ServletConfig sc = getServletConfig();
184 if (sc == null) {
185 throw new IllegalStateException(
186 lStrings.getString("err.servlet_config_not_initialized"));
187 }
188
189 return sc.getServletContext();
190 }
191
192
193
194
195
196 /**
197 * Returns information about the servlet, such as
198 * author, version, and copyright.
199 * By default, this method returns an empty string. Override this method
200 * to have it return a meaningful value. See {@link
201 * Servlet#getServletInfo}.
202 *
203 *
204 * @return String information about this servlet, by default an
205 * empty string
206 *
207 */
208
209 public String getServletInfo() {
210 return "";
211 }
212
213
214
215
216 /**
217 *
218 * Called by the servlet container to indicate to a servlet that the
219 * servlet is being placed into service. See {@link Servlet#init}.
220 *
221 * <p>This implementation stores the {@link ServletConfig}
222 * object it receives from the servlet container for later use.
223 * When overriding this form of the method, call
224 * <code>super.init(config)</code>.
225 *
226 * @param config the <code>ServletConfig</code> object
227 * that contains configutation
228 * information for this servlet
229 *
230 * @exception ServletException if an exception occurs that
231 * interrupts the servlet's normal
232 * operation
233 *
234 *
235 * @see UnavailableException
236 *
237 */
238
239 public void init(ServletConfig config) throws ServletException {
240 this.config = config;
241 this.init();
242 }
243
244
245
246
247
248 /**
249 *
250 * A convenience method which can be overridden so that there's no need
251 * to call <code>super.init(config)</code>.
252 *
253 * <p>Instead of overriding {@link #init(ServletConfig)}, simply override
254 * this method and it will be called by
255 * <code>GenericServlet.init(ServletConfig config)</code>.
256 * The <code>ServletConfig</code> object can still be retrieved via {@link
257 * #getServletConfig}.
258 *
259 * @exception ServletException if an exception occurs that
260 * interrupts the servlet's
261 * normal operation
262 *
263 */
264
265 public void init() throws ServletException {
266
267 }
268
269
270
271
272 /**
273 *
274 * Writes the specified message to a servlet log file, prepended by the
275 * servlet's name. See {@link ServletContext#log(String)}.
276 *
277 * @param msg a <code>String</code> specifying
278 * the message to be written to the log file
279 *
280 */
281
282 public void log(String msg) {
283 getServletContext().log(getServletName() + ": "+ msg);
284 }
285
286
287
288
289 /**
290 * Writes an explanatory message and a stack trace
291 * for a given <code>Throwable</code> exception
292 * to the servlet log file, prepended by the servlet's name.
293 * See {@link ServletContext#log(String, Throwable)}.
294 *
295 *
296 * @param message a <code>String</code> that describes
297 * the error or exception
298 *
299 * @param t the <code>java.lang.Throwable</code> error
300 * or exception
301 *
302 *
303 */
304
305 public void log(String message, Throwable t) {
306 getServletContext().log(getServletName() + ": " + message, t);
307 }
308
309
310
311 /**
312 * Called by the servlet container to allow the servlet to respond to
313 * a request. See {@link Servlet#service}.
314 *
315 * <p>This method is declared abstract so subclasses, such as
316 * <code>HttpServlet</code>, must override it.
317 *
318 *
319 *
320 * @param req the <code>ServletRequest</code> object
321 * that contains the client's request
322 *
323 * @param res the <code>ServletResponse</code> object
324 * that will contain the servlet's response
325 *
326 * @exception ServletException if an exception occurs that
327 * interferes with the servlet's
328 * normal operation occurred
329 *
330 * @exception IOException if an input or output
331 * exception occurs
332 *
333 */
334
335 public abstract void service(ServletRequest req, ServletResponse res)
336 throws ServletException, IOException;
337
338
339
340 /**
341 * Returns the name of this servlet instance.
342 * See {@link ServletConfig#getServletName}.
343 *
344 * @return the name of this servlet instance
345 *
346 *
347 *
348 */
349
350 public String getServletName() {
351 ServletConfig sc = getServletConfig();
352 if (sc == null) {
353 throw new IllegalStateException(
354 lStrings.getString("err.servlet_config_not_initialized"));
355 }
356
357 return sc.getServletName();
358 }
359 }