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