home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / GenericServlet.java < prev    next >
Text File  |  1998-04-21  |  9KB  |  217 lines
  1. /*
  2.  * @(#)GenericServlet.java    1.23 97/11/05
  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.23, 11/05/97
  47.  */
  48.  
  49. public abstract class GenericServlet 
  50.     implements Servlet, ServletConfig, java.io.Serializable { 
  51.  
  52.     private transient ServletConfig config;
  53.  
  54.     /**
  55.      * The default constructor does no work.
  56.      */
  57.     public GenericServlet () { }
  58.  
  59.     /**
  60.      * Returns a ServletContext object, which contains information
  61.      * about the network service in which the servlet is running.  This
  62.      * is a convenience method; it gets the ServletContext object from
  63.      * the ServletConfig object.  (The ServletConfig object was passed
  64.      * into and stored by the init method.)
  65.      */
  66.     public ServletContext getServletContext() {
  67.     return getServletConfig().getServletContext();
  68.     }
  69.  
  70.     /**
  71.      * Returns a string containing the value of the named
  72.      * initialization parameter, or null if the requested parameter
  73.      * does not exist.  Init parameters have a single string value; it
  74.      * is the responsibility of the servlet writer to interpret the
  75.      * string.
  76.      *
  77.      * <p>This is a convenience method; it gets the parameter's value
  78.      * from the ServletConfig object.  (The ServletConfig object was
  79.      * passed into and stored by the init method.)
  80.      *
  81.      * @param name the name of the parameter whose value is requested
  82.      */
  83.     public String getInitParameter(String name) {
  84.     return getServletConfig().getInitParameter(name);
  85.     }
  86.  
  87.     /**
  88.      * Returns the names of the servlet's initialization parameters as
  89.      * an enumeration of strings, or an empty enumeration if there are
  90.      * no initialization parameters.  The getInitParameterNames method
  91.      * is supplied for convenience; it gets the parameter names from
  92.      * the ServletConfig object.  (The ServletConfig object was passed
  93.      * into and stored by the init method.)
  94.      */
  95.     public Enumeration getInitParameterNames() {
  96.     return getServletConfig().getInitParameterNames();
  97.     }
  98.  
  99.     /**
  100.      * 
  101.      * Writes the class name of the servlet and the given message to
  102.      * the servlet log file.  The name of the servlet log file is
  103.      * server specific; it is normally an event log.
  104.      *
  105.      * <p>If a servlet will have multiple instances (for example, if
  106.      * the network service runs the servlet for multiple virtual
  107.      * hosts), the servlet writer should override this method.  The
  108.      * specialized method should log an instance identifier, along with
  109.      * the requested message.  The default message prefix, the class
  110.      * name of the servlet, does not allow the log entries of the
  111.      * instances to be distinguished from one another.
  112.      *
  113.      * @param msg the message string to be logged
  114.      */
  115.     public void log(String msg) {
  116.     getServletContext().log(getClass().getName() + ": "+ msg);
  117.     }
  118.  
  119.     /**
  120.      * Returns a string that contains information about the servlet,
  121.      * such as its author, version, and copyright.  This method
  122.      * must be overridden in order to return this information.
  123.      * If it is not overridden, null is returned.
  124.      */
  125.     public String getServletInfo() {
  126.     return null;
  127.     }
  128.  
  129.     /**
  130.      *
  131.      * Initializes the servlet and logs the initialization. The init
  132.      * method is called once, automatically, by the network service
  133.      * each time it loads the servlet.  It is guaranteed to finish
  134.      * before any service requests are accepted.  On fatal
  135.      * initialization errors, an UnavailableException should be
  136.      * thrown.  Do not call call the method System.exit.
  137.      *
  138.      * <p>The init method stores the ServletConfig object.  Servlet
  139.      * writers who specialize this method should call either
  140.      * super.init, or store the ServletConfig object themselves.  If an
  141.      * implementor decides to store the ServletConfig object in a
  142.      * different location, then the getServletConfig method must also
  143.      * be overridden.
  144.      *
  145.      * @see UnavailableException
  146.      * @param config servlet configuration information
  147.      * @exception ServletException if a servlet exception has occurred
  148.      */
  149.     public void init(ServletConfig config) throws ServletException {
  150.     this.config = config;
  151.     log("init");
  152.     }
  153.  
  154.     /**
  155.      * Returns a servletConfig object containing any startup
  156.      * configuration information for this servlet.
  157.      */
  158.     public ServletConfig getServletConfig() {
  159.     return config;
  160.     }
  161.  
  162.     /**
  163.      * 
  164.      * Carries out a single request from the client.  The request
  165.      * object contains parameters provided by the client, and an input
  166.      * stream, which can also bring data to the servlet.  To return
  167.      * information to the client, write to the output stream of the
  168.      * response object.
  169.      *
  170.      * <p>Service requests handled after servlet initialization has
  171.      * completed.  Any requests for service that are received during
  172.      * initialization block until it is complete.
  173.      *
  174.      * <p>Note that servlets typically run inside multi-threaded
  175.      * network services, which can handle multiple service requests
  176.      * simultaneously.  It is the servlet writer's responsibility to
  177.      * synchronize access to any shared resources, such as database or
  178.      * network connections.  The simplest way to do this is to
  179.      * synchronize the entire service call.  This can have a major
  180.      * performance impact, however, and should be avoided whenever
  181.      * possible in favor of techniques that are less coarse.  For more
  182.      * information on synchronization, see the <a
  183.      * href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">the
  184.      * Java tutorial on multithreaded programming</a>.
  185.      *
  186.      *
  187.      * @param req the servlet request
  188.      * @param res the servlet response
  189.      * @exception ServletException if a servlet exception has occurred
  190.      * @exception IOException if an I/O exception has occurred
  191.      */
  192.     public abstract void service(ServletRequest req, ServletResponse res)
  193.     throws ServletException, IOException;
  194.  
  195.     /**
  196.      *
  197.      * Destroys the servlet, cleaning up whatever resources are being
  198.      * held, and logs the destruction in the servlet log file.  This
  199.      * method is called, once, automatically, by the network service
  200.      * each time it removes the servlet.  After destroy is run, it
  201.      * cannot be called again until the network service reloads the
  202.      * servlet.
  203.      *
  204.      * <p>When the network service removes a servlet, it calls destroy
  205.      * after all service calls have been completed, or a
  206.      * service-specific number of seconds have passed, whichever comes
  207.      * first.  In the case of long-running operations, there could be
  208.      * other threads running service requests when destroy is called.
  209.      * The servlet writer is responsible for making sure that any
  210.      * threads still in the service method complete. 
  211.      */
  212.     public void destroy() {
  213.     log("destroy");
  214.     }
  215.  
  216. }
  217.