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