View Javadoc

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  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
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 }