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