lib/servlet-api/javax/servlet/GenericServlet.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  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 package javax.servlet;
  18
  19 import java.io.IOException;
  20 import java.util.Enumeration;
  21
  22 /**
  23  * Defines a generic, protocol-independent servlet. To write an HTTP servlet for
  24  * use on the Web, extend {@link javax.servlet.http.HttpServlet} instead.
  25  * <p>
  26  * <code>GenericServlet</code> implements the <code>Servlet</code> and
  27  * <code>ServletConfig</code> interfaces. <code>GenericServlet</code> may be
  28  * directly extended by a servlet, although it's more common to extend a
  29  * protocol-specific subclass such as <code>HttpServlet</code>.
  30  * <p>
  31  * <code>GenericServlet</code> makes writing servlets easier. It provides simple
  32  * versions of the lifecycle methods <code>init</code> and <code>destroy</code>
  33  * and of the methods in the <code>ServletConfig</code> interface.
  34  * <code>GenericServlet</code> also implements the <code>log</code> method,
  35  * declared in the <code>ServletContext</code> interface.
  36  * <p>
  37  * To write a generic servlet, you need only override the abstract
  38  * <code>service</code> method.
  39  */
  40 public abstract class GenericServlet implements Servlet, ServletConfig,
  41         java.io.Serializable {
  42
  43     private static final long serialVersionUID = 1L;
  44
  45     private transient ServletConfig config;
  46
  47     /**
  48      * Does nothing. All of the servlet initialization is done by one of the
  49      * <code>init</code> methods.
  50      */
  51     public GenericServlet() {
  52         // NOOP
  53     }
  54
  55     /**
  56      * Called by the servlet container to indicate to a servlet that the servlet
  57      * is being taken out of service. See {@link Servlet#destroy}.
  58      */
  59     @Override
  60     public void destroy() {
  61         // NOOP by default
  62     }
  63
  64     /**
  65      * Returns a <code>String</code> containing the value of the named
  66      * initialization parameter, or <code>null</code> if the parameter does not
  67      * exist. See {@link ServletConfig#getInitParameter}.
  68      * <p>
  69      * This method is supplied for convenience. It gets the value of the named
  70      * parameter from the servlet's <code>ServletConfig</code> object.
  71      *
  72      * @param name
  73      *            a <code>String</code> specifying the name of the
  74      *            initialization parameter
  75      * @return String a <code>String</code> containing the value of the
  76      *         initialization parameter
  77      */
  78     @Override
  79     public String getInitParameter(String name) {
  80         return getServletConfig().getInitParameter(name);
  81     }
  82
  83     /**
  84      * Returns the names of the servlet's initialization parameters as an
  85      * <code>Enumeration</code> of <code>String</code> objects, or an empty
  86      * <code>Enumeration</code> if the servlet has no initialization parameters.
  87      * See {@link ServletConfig#getInitParameterNames}.
  88      * <p>
  89      * This method is supplied for convenience. It gets the parameter names from
  90      * the servlet's <code>ServletConfig</code> object.
  91      *
  92      * @return Enumeration an enumeration of <code>String</code> objects
  93      *         containing the names of the servlet's initialization parameters
  94      */
  95     @Override
  96     public Enumeration<String> getInitParameterNames() {
  97         return getServletConfig().getInitParameterNames();
  98     }
  99
 100     /**
 101      * Returns this servlet's {@link ServletConfig} object.
 102      *
 103      * @return ServletConfig the <code>ServletConfig</code> object that
 104      *         initialized this servlet
 105      */
 106     @Override
 107     public ServletConfig getServletConfig() {
 108         return config;
 109     }
 110
 111     /**
 112      * Returns a reference to the {@link ServletContext} in which this servlet
 113      * is running. See {@link ServletConfig#getServletContext}.
 114      * <p>
 115      * This method is supplied for convenience. It gets the context from the
 116      * servlet's <code>ServletConfig</code> object.
 117      *
 118      * @return ServletContext the <code>ServletContext</code> object passed to
 119      *         this servlet by the <code>init</code> method
 120      */
 121     @Override
 122     public ServletContext getServletContext() {
 123         return getServletConfig().getServletContext();
 124     }
 125
 126     /**
 127      * Returns information about the servlet, such as author, version, and
 128      * copyright. By default, this method returns an empty string. Override this
 129      * method to have it return a meaningful value. See
 130      * {@link Servlet#getServletInfo}.
 131      *
 132      * @return String information about this servlet, by default an empty string
 133      */
 134     @Override
 135     public String getServletInfo() {
 136         return "";
 137     }
 138
 139     /**
 140      * Called by the servlet container to indicate to a servlet that the servlet
 141      * is being placed into service. See {@link Servlet#init}.
 142      * <p>
 143      * This implementation stores the {@link ServletConfig} object it receives
 144      * from the servlet container for later use. When overriding this form of
 145      * the method, call <code>super.init(config)</code>.
 146      *
 147      * @param config
 148      *            the <code>ServletConfig</code> object that contains
 149      *            configuration information for this servlet
 150      * @exception ServletException
 151      *                if an exception occurs that interrupts the servlet's
 152      *                normal operation
 153      * @see UnavailableException
 154      */
 155     @Override
 156     public void init(ServletConfig config) throws ServletException {
 157         this.config = config;
 158         this.init();
 159     }
 160
 161     /**
 162      * A convenience method which can be overridden so that there's no need to
 163      * call <code>super.init(config)</code>.
 164      * <p>
 165      * Instead of overriding {@link #init(ServletConfig)}, simply override this
 166      * method and it will be called by
 167      * <code>GenericServlet.init(ServletConfig config)</code>. The
 168      * <code>ServletConfig</code> object can still be retrieved via
 169      * {@link #getServletConfig}.
 170      *
 171      * @exception ServletException
 172      *                if an exception occurs that interrupts the servlet's
 173      *                normal operation
 174      */
 175     public void init() throws ServletException {
 176         // NOOP by default
 177     }
 178
 179     /**
 180      * Writes the specified message to a servlet log file, prepended by the
 181      * servlet's name. See {@link ServletContext#log(String)}.
 182      *
 183      * @param msg
 184      *            a <code>String</code> specifying the message to be written to
 185      *            the log file
 186      */
 187     public void log(String msg) {
 188         getServletContext().log(getServletName() + ": " + msg);
 189     }
 190
 191     /**
 192      * Writes an explanatory message and a stack trace for a given
 193      * <code>Throwable</code> exception to the servlet log file, prepended by
 194      * the servlet's name. See {@link ServletContext#log(String, Throwable)}.
 195      *
 196      * @param message
 197      *            a <code>String</code> that describes the error or exception
 198      * @param t
 199      *            the <code>java.lang.Throwable</code> error or exception
 200      */
 201     public void log(String message, Throwable t) {
 202         getServletContext().log(getServletName() + ": " + message, t);
 203     }
 204
 205     /**
 206      * Called by the servlet container to allow the servlet to respond to a
 207      * request. See {@link Servlet#service}.
 208      * <p>
 209      * This method is declared abstract so subclasses, such as
 210      * <code>HttpServlet</code>, must override it.
 211      *
 212      * @param req
 213      *            the <code>ServletRequest</code> object that contains the
 214      *            client's request
 215      * @param res
 216      *            the <code>ServletResponse</code> object that will contain the
 217      *            servlet's response
 218      * @exception ServletException
 219      *                if an exception occurs that interferes with the servlet's
 220      *                normal operation occurred
 221      * @exception IOException
 222      *                if an input or output exception occurs
 223      */
 224     @Override
 225     public abstract void service(ServletRequest req, ServletResponse res)
 226             throws ServletException, IOException;
 227
 228     /**
 229      * Returns the name of this servlet instance. See
 230      * {@link ServletConfig#getServletName}.
 231      *
 232      * @return the name of this servlet instance
 233      */
 234     @Override
 235     public String getServletName() {
 236         return config.getServletName();
 237     }
 238 }