001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.servlet;
017
018 import java.io.IOException;
019 import java.util.Enumeration;
020
021 /**
022 *
023 * Defines a generic, protocol-independent
024 * servlet. To write an HTTP servlet for use on the
025 * Web, extend {@link javax.servlet.http.HttpServlet} instead.
026 *
027 * <p><code>GenericServlet</code> implements the <code>Servlet</code>
028 * and <code>ServletConfig</code> interfaces. <code>GenericServlet</code>
029 * may be directly extended by a servlet, although it's more common to extend
030 * a protocol-specific subclass such as <code>HttpServlet</code>.
031 *
032 * <p><code>GenericServlet</code> makes writing servlets
033 * easier. It provides simple versions of the lifecycle methods
034 * <code>init</code> and <code>destroy</code> and of the methods
035 * in the <code>ServletConfig</code> interface. <code>GenericServlet</code>
036 * also implements the <code>log</code> method, declared in the
037 * <code>ServletContext</code> interface.
038 *
039 * <p>To write a generic servlet, you need only
040 * override the abstract <code>service</code> method.
041 *
042 *
043 * @author Various
044 * @version $Version$
045 *
046 *
047 *
048 */
049
050
051 public abstract class GenericServlet
052 implements Servlet, ServletConfig, java.io.Serializable
053 {
054
055 private transient ServletConfig config;
056
057
058 /**
059 *
060 * Does nothing. All of the servlet initialization
061 * is done by one of the <code>init</code> methods.
062 *
063 */
064
065 public GenericServlet() { }
066
067
068
069 /**
070 * Called by the servlet container to indicate to a servlet that the
071 * servlet is being taken out of service. See {@link Servlet#destroy}.
072 *
073 *
074 */
075
076 public void destroy() {
077 }
078
079
080
081 /**
082 * Returns a <code>String</code> containing the value of the named
083 * initialization parameter, or <code>null</code> if the parameter does
084 * not exist. See {@link ServletConfig#getInitParameter}.
085 *
086 * <p>This method is supplied for convenience. It gets the
087 * value of the named parameter from the servlet's
088 * <code>ServletConfig</code> object.
089 *
090 * @param name a <code>String</code> specifying the name
091 * of the initialization parameter
092 *
093 * @return String a <code>String</code> containing the value
094 * of the initialization parameter
095 *
096 */
097
098 public String getInitParameter(String name) {
099 return getServletConfig().getInitParameter(name);
100 }
101
102
103
104 /**
105 * Returns the names of the servlet's initialization parameters
106 * as an <code>Enumeration</code> of <code>String</code> objects,
107 * or an empty <code>Enumeration</code> if the servlet has no
108 * initialization parameters. See {@link
109 * ServletConfig#getInitParameterNames}.
110 *
111 * <p>This method is supplied for convenience. It gets the
112 * parameter names from the servlet's <code>ServletConfig</code> object.
113 *
114 *
115 * @return Enumeration an enumeration of <code>String</code>
116 * objects containing the names of
117 * the servlet's initialization parameters
118 *
119 */
120
121 public Enumeration getInitParameterNames() {
122 return getServletConfig().getInitParameterNames();
123 }
124
125
126
127
128
129 /**
130 * Returns this servlet's {@link ServletConfig} object.
131 *
132 * @return ServletConfig the <code>ServletConfig</code> object
133 * that initialized this servlet
134 *
135 */
136
137 public ServletConfig getServletConfig() {
138 return config;
139 }
140
141
142
143
144 /**
145 * Returns a reference to the {@link ServletContext} in which this servlet
146 * is running. See {@link ServletConfig#getServletContext}.
147 *
148 * <p>This method is supplied for convenience. It gets the
149 * context from the servlet's <code>ServletConfig</code> object.
150 *
151 *
152 * @return ServletContext the <code>ServletContext</code> object
153 * passed to this servlet by the <code>init</code>
154 * method
155 *
156 */
157
158 public ServletContext getServletContext() {
159 return getServletConfig().getServletContext();
160 }
161
162
163
164
165
166 /**
167 * Returns information about the servlet, such as
168 * author, version, and copyright.
169 * By default, this method returns an empty string. Override this method
170 * to have it return a meaningful value. See {@link
171 * Servlet#getServletInfo}.
172 *
173 *
174 * @return String information about this servlet, by default an
175 * empty string
176 *
177 */
178
179 public String getServletInfo() {
180 return "";
181 }
182
183
184
185
186 /**
187 *
188 * Called by the servlet container to indicate to a servlet that the
189 * servlet is being placed into service. See {@link Servlet#init}.
190 *
191 * <p>This implementation stores the {@link ServletConfig}
192 * object it receives from the servlet container for later use.
193 * When overriding this form of the method, call
194 * <code>super.init(config)</code>.
195 *
196 * @param config the <code>ServletConfig</code> object
197 * that contains configutation
198 * information for this servlet
199 *
200 * @exception ServletException if an exception occurs that
201 * interrupts the servlet's normal
202 * operation
203 *
204 *
205 * @see UnavailableException
206 *
207 */
208
209 public void init(ServletConfig config) throws ServletException {
210 this.config = config;
211 this.init();
212 }
213
214
215
216
217
218 /**
219 *
220 * A convenience method which can be overridden so that there's no need
221 * to call <code>super.init(config)</code>.
222 *
223 * <p>Instead of overriding {@link #init(ServletConfig)}, simply override
224 * this method and it will be called by
225 * <code>GenericServlet.init(ServletConfig config)</code>.
226 * The <code>ServletConfig</code> object can still be retrieved via {@link
227 * #getServletConfig}.
228 *
229 * @exception ServletException if an exception occurs that
230 * interrupts the servlet's
231 * normal operation
232 *
233 */
234
235 public void init() throws ServletException {
236
237 }
238
239
240
241
242 /**
243 *
244 * Writes the specified message to a servlet log file, prepended by the
245 * servlet's name. See {@link ServletContext#log(String)}.
246 *
247 * @param msg a <code>String</code> specifying
248 * the message to be written to the log file
249 *
250 */
251
252 public void log(String msg) {
253 getServletContext().log(getServletName() + ": "+ msg);
254 }
255
256
257
258
259 /**
260 * Writes an explanatory message and a stack trace
261 * for a given <code>Throwable</code> exception
262 * to the servlet log file, prepended by the servlet's name.
263 * See {@link ServletContext#log(String, Throwable)}.
264 *
265 *
266 * @param message a <code>String</code> that describes
267 * the error or exception
268 *
269 * @param t the <code>java.lang.Throwable</code> error
270 * or exception
271 *
272 *
273 */
274
275 public void log(String message, Throwable t) {
276 getServletContext().log(getServletName() + ": " + message, t);
277 }
278
279
280
281 /**
282 * Called by the servlet container to allow the servlet to respond to
283 * a request. See {@link Servlet#service}.
284 *
285 * <p>This method is declared abstract so subclasses, such as
286 * <code>HttpServlet</code>, must override it.
287 *
288 *
289 *
290 * @param req the <code>ServletRequest</code> object
291 * that contains the client's request
292 *
293 * @param res the <code>ServletResponse</code> object
294 * that will contain the servlet's response
295 *
296 * @exception ServletException if an exception occurs that
297 * interferes with the servlet's
298 * normal operation occurred
299 *
300 * @exception IOException if an input or output
301 * exception occurs
302 *
303 */
304
305 public abstract void service(ServletRequest req, ServletResponse res)
306 throws ServletException, IOException;
307
308
309
310 /**
311 * Returns the name of this servlet instance.
312 * See {@link ServletConfig#getServletName}.
313 *
314 * @return the name of this servlet instance
315 *
316 *
317 *
318 */
319
320 public String getServletName() {
321 return config.getServletName();
322 }
323 }