View Javadoc

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 }