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