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-24 21:01:51 -0700 (Tue, 24 Oct 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 }