1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19
20
21
22
23
24 package javax.servlet;
25
26 import java.io.IOException;
27 import java.util.Enumeration;
28
29 /**
30 *
31 * Defines a generic, protocol-independent
32 * servlet. To write an HTTP servlet for use on the
33 * Web, extend {@link javax.servlet.http.HttpServlet} instead.
34 *
35 * <p><code>GenericServlet</code> implements the <code>Servlet</code>
36 * and <code>ServletConfig</code> interfaces. <code>GenericServlet</code>
37 * may be directly extended by a servlet, although it's more common to extend
38 * a protocol-specific subclass such as <code>HttpServlet</code>.
39 *
40 * <p><code>GenericServlet</code> makes writing servlets
41 * easier. It provides simple versions of the lifecycle methods
42 * <code>init</code> and <code>destroy</code> and of the methods
43 * in the <code>ServletConfig</code> interface. <code>GenericServlet</code>
44 * also implements the <code>log</code> method, declared in the
45 * <code>ServletContext</code> interface.
46 *
47 * <p>To write a generic servlet, you need only
48 * override the abstract <code>service</code> method.
49 *
50 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
51 */
52 public abstract class GenericServlet implements Servlet, ServletConfig, java.io.Serializable {
53 private transient ServletConfig config;
54
55 /**
56 * Does nothing. All of the servlet initialization
57 * is done by one of the <code>init</code> methods.
58 */
59 public GenericServlet() {
60 }
61
62 /**
63 * Called by the servlet container to indicate to a servlet that the
64 * servlet is being taken out of service. See {@link Servlet#destroy}.
65 */
66 public void destroy() {
67 }
68
69 /**
70 * Returns a <code>String</code> containing the value of the named
71 * initialization parameter, or <code>null</code> if the parameter does
72 * not exist. See {@link ServletConfig#getInitParameter}.
73 *
74 * <p>This method is supplied for convenience. It gets the
75 * value of the named parameter from the servlet's
76 * <code>ServletConfig</code> object.
77 *
78 * @param name a <code>String</code> specifying the name
79 * of the initialization parameter
80 *
81 * @return String a <code>String</code> containing the value
82 * of the initalization parameter
83 */
84 public String getInitParameter(String name) {
85 return getServletConfig().getInitParameter(name);
86 }
87
88 /**
89 * Returns the names of the servlet's initialization parameters
90 * as an <code>Enumeration</code> of <code>String</code> objects,
91 * or an empty <code>Enumeration</code> if the servlet has no
92 * initialization parameters. See {@link
93 * ServletConfig#getInitParameterNames}.
94 *
95 * <p>This method is supplied for convenience. It gets the
96 * parameter names from the servlet's <code>ServletConfig</code> object.
97 *
98 *
99 * @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 }