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