View Javadoc

    1
    2
    3   /*
    4    * The contents of this file are subject to the terms
    5    * of the Common Development and Distribution License
    6    * (the "License").  You may not use this file except
    7    * in compliance with the License.
    8    *
    9    * You can obtain a copy of the license at
    10   * glassfish/bootstrap/legal/CDDLv1.0.txt or
    11   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
    12   * See the License for the specific language governing
    13   * permissions and limitations under the License.
    14   *
    15   * When distributing Covered Code, include this CDDL
    16   * HEADER in each file and include the License file at
    17   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable,
    18   * add the following below this CDDL HEADER, with the
    19   * fields enclosed by brackets "[]" replaced with your
    20   * own identifying information: Portions Copyright [yyyy]
    21   * [name of copyright owner]
    22   *
    23   * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
    24   *
    25   * Portions Copyright Apache Software Foundation.
    26   */
    27
    28  package javax.servlet;
    29
    30  import java.io.IOException;
    31  import java.util.Enumeration;
    32  import java.util.ResourceBundle;
    33
    34  /**
    35   *
    36   * Defines a generic, protocol-independent
    37   * servlet. To write an HTTP servlet for use on the
    38   * Web, extend {@link javax.servlet.http.HttpServlet} instead.
    39   *
    40   * <p><code>GenericServlet</code> implements the <code>Servlet</code>
    41   * and <code>ServletConfig</code> interfaces. <code>GenericServlet</code>
    42   * may be directly extended by a servlet, although it's more common to extend
    43   * a protocol-specific subclass such as <code>HttpServlet</code>.
    44   *
    45   * <p><code>GenericServlet</code> makes writing servlets
    46   * easier. It provides simple versions of the lifecycle methods
    47   * <code>init</code> and <code>destroy</code> and of the methods
    48   * in the <code>ServletConfig</code> interface. <code>GenericServlet</code>
    49   * also implements the <code>log</code> method, declared in the
    50   * <code>ServletContext</code> interface.
    51   *
    52   * <p>To write a generic servlet, you need only
    53   * override the abstract <code>service</code> method.
    54   *
    55   *
    56   * @author 	Various
    57   */
    58
    59
    60  public abstract class GenericServlet
    61      implements Servlet, ServletConfig, java.io.Serializable
    62  {
    63      private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
    64      private static ResourceBundle lStrings =
    65          ResourceBundle.getBundle(LSTRING_FILE);
    66
    67      private transient ServletConfig config;
    68
    69
    70      /**
    71       *
    72       * Does nothing. All of the servlet initialization
    73       * is done by one of the <code>init</code> methods.
    74       *
    75       */
    76
    77      public GenericServlet() { }
    78
    79
    80
    81     /**
    82       * Called by the servlet container to indicate to a servlet that the
    83       * servlet is being taken out of service.  See {@link Servlet#destroy}.
    84       *
    85       *
    86       */
    87
    88      public void destroy() {
    89      }
    90
    91
    92
    93      /**
    94       * Returns a <code>String</code> containing the value of the named
    95       * initialization parameter, or <code>null</code> if the parameter does
    96       * not exist.  See {@link ServletConfig#getInitParameter}.
    97       *
    98       * <p>This method is supplied for convenience. It gets the
    99       * value of the named parameter from the servlet's
    100      * <code>ServletConfig</code> object.
    101      *
    102      * @param name 		a <code>String</code> specifying the name
    103      *				of the initialization parameter
    104      *
    105      * @return String 		a <code>String</code> containing the value
    106      *				of the initialization parameter
    107      *
    108      */
    109
    110     public String getInitParameter(String name) {
    111         ServletConfig sc = getServletConfig();
    112         if (sc == null) {
    113             throw new IllegalStateException(
    114                 lStrings.getString("err.servlet_config_not_initialized"));
    115         }
    116
    117         return sc.getInitParameter(name);
    118     }
    119
    120
    121
    122    /**
    123     * Returns the names of the servlet's initialization parameters
    124     * as an <code>Enumeration</code> of <code>String</code> objects,
    125     * or an empty <code>Enumeration</code> if the servlet has no
    126     * initialization parameters.  See {@link
    127     * ServletConfig#getInitParameterNames}.
    128     *
    129     * <p>This method is supplied for convenience. It gets the
    130     * parameter names from the servlet's <code>ServletConfig</code> object.
    131     *
    132     *
    133     * @return Enumeration 	an enumeration of <code>String</code>
    134     *				objects containing the names of
    135     *				the servlet's initialization parameters
    136     *
    137     */
    138
    139     public Enumeration getInitParameterNames() {
    140         ServletConfig sc = getServletConfig();
    141         if (sc == null) {
    142             throw new IllegalStateException(
    143                 lStrings.getString("err.servlet_config_not_initialized"));
    144         }
    145
    146         return sc.getInitParameterNames();
    147     }
    148
    149
    150
    151
    152
    153     /**
    154      * Returns this servlet's {@link ServletConfig} object.
    155      *
    156      * @return ServletConfig 	the <code>ServletConfig</code> object
    157      *				that initialized this servlet
    158      *
    159      */
    160
    161     public ServletConfig getServletConfig() {
    162 	return config;
    163     }
    164
    165
    166
    167
    168     /**
    169      * Returns a reference to the {@link ServletContext} in which this servlet
    170      * is running.  See {@link ServletConfig#getServletContext}.
    171      *
    172      * <p>This method is supplied for convenience. It gets the
    173      * context from the servlet's <code>ServletConfig</code> object.
    174      *
    175      *
    176      * @return ServletContext 	the <code>ServletContext</code> object
    177      *				passed to this servlet by the <code>init</code>
    178      *				method
    179      *
    180      */
    181
    182     public ServletContext getServletContext() {
    183         ServletConfig sc = getServletConfig();
    184         if (sc == null) {
    185             throw new IllegalStateException(
    186                 lStrings.getString("err.servlet_config_not_initialized"));
    187         }
    188
    189         return sc.getServletContext();
    190     }
    191
    192
    193
    194
    195
    196     /**
    197      * Returns information about the servlet, such as
    198      * author, version, and copyright.
    199      * By default, this method returns an empty string.  Override this method
    200      * to have it return a meaningful value.  See {@link
    201      * Servlet#getServletInfo}.
    202      *
    203      *
    204      * @return String 		information about this servlet, by default an
    205      * 				empty string
    206      *
    207      */
    208
    209     public String getServletInfo() {
    210 	return "";
    211     }
    212
    213
    214
    215
    216     /**
    217      *
    218      * Called by the servlet container to indicate to a servlet that the
    219      * servlet is being placed into service.  See {@link Servlet#init}.
    220      *
    221      * <p>This implementation stores the {@link ServletConfig}
    222      * object it receives from the servlet container for later use.
    223      * When overriding this form of the method, call
    224      * <code>super.init(config)</code>.
    225      *
    226      * @param config 			the <code>ServletConfig</code> object
    227      *					that contains configutation
    228      *					information for this servlet
    229      *
    230      * @exception ServletException 	if an exception occurs that
    231      *					interrupts the servlet's normal
    232      *					operation
    233      *
    234      *
    235      * @see 				UnavailableException
    236      *
    237      */
    238
    239     public void init(ServletConfig config) throws ServletException {
    240 	this.config = config;
    241 	this.init();
    242     }
    243
    244
    245
    246
    247
    248     /**
    249      *
    250      * A convenience method which can be overridden so that there's no need
    251      * to call <code>super.init(config)</code>.
    252      *
    253      * <p>Instead of overriding {@link #init(ServletConfig)}, simply override
    254      * this method and it will be called by
    255      * <code>GenericServlet.init(ServletConfig config)</code>.
    256      * The <code>ServletConfig</code> object can still be retrieved via {@link
    257      * #getServletConfig}.
    258      *
    259      * @exception ServletException 	if an exception occurs that
    260      *					interrupts the servlet's
    261      *					normal operation
    262      *
    263      */
    264
    265     public void init() throws ServletException {
    266
    267     }
    268
    269
    270
    271
    272     /**
    273      *
    274      * Writes the specified message to a servlet log file, prepended by the
    275      * servlet's name.  See {@link ServletContext#log(String)}.
    276      *
    277      * @param msg 	a <code>String</code> specifying
    278      *			the message to be written to the log file
    279      *
    280      */
    281
    282     public void log(String msg) {
    283 	getServletContext().log(getServletName() + ": "+ msg);
    284     }
    285
    286
    287
    288
    289     /**
    290      * Writes an explanatory message and a stack trace
    291      * for a given <code>Throwable</code> exception
    292      * to the servlet log file, prepended by the servlet's name.
    293      * See {@link ServletContext#log(String, Throwable)}.
    294      *
    295      *
    296      * @param message 		a <code>String</code> that describes
    297      *				the error or exception
    298      *
    299      * @param t			the <code>java.lang.Throwable</code> error
    300      * 				or exception
    301      *
    302      *
    303      */
    304
    305     public void log(String message, Throwable t) {
    306 	getServletContext().log(getServletName() + ": " + message, t);
    307     }
    308
    309
    310
    311     /**
    312      * Called by the servlet container to allow the servlet to respond to
    313      * a request.  See {@link Servlet#service}.
    314      *
    315      * <p>This method is declared abstract so subclasses, such as
    316      * <code>HttpServlet</code>, must override it.
    317      *
    318      *
    319      *
    320      * @param req 	the <code>ServletRequest</code> object
    321      *			that contains the client's request
    322      *
    323      * @param res 	the <code>ServletResponse</code> object
    324      *			that will contain the servlet's response
    325      *
    326      * @exception ServletException 	if an exception occurs that
    327      *					interferes with the servlet's
    328      *					normal operation occurred
    329      *
    330      * @exception IOException 		if an input or output
    331      *					exception occurs
    332      *
    333      */
    334
    335     public abstract void service(ServletRequest req, ServletResponse res)
    336 	throws ServletException, IOException;
    337
    338
    339
    340     /**
    341      * Returns the name of this servlet instance.
    342      * See {@link ServletConfig#getServletName}.
    343      *
    344      * @return          the name of this servlet instance
    345      *
    346      *
    347      *
    348      */
    349
    350     public String getServletName() {
    351         ServletConfig sc = getServletConfig();
    352         if (sc == null) {
    353             throw new IllegalStateException(
    354                 lStrings.getString("err.servlet_config_not_initialized"));
    355         }
    356
    357         return sc.getServletName();
    358     }
    359 }