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 package javax.servlet;
021
022 import java.io.IOException;
023 import java.util.Enumeration;
024
025 /**
026 * Defines a generic, protocol-independent
027 * servlet. To write an HTTP servlet for use on the
028 * Web, extend {@link javax.servlet.http.HttpServlet} instead.
029 * <p/>
030 * <p><code>GenericServlet</code> implements the <code>Servlet</code>
031 * and <code>ServletConfig</code> interfaces. <code>GenericServlet</code>
032 * may be directly extended by a servlet, although it's more common to extend
033 * a protocol-specific subclass such as <code>HttpServlet</code>.
034 * <p/>
035 * <p><code>GenericServlet</code> makes writing servlets
036 * easier. It provides simple versions of the lifecycle methods
037 * <code>init</code> and <code>destroy</code> and of the methods
038 * in the <code>ServletConfig</code> interface. <code>GenericServlet</code>
039 * also implements the <code>log</code> method, declared in the
040 * <code>ServletContext</code> interface.
041 * <p/>
042 * <p>To write a generic servlet, you need only
043 * override the abstract <code>service</code> method.
044 *
045 * @version $Rev: 788194 $ $Date: 2009-06-24 18:05:48 -0400 (Wed, 24 Jun 2009) $
046 */
047
048
049 public abstract class GenericServlet implements Servlet, ServletConfig, java.io.Serializable {
050
051 private transient ServletConfig config;
052
053 /**
054 * Does nothing. All of the servlet initialization
055 * is done by one of the <code>init</code> methods.
056 */
057 public GenericServlet() {
058 }
059
060 /**
061 * Called by the servlet container to indicate to a servlet that the
062 * servlet is being taken out of service. See {@link Servlet#destroy}.
063 */
064 public void destroy() {
065 }
066
067 /**
068 * Returns a <code>String</code> containing the value of the named
069 * initialization parameter, or <code>null</code> if the parameter does
070 * not exist. See {@link ServletConfig#getInitParameter}.
071 * <p/>
072 * <p>This method is supplied for convenience. It gets the
073 * value of the named parameter from the servlet's
074 * <code>ServletConfig</code> object.
075 *
076 * @param name a <code>String</code> specifying the name
077 * of the initialization parameter
078 * @return String a <code>String</code> containing the value
079 * of the initialization parameter
080 */
081 public String getInitParameter(String name) {
082 return getServletConfig().getInitParameter(name);
083 }
084
085 /**
086 * Returns the names of the servlet's initialization parameters
087 * as an <code>Enumeration</code> of <code>String</code> objects,
088 * or an empty <code>Enumeration</code> if the servlet has no
089 * initialization parameters. See {@link
090 * ServletConfig#getInitParameterNames}.
091 * <p/>
092 * <p>This method is supplied for convenience. It gets the
093 * parameter names from the servlet's <code>ServletConfig</code> object.
094 *
095 * @return Enumeration an enumeration of <code>String</code>
096 * objects containing the names of
097 * the servlet's initialization parameters
098 */
099 public Enumeration<String> getInitParameterNames() {
100 return getServletConfig().getInitParameterNames();
101 }
102
103 /**
104 * Returns this servlet's {@link ServletConfig} object.
105 *
106 * @return ServletConfig the <code>ServletConfig</code> object
107 * that initialized this servlet
108 */
109 public ServletConfig getServletConfig() {
110 return config;
111 }
112
113 /**
114 * Returns a reference to the {@link ServletContext} in which this servlet
115 * is running. See {@link ServletConfig#getServletContext}.
116 * <p/>
117 * <p>This method is supplied for convenience. It gets the
118 * context from the servlet's <code>ServletConfig</code> object.
119 *
120 * @return ServletContext the <code>ServletContext</code> object
121 * passed to this servlet by the <code>init</code>
122 * method
123 */
124 public ServletContext getServletContext() {
125 return getServletConfig().getServletContext();
126 }
127
128 /**
129 * Returns information about the servlet, such as
130 * author, version, and copyright.
131 * By default, this method returns an empty string. Override this method
132 * to have it return a meaningful value. See {@link
133 * Servlet#getServletInfo}.
134 *
135 * @return String information about this servlet, by default an
136 * empty string
137 */
138 public String getServletInfo() {
139 return "";
140 }
141
142 /**
143 * Called by the servlet container to indicate to a servlet that the
144 * servlet is being placed into service. See {@link Servlet#init}.
145 * <p/>
146 * <p>This implementation stores the {@link ServletConfig}
147 * object it receives from the servlet container for later use.
148 * When overriding this form of the method, call
149 * <code>super.init(config)</code>.
150 *
151 * @param config the <code>ServletConfig</code> object
152 * that contains configutation
153 * information for this servlet
154 * @throws ServletException if an exception occurs that
155 * interrupts the servlet's normal
156 * operation
157 * @see UnavailableException
158 */
159 public void init(ServletConfig config) throws ServletException {
160 this.config = config;
161 init();
162 }
163
164 /**
165 * A convenience method which can be overridden so that there's no need
166 * to call <code>super.init(config)</code>.
167 * <p/>
168 * <p>Instead of overriding {@link #init(ServletConfig)}, simply override
169 * this method and it will be called by
170 * <code>GenericServlet.init(ServletConfig config)</code>.
171 * The <code>ServletConfig</code> object can still be retrieved via {@link
172 * #getServletConfig}.
173 *
174 * @throws ServletException if an exception occurs that
175 * interrupts the servlet's
176 * normal operation
177 */
178 public void init() throws ServletException {
179 }
180
181 /**
182 * Writes the specified message to a servlet log file, prepended by the
183 * servlet's name. See {@link ServletContext#log(String)}.
184 *
185 * @param msg a <code>String</code> specifying
186 * the message to be written to the log file
187 */
188 public void log(String msg) {
189 getServletContext().log(getServletName() + ": " + msg);
190 }
191
192 /**
193 * Writes an explanatory message and a stack trace
194 * for a given <code>Throwable</code> exception
195 * to the servlet log file, prepended by the servlet's name.
196 * See {@link ServletContext#log(String, Throwable)}.
197 *
198 * @param message a <code>String</code> that describes
199 * the error or exception
200 * @param t the <code>java.lang.Throwable</code> error
201 * or exception
202 */
203 public void log(String message, Throwable t) {
204 getServletContext().log(getServletName() + ": " + message, t);
205 }
206
207 /**
208 * Called by the servlet container to allow the servlet to respond to
209 * a request. See {@link Servlet#service}.
210 * <p/>
211 * <p>This method is declared abstract so subclasses, such as
212 * <code>HttpServlet</code>, must override it.
213 *
214 * @param req the <code>ServletRequest</code> object
215 * that contains the client's request
216 * @param res the <code>ServletResponse</code> object
217 * that will contain the servlet's response
218 * @throws ServletException if an exception occurs that
219 * interferes with the servlet's
220 * normal operation occurred
221 * @throws IOException if an input or output
222 * exception occurs
223 */
224 public abstract void service(ServletRequest req, ServletResponse res) throws ServletException, IOException;
225
226 /**
227 * Returns the name of this servlet instance.
228 * See {@link ServletConfig#getServletName}.
229 *
230 * @return the name of this servlet instance
231 */
232 public String getServletName() {
233 return config.getServletName();
234 }
235
236 }