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 
GenericServlet()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 
destroy()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 
getInitParameter(String name)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 
getInitParameterNames()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 
getServletConfig()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 
getServletContext()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 
getServletInfo()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 
init(ServletConfig config)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 
init()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 
log(String msg)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 
log(String message, Throwable t)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 
service(ServletRequest req, ServletResponse res)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 
getServletName()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 }
360