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