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