home *** CD-ROM | disk | FTP | other *** search
/ Java Developer's Companion / Java Developer's Companion.iso / binaries / Windows / jsdk / src / javax / servlet / GenericServlet.java next >
Encoding:
Java Source  |  1997-07-18  |  8.5 KB  |  213 lines
  1. /*
  2.  * @(#)GenericServlet.java    1.18 97/05/22
  3.  * 
  4.  * Copyright (c) 1996-1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.0
  20.  */
  21.  
  22. package javax.servlet;
  23.  
  24. import java.io.IOException;
  25. import java.util.Enumeration;
  26.  
  27. /**
  28.  * The GenericServlet class implements the Servlet interface and, for
  29.  * convenience, the ServletConfig interface.  Servlet developers
  30.  * typically subclass GenericServlet, or its descendent HttpServlet,
  31.  * unless the servlet needs another class as a parent.  (If a servlet
  32.  * does need to subclass another class, the servlet must implement the
  33.  * Servlet interface directly.  This would be necessary when, for
  34.  * example, RMI or CORBA objects act as servlets.)
  35.  *
  36.  * <p>The GenericServlet class was created to make writing servlets
  37.  * easier.  It provides simple versions of the lifecycle methods init
  38.  * and destroy, and of the methods in the ServletConfig interface.  It
  39.  * also provides a log method, from the ServletContext interface.  The
  40.  * servlet writer must override only the service method, which is
  41.  * abstract.  Though not required, the servlet implementer should also
  42.  * override the getServletInfo method, and will want to specialize the
  43.  * init and destroy methods if expensive servlet-wide resources are to
  44.  * be managed.
  45.  *
  46.  * @version     1.18, 05/22/97
  47.  * @author Pavani Diwanji */
  48.  
  49. public abstract
  50. class GenericServlet implements Servlet, ServletConfig {
  51.     private ServletConfig config;
  52.  
  53.     /**
  54.      * The default constructor does no work.
  55.      */
  56.     protected GenericServlet () { }
  57.  
  58.     /**
  59.      * Returns a ServletContext object, which contains information
  60.      * about the network service in which the servlet is running.  This
  61.      * is a convenience method; it gets the ServletContext object from
  62.      * the ServletConfig object.  (The ServletConfig object was passed
  63.      * into and stored by the init method.)
  64.      */
  65.     public ServletContext getServletContext() {
  66.     return config.getServletContext();
  67.     }
  68.  
  69.     /**
  70.      * Returns a string containing the value of the named
  71.      * initialization parameter, or null if the requested parameter
  72.      * does not exist.  Init parameters have a single string value; it
  73.      * is the responsibility of the servlet writer to interpret the
  74.      * string.
  75.      *
  76.      * <p>This is a convenience method; it gets the parameter's value
  77.      * from the ServletConfig object.  (The ServletConfig object was
  78.      * passed into and stored by the init method.)
  79.      *
  80.      * @param name the name of the parameter whose value is requested */
  81.     public String getInitParameter(String name) {
  82.     return config.getInitParameter(name);
  83.     }
  84.  
  85.     /**
  86.      * Returns the names of the servlet's initialization parameters as
  87.      * an enumeration of strings, or an empty enumeration if there are
  88.      * no initialization parameters.  The getInitParameterNames method
  89.      * is supplied for convenience; it gets the parameter names from
  90.      * the ServletConfig object.  (The ServletConfig object was passed
  91.      * into and stored by the init method.)
  92.      */
  93.     public Enumeration getInitParameterNames() {
  94.     return config.getInitParameterNames();
  95.     }
  96.  
  97.     /**
  98.      * 
  99.      * Writes the class name of the servlet and the given message to
  100.      * the servlet log file.  The name of the servlet log file is
  101.      * server specific; it is normally an event log.
  102.      *
  103.      * <p>If a servlet will have multiple instances (for example, if
  104.      * the network service runs the servlet for multiple virtual
  105.      * hosts), the servlet writer should override this method.  The
  106.      * specialized method should log an instance identifier, along with
  107.      * the requested message.  The default message prefix, the class
  108.      * name of the servlet, does not allow the log entries of the
  109.      * instances to be distinguished from one another.
  110.      *
  111.      * @param msg the message string to be logged
  112.      * */
  113.     public void log(String msg) {
  114.     getServletContext().log(getClass().getName() + ": "+ msg);
  115.     }
  116.  
  117.     /**
  118.      * Returns a string that contains information about the servlet,
  119.      * such as its author, version, and copyright.  This method
  120.      * must be overridden in order to return this information.
  121.      * If it is not overridden, null is returned.
  122.      */
  123.     public String getServletInfo() {
  124.     return null;
  125.     }
  126.  
  127.     /**
  128.      *
  129.      * Initializes the servlet and logs the initialization. The init
  130.      * method is called once, automatically, by the network service
  131.      * each time it loads the servlet.  It is guaranteed to finish
  132.      * before any service requests are accepted.  On fatal
  133.      * initialization errors, an UnavailableException should be
  134.      * thrown.  Do not call call the method System.exit.
  135.      *
  136.      * <p>The init method stores the ServletConfig object.  Servlet
  137.      * writers who specialize this method should call either
  138.      * super.init, or store the ServletConfig object themselves.  If an
  139.      * implementor decides to store the ServletConfig object in a
  140.      * different location, then the getServletConfig method must also
  141.      * be overridden.
  142.      *
  143.      * @see UnavailableException
  144.      * @param config servlet configuration information
  145.      * @exception ServletException if a servlet exception has occurred
  146.      * */
  147.     public void init(ServletConfig config) throws ServletException {
  148.     this.config = config;
  149.     log("init");
  150.     }
  151.  
  152.     /**
  153.      * Returns a servletConfig object containing any startup
  154.      * configuration information for this servlet.
  155.      */
  156.     public ServletConfig getServletConfig() {
  157.     return config;
  158.     }
  159.  
  160.     /**
  161.      * 
  162.      * Carries out a single request from the client.  The request
  163.      * object contains parameters provided by the client, and an input
  164.      * stream, which can also bring data to the servlet.  To return
  165.      * information to the client, write to the output stream of the
  166.      * response object.
  167.      *
  168.      * <p>Service requests handled after servlet initialization has
  169.      * completed.  Any requests for service that are received during
  170.      * initialization block until it is complete.
  171.      *
  172.      * <p>Note that servlets typically run inside multi-threaded
  173.      * network services, which can handle multiple service requests
  174.      * simultaneously.  It is the servlet writer's responsibility to
  175.      * synchronize access to any shared resources, such as database or
  176.      * network connections.  The simplest way to do this is to
  177.      * synchronize the entire service call.  This can have a major
  178.      * performance impact, however, and should be avoided whenever
  179.      * possible in favor of techniques that are less coarse.  For more
  180.      * information on synchronization, see the <a
  181.      * href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
  182.      * Java tutorial on multithreaded programming</a>.
  183.      *
  184.      *
  185.      * @param req the servlet request
  186.      * @param res the servlet response
  187.      * @exception ServletException if a servlet exception has occurred
  188.      * @exception IOException if an I/O exception has occurred */
  189.     public abstract void service(ServletRequest req, ServletResponse res)
  190.     throws ServletException, IOException;
  191.  
  192.     /**
  193.      *
  194.      * Destroys the servlet, cleaning up whatever resources are being
  195.      * held, and logs the destruction in the servlet log file.  This
  196.      * method is called, once, automatically, by the network service
  197.      * each time it removes the servlet.  After destroy is run, it
  198.      * cannot be called again until the network service reloads the
  199.      * servlet.
  200.      *
  201.      * <p>When the network service removes a servlet, it calls destroy
  202.      * after all service calls have been completed, or a
  203.      * service-specific number of seconds have passed, whichever comes
  204.      * first.  In the case of long-running operations, there could be
  205.      * other threads running service requests when destroy is called.
  206.      * The servlet writer is responsible for making sure that any
  207.      * threads still in the service method complete.  */
  208.     public void destroy() {
  209.     log("destroy");
  210.     }
  211.  
  212. }
  213.