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