tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@locus.apache.org
Subject cvs commit: jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat Realm.java Request.java Resources.java Response.java Session.java Store.java Valve.java Wrapper.java
Date Thu, 20 Jan 2000 06:33:39 GMT
craigmcc    00/01/19 22:33:39

  Added:       proposals/catalina/src/share/org/apache/tomcat Realm.java
                        Request.java Resources.java Response.java
                        Session.java Store.java Valve.java Wrapper.java
  Log:
  Check-in #3 of the basic interfaces for the "Catalina" proposal.
  
  Revision  Changes    Path
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Realm.java
  
  Index: Realm.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Realm.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.security.Principal;
  
  
  /**
   * A <b>Realm</b> is a read-only facade for an underlying security realm
   * used to authenticate individual users, and identify the security roles
   * associated with those users.  Realms can be attached at any Container
   * level, but will typically only be attached to a Context, or higher level,
   * Container.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Realm {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the Container with which this Realm has been associated.
       */
      public Container getContainer();
  
  
      /**
       * Set the Container with which this Realm has been associated.
       *
       * @param container The associated Container
       */
      public void setContainer(Container container);
  
  
      /**
       * Return descriptive information about this Realm implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Return the Principal associated with the specified username and
       * credentials, if there is one; otherwise return <code>null</code>.
       *
       * @param username Username of the Principal to look up
       * @param credentials Password or other credentials to use in
       *  authenticating this username
       */
      public Principal authenticate(String username, String credentials);
  
  
      /**
       * Return the Principal associated with the specified username and
       * credentials, if there is one; otherwise return <code>null</code>.
       *
       * @param username Username of the Principal to look up
       * @param credentials Password or other credentials to use in
       *  authenticating this username
       */
      public Principal authenticate(String username, byte[] credentials);
  
  
      /**
       * Return <code>true</code> if the specified Principal has the specified
       * security role, within the context of this Realm; otherwise return
       * <code>false</code>.
       *
       * @param principal Principal for whom the role is to be checked
       * @param role Security role to be checked
       */
      public boolean hasRole(Principal principal, String role);
  
  
  }
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Request.java
  
  Index: Request.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Request.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.InputStream;
  import java.io.IOException;
  import java.security.Principal;
  import java.util.Locale;
  import javax.servlet.ServletException;
  import javax.servlet.http.Cookie;
  import javax.servlet.http.HttpServletRequest;
  
  
  /**
   * A <b>Request</b> is the Tomcat-internal facade for an
   * <code>HttpServletRequest</code> that is to be processed, in order to
   * produce a corresponding Response.  
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Request {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the Context within which this Request is being processed.
       */
      public Context getContext();
  
  
      /**
       * Set the Context within which this Request is being processed.  This
       * must be called as soon as the appropriate Context is identified, because
       * it identifies the value to be returned by <code>getContextPath()</code>,
       * and thus enables parsing of the request URI.
       *
       * @param context The newly associated Context
       */
      public void setContext(Context context);
  
  
      /**
       * Return descriptive information about this Request implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      /**
       * Return the <code>HttpServletRequest</code> for which this object
       * is the facade.
       */
      public HttpServletRequest getRequest();
  
  
      /**
       * Return the Response with which this Request is associated.
       */
      public Response getResponse();
  
  
      /**
       * Set the Response with which this Request is associated.
       *
       * @param response The new associated response
       */
      public void setResponse(Response response);
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Add a Cookie to the set of Cookies associated with this Request.
       *
       * @param cookie The new cookie
       */
      public void addCookie(Cookie cookie);
  
  
      /**
       * Add a Header to the set of Headers associated with this Request.
       *
       * @param name The new header name
       * @param value The new header value
       */
      public void addHeader(String name, String value);
  
  
      /**
       * Add a Locale to the set of preferred Locales for this Request.  The
       * first added Locale will be the first one returned by getLocales().
       *
       * @param locale The new preferred Locale
       */
      public void addLocale(Locale locale);
  
  
      /**
       * Release all object references, and initialize instance variables, in
       * preparation for reuse of this object.
       */
      public void recycle();
  
  
      /**
       * Set the authentication type used for this request, if any; otherwise
       * set the type to <code>null</code>.  Typical values are "BASIC",
       * "DIGEST", or "SSL".
       *
       * @param type The authentication type used
       */
      public void setAuthType(String type);
  
  
      /**
       * Set the content length associated with this Request.
       *
       * @param length The new content length
       */
      public void setContentLength(int length);
  
  
      /**
       * Set the content type (and optionally the character encoding)
       * associated with this Request.  For example,
       * <code>text/html; charset=ISO-8859-4</code>.
       *
       * @param type The new content type
       */
      public void setContentType(String type);
  
  
      /**
       * Set the input stream associated with this Request.  This stream
       * will be wrapped by a Reader if <code>getReader()</code> is called.
       *
       * @param stream The new input stream
       */
      public void setInputStream(InputStream stream);
  
  
      /**
       * Set the HTTP request method used for this Request.
       *
       * @param method The request method
       */
      public void setMethod(String method);
  
  
      /**
       * Set the protocol name and version associated with this Request.
       *
       * @param protocol Protocol name and version
       */
      public void setProtocol(String protocol);
  
  
      /**
       * Set the remote IP address associated with this Request.  NOTE:  This
       * value will be used to resolve the value for <code>getRemoteHost()</code>
       * if that method is called.
       *
       * @param remote The remote IP address
       */
      public void setRemoteAddr(String remote);
  
  
      /**
       * Set the unparsed request URI for this Request.  This value cannot be
       * parsed until <code>setContext()</code> has been called.  <b>FIXME</b>:
       * how and when is parsing initiated?
       *
       * @param uri The request URI
       */
      public void setRequestURI(String uri);
  
  
      /**
       * Set the name of the scheme associated with this request.  Typical values
       * are <code>http</code>, <code>https</code>, and <code>ftp</code>.
       *
       * @param scheme The scheme
       */
      public void setScheme(String scheme);
  
  
      /**
       * Set the name of the server (virtual host) to process this request.
       *
       * @param name The server name
       */
      public void setServerName(String name);
  
  
      /**
       * Set the port number of the server to process this request.
       *
       * @param port The server port
       */
      public void setServerPort(int port);
  
  
      /**
       * Set the value to be returned by <code>isSecure()</code>
       * for this Request.
       *
       * @param secure The new isSecure value
       */
      public void setSecure(boolean secure);
  
  
      /**
       * Set the Principal who has been authenticated for this Request.  This
       * value is also used to calculate the value to be returned by the
       * <code>getRemoteUser()</code> method.
       *
       * @param principal The user Principal
       */
      public void setUserPrincipal(Principal principal);
  
  
  }
  
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Resources.java
  
  Index: Resources.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Resources.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.InputStream;
  import java.net.MalformedURLException;
  import java.net.URL;
  
  
  /**
   * A <b>Resources</b> is a generic interface for the resource acquisition
   * and lookup methods of the ServletContext interface.
   * <p>
   * A Resources object is generally attached to a Context, or higher level,
   * Container.  However, a Connector may also provide a Resources object
   * associated with a particular Request, which should be treated by any
   * Container processing this request as overriding any Resources object
   * normally configured for this Container.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Resources {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the Container with which this Resources has been associated.
       */
      public Container getContainer();
  
  
      /**
       * Set the Container with which this Resources has been associated.
       *
       * @param container The associated Container
       */
      public void setContainer(Container container);
  
  
      /**
       * Return descriptive information about this Resources implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Return the MIME type of the specified file, or <code>null</code> if
       * the MIME type is not known.  The MIME type is determined by the
       * configuration of the servlet container, and may be specified in a
       * web application descriptor.  Common MIME types are
       * <code>"text/html"</code> and <code>"image/gif"</code>.
       *
       * @param file Name of the file whose MIME type is to be determined
       */
      public String getMimeType(String file);
  
  
      /**
       * Return the real path for a given virtual path.  For example, the
       * virtual path <code>"/index.html"</code> has a real path of whatever
       * file on the server's filesystem would be served by a request for
       * <code>"/index.html"</code>.
       * <p>
       * The real path returned will be in a form appropriate to the computer
       * and operating system on which the servlet container is running,
       * including the proper path separators.  This method returns
       * <code>null</code> if the servlet container cannot translate the
       * virtual path to a real path for any reason (such as when the content
       * is being made available from a <code>.war</code> archive).
       *
       * @param path The virtual path to be translated
       */
      public String getRealPath(String path);
  
  
      /**
       * Return a URL to the resource that is mapped to the specified path.
       * The path must begin with a "/" and is interpreted as relative to
       * the current context root.
       * <p>
       * This method allows the Container to make a resource available to
       * servlets from any source.  Resources can be located on a local or
       * remote file system, in a database, or in a <code>.war</code> file.
       * <p>
       * The servlet container must implement the URL handlers and
       * <code>URLConnection</code> objects that are necessary to access
       * the resource.
       * <p>
       * This method returns <code>null</code> if no resource is mapped to
       * the pathname.
       * <p>
       * Some Containers may allow writing to the URL returned by this method,
       * using the methods of the URL class.
       * <p>
       * The resource content is returned directly, so be aware that
       * requesting a <code>.jsp</code> page returns the JSP source code.
       * Use a <code>RequestDispatcher</code> instead to include results
       * of an execution.
       * <p>
       * This method has a different purpose than
       * <code>java.lang.Class.getResource()</code>, which looks up resources
       * based on a class loader.  This method does not use class loaders.
       *
       * @param path The path to the desired resource
       *
       * @exception MalformedURLException if the pathname is not given
       *  in the correct form
       */
      public URL getResource(String path) throws MalformedURLException;
  
  
      /**
       * Return the resource located at the named path as an
       * <code>InputStream</code> object.
       * <p>
       * The data in the <code>InputStream</code> can be of any type or length.
       * The path must be specified according to the rules given in
       * <code>getResource()</code>.  This method returns <code>null</code>
       * if no resource exists at the specified path.
       * <p>
       * Meta-information such as content length and content type that is
       * available via the <code>getResource()</code> method is lost when
       * using this method.
       * <p>
       * The servlet container must implement the URL handlers and
       * <code>URLConnection</code> objects that are necessary to access
       * the resource.
       * <p>
       * This method is different from
       * <code>java.lang.Class.getResourceAsStream()</code>, which uses a
       * class loader.  This method allows servlet containers to make a
       * resource available to a servlet from any location, without using
       * a class loader.
       *
       * @param path The path to the desired resource
       */
      public InputStream getResourceAsStream(String path);
  
  
  }
  
  
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Response.java
  
  Index: Response.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Response.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.IOException;
  import java.io.OutputStream;
  import java.util.Enumeration;
  import javax.servlet.ServletException;
  import javax.servlet.http.HttpServletResponse;
  
  
  /**
   * A <b>Response</b> is the Tomcat-internal facade for an
   * <code>HttpServletResponse</code> that is to be produced, based on the
   * processing of a corresponding Request.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Response {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the Context with which this Response is associated.
       */
      public Context getContext();
  
  
      /**
       * Set the Context with which this Response is associated.  This should
       * be called as soon as the appropriate Context is identified.
       *
       * @param context The associated Context
       */
      public void setContext(Context context);
  
  
      /**
       * Return descriptive information about this Response implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      /**
       * Return the Request with which this Response is associated.
       */
      public Request getRequest();
  
  
      /**
       * Set the Request with which this Response is associated.
       *
       * @param request The new associated request
       */
      public void setRequest(Request request);
  
  
      /**
       * Return the <code>HttpServletResponse</code> for which this object
       * is the facade.
       */
      public HttpServletResponse getResponse();
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Ensure that the HTTP headers (and any buffered output) have been
       * flushed to the output stream, even if it was never acquired by
       * a servlet.
       *
       * @exception IOException if an input/output error occurs
       */
      public void flush() throws IOException;
  
  
      /**
       * Return the content length that was set or calculated for this Response.
       */
      public int getContentLength();
  
  
      /**
       * Return the content type that was set or calculated for this response,
       * or <code>null</code> if no content type was set.
       */
      public String getContentType();
  
  
      /**
       * Return the value for the specified header, or <code>null</code> if this
       * header has not been set.  If more than one value was added for this
       * name, only the first is returned; use getHeaderValues() to retrieve all
       * of them.
       *
       * @param name Header name to look up
       */
      public String getHeader(String name);
  
  
      /**
       * Return an enumeration all the header names set for this response, or
       * an empty Enumeration if no headers have been set.
       */
      public Enumeration getHeaderNames();
  
  
      /**
       * Return an enumeration of all the header values associated with the
       * specified header name, or an empty enumeration if there are no such
       * header values.
       *
       * @param name Header name to look up
       */
      public Enumeration getHeaderValues(String name);
  
  
      /**
       * Return the HTTP status code associated with this Response.
       */
      public int getStatus();
  
  
      /**
       * Release all object references, and initialize instance variables, in
       * preparation for reuse of this object.
       */
      public void recycle();
  
  
      /**
       * Set the output stream associated with this Response.  This stream will
       * be wrapped by a PrintWriter if <code>getWriter()</code> is called.
       *
       * @param stream The new output stream
       */
      public void setOutputStream(OutputStream stream);
  
  
  }
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Session.java
  
  Index: Session.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Session.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.IOException;
  import javax.servlet.ServletException;
  import javax.servlet.http.HttpSession;
  
  
  /**
   * A <b>Session</b> is the Tomcat-internal facade for an
   * <code>HttpSession</code> that is used to maintain state information
   * between requests for a particular user of a web application.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Session {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the creation time for this session.
       */
      public long getCreationTime();
  
  
      /**
       * Set the creation time for this session.  This method is called by the
       * Manager when an existing Session instance is reused.
       *
       * @param time The new creation time
       */
      public void setCreationTime(long time);
  
  
      /**
       * Return the session identifier for this session.
       */
      public String getId();
  
  
      /**
       * Set the session identifier for this session.
       *
       * @param id The new session identifier
       */
      public void setId(String id);
  
  
      /**
       * Return descriptive information about this Session implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      /**
       * Return the last time the client sent a request associated with this
       * session, as the number of milliseconds since midnight, January 1, 1970
       * GMT.  Actions that your application takes, such as getting or setting
       * a value associated with the session, do not affect the access time.
       */
      public long getLastAccessedTime();
  
  
      /**
       * Return the Manager within which this Session is valid.
       */
      public Manager getManager();
  
  
      /**
       * Set the Manager within which this Session is valid.
       *
       * @param manager The new Manager
       */
      public void setManager(Manager manager);
  
  
      /**
       * Return the maximum time interval, in seconds, between client requests
       * before the servlet container will invalidate the session.  A negative
       * time indicates that the session should never time out.
       */
      public int getMaxInactiveInterval();
  
  
      /**
       * Set the maximum time interval, in seconds, between client requests
       * before the servlet container will invalidate the session.  A negative
       * time indicates that the session should never time out.
       *
       * @param interval The new maximum interval
       */
      public void setMaxInactiveInterval(int interval);
  
  
      /**
       * Return the <code>HttpSession</code> for which this object
       * is the facade.
       */
      public HttpSession getSession();
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Update the accessed time information for this session.  This method
       * should be called by the context when a request comes in for a particular
       * session, even if the application does not reference it.
       */
      public void access();
  
  
      /**
       * Perform the internal processing required to invalidate this session,
       * without triggering an exception if the session has already expired.
       */
      public void expire();
  
  
      /**
       * Release all object references, and initialize instance variables, in
       * preparation for reuse of this object.
       */
      public void recycle();
  
  
  }
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Store.java
  
  Index: Store.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Store.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.IOException;
  
  
  /**
   * A <b>Store</b> is the abstraction of a Tomcat component that provides
   * persistent storage and loading of Sessions and their associated user data.
   * Implementations are free to save and load the Sessions to any media they
   * wish, but it is assumed that saved Sessions are persistent across
   * server or context restarts.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Store {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the number of Sessions present in this Store.
       *
       * @exception IOException if an input/output error occurs
       */
      public int getSize() throws IOException;
  
  
      /**
       * Return descriptive information about this Store implementation and
       * the corresponding version number, in the format
       * <code>&lt;description&gt;/&lt;version&gt;</code>.
       */
      public String getInfo();
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Return an array containing the session identifiers of all Sessions
       * currently saved in this Store.  If there are no such Sessions, a
       * zero-length array is returned.
       *
       * @exception IOException if an input/output error occurred
       */
      public String[] keys() throws IOException;
  
  
      /**
       * Load and return the Session associated with the specified session
       * identifier from this Store, without removing it.  If there is no
       * such stored Session, return <code>null</code>.
       *
       * @param id Session identifier of the session to load
       *
       * @exception ClassNotFoundException if a deserialization error occurs
       * @exception IOException if an input/output error occurs
       */
      public Session load(String id)
          throws ClassNotFoundException, IOException;
  
  
      /**
       * Remove the Session with the specified session identifier from
       * this Store, if present.  If no such Session is present, this method
       * takes no action.
       *
       * @param id Session identifier of the Session to be removed
       *
       * @exception IOException if an input/output error occurs
       */
      public void remove(String id) throws IOException;
  
  
      /**
       * Save the specified Session into this Store.  Any previously saved
       * information for the associated session identifier is replaced.
       *
       * @param session Session to be saved
       *
       * @exception IOException if an input/output error occurs
       */
      public void save(Session session) throws IOException;
  
  
  }
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Valve.java
  
  Index: Valve.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Valve.java,v 1.1 2000/01/20 06:33:38 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:38 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import java.io.IOException;
  import javax.servlet.ServletException;
  
  
  /**
   * A <b>Valve</b> intercepts request processing prior to, and after, the
   * call to a Container's <code>invoke()</code> method.  Conceptually, a
   * chain of Valves can be associated (in a pipeline) with a particular
   * Container.
   * <p>
   * An individual Valve can either process the request itself, or hand off
   * processing to a subsequent Valve in the pipeline, possibly after having
   * modified some properties of the Request.  Within a Valve implementation,
   * you place your functional logic in the <code>invoke()</code> method, which
   * is called by the previous Valve in the pipeline (or by the enclosing
   * Container in the standard implementation).  See the method description
   * below for the detailed contracts your <code>invoke()</code> method
   * must conform to.
   * <p>
   * <b>NOTE</b>:  The Valve concept was first introduced in the development
   * branch of Apache JServ (http://java.apache.org), to provide the ability
   * to interject processing logic at any desired Container level.  With
   * respect to the Catalina proposal, this should be considered an alternative
   * design to the originally proposed <code>Interceptor</code> interface.
   * With respect to Interceptor, a Valve exhibits the following differences:
   * <ul>
   * <li>Calls to subsequent Valves in the pipeline are nested on the stack.
   *     Therefore, local variables (within the <code>invoke()</code> method
   *     can be used to maintain state information for a particular request
   *     being handled by a particular thread.  With the Interceptor design,
   *     you must store request-local state in between calls to the
   *     <code>preService()</code> and <code>postService()</code> methods --
   *     probably as custom request attributes.
   * <li>Due to the nested nature of calls in the pipeline, more stack space
   *     is consumed for the Valve design than the Interceptor design.  In
   *     practice, this is unlikely to be a significant issue.
   * <li>Valves can intercept exceptions thrown by subsequent Valves, or the
   *     processing logic of subordinate Containers.  This allows a Valve to
   *     allocate resources, call the subordinate logic, and reliably release
   *     those resources, even in the face of exceptions.  This is not
   *     possible with the currently specified Interceptor design.
   * <li>Advanced Valve implementations may elect to replace one or both of the
   *     arguments to <code>invoke()</code> (the Request being processed and the
   *     Response being produced).  This would allow a Valve to implement post
   *     processing filters, if desired, before producing the final response
   *     returned to the caller of this Valve.
   * </ul>
   * <p>
   * <b>HISTORICAL NOTE</b>:  The "Valve" name was assigned to this concept
   * because a valve is what you use in a real world pipeline to control and/or
   * modify flows through it.
   *
   * @author Craig R. McClanahan
   * @author Gunnar Rjnning
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:38 $
   */
  
  public interface Valve {
  
  
      //-------------------------------------------------------------- Properties
  
  
      /**
       * Return the Container to which this Valve was added, if any.
       */
      public Container getContainer();
  
  
      /**
       * Set the Container to which this Valve is being added.  This method
       * must be called from within the <code>addValve()</code> method of
       * the specified Container.  This Valve may refuse to become attached
       * to the specified Container by throwing an exception.
       *
       * @param container Container to which this Valve is being added
       *
       * @exception IllegalArgumentException if this Valve refused to be
       *  attached to the specified Container
       * @exception IllegalStateException if this Valve is already
       *  attached to a different Container.
       */
      public void setContainer(Container container);
  
  
      /**
       * Return descriptive information about this Valve implementation.
       */
      public String getInfo();
  
  
      //---------------------------------------------------------- Public Methods
  
  
      /**
       * The method that is called when it is this Valve's turn to process a
       * particular request/response combination.  A Valve <b>MAY</b> do any
       * of the following things, in this order:
       * <ul>
       * <li>Examine the properties of the incoming Request (and the underlying
       *     HttpServletRequest that it represents).
       * <li>Modify the properties of the incoming Request.
       * <li>Create a completed Response, in the same manner that a servlet
       *     would do so.
       * <li>If a completed Response was not created, pass this Request and
       *     Response on to the next Valve in this pipeline, in an
       *     implementation-dependent manner.  If your Valve extends the
       *     standard base class
       *     (<code>org.apache.tomcat.core.ValveBase</code>),
       *     this is done by calling <code>invokeNext()</code>.
       * <li>Examine, but not modify, the properties of the outgoing Response,
       *     as well as the final Request, which might have been modified by a
       *     subsequent Valve, or by execution of a call to
       *     <code>RequestDispatcher.forward()</code> within the servlet
       *     that processed this Request.
       * </ul>
       * <p>
       * A Valve <b>MUST NOT</b> do any of the following things:
       * <ul>
       * <li>Change request properties that have already been used to direct
       *     the flow of processing control for this request (for instance,
       *     trying to change the virtual host to which a Request should be
       *     sent from a pipeline attached to a Host or Context in the
       *     standard implementation).
       * <li>Create a completed Response <strong>AND</strong> pass this
       *     Request and Response on to the next Valve in the pipeline.
       * <li>Consume bytes from the input stream associated with the Request.
       * <li>Append bytes to the output stream associated with
       *     the Response.
       * <li>Modify the HTTP headers included with the Response.
       * </ul>
       * <p>
       *
       * @param request The servlet request to be processed
       * @param response The servlet response to be created
       *
       * @exception IOException if an input/output error occurs
       * @exception ServletException if a servlet error occurs
       */
      public void invoke(Request request, Response response)
  	throws IOException, ServletException;
  
  
  }
  
  
  
  1.1                  jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Wrapper.java
  
  Index: Wrapper.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-tomcat/proposals/catalina/src/share/org/apache/tomcat/Wrapper.java,v 1.1 2000/01/20 06:33:39 craigmcc Exp $
   * $Revision: 1.1 $
   * $Date: 2000/01/20 06:33:39 $
   *
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowlegement:  
   *       "This product includes software developed by the 
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowlegement may appear in the software itself,
   *    if and wherever such third-party acknowlegements normally appear.
   *
   * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Group.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   * [Additional notices, if required by prior licensing conditions]
   *
   */ 
  
  
  package org.apache.tomcat;
  
  
  import javax.servlet.Servlet;
  import javax.servlet.ServletException;
  
  
  /**
   * A <b>Wrapper</b> is a Container that represents an individual servlet
   * definition from the deployment descriptor of the web application.  It
   * provides a convenient mechanism to use Interceptors that see every single
   * request to the servlet represented by this definition.
   * <p>
   * Implementations of Wrapper are responsible for managing the servlet life
   * cycle for their underlying servlet class, including calling init() and
   * destroy() at appropriate times, as well as respecting the existence of
   * the SingleThreadModel declaration on the servlet class itself.
   * <p>
   * The parent Container attached to a Wrapper will generally be an
   * implementation of Context, representing the servlet context (and
   * therefore the web application) within which this servlet executes.
   * <p>
   * Child Containers are not allowed on Wrapper implementations, so the
   * <code>addChild()</code> method should throw an
   * <code>IllegalArgumentException</code>.
   *
   * @author Craig R. McClanahan
   * @version $Revision: 1.1 $ $Date: 2000/01/20 06:33:39 $
   */
  
  public interface Wrapper extends Container {
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the servlet configuration definitions for this servlet.
       */
      public WrapperConfig getConfiguration();
  
  
      /**
       * Set the servlet configuration definitions for this servlet.
       *
       * @param config The new servlet configuration definitions
       */
      public void setConfiguration(WrapperConfig config);
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Add a new security role reference record to the set of records for
       * this servlet.
       *
       * @param name Role name used within this servlet
       * @param link Role name used within the web application
       * @param description Description of this security role reference
       */
      public void addSecurityRole(String name, String link,
  				String description);
  
  
      /**
       * Allocate an initialized instance of this Servlet that is ready to have
       * its <code>service()</code> method called.  If the servlet class does
       * not implement <code>SingleThreadModel</code>, the (only) initialized
       * instance may be returned immediately.  If the servlet class implements
       * <code>SingleThreadModel</code>, the Wrapper implementation must ensure
       * that this instance is not allocated again until it is deallocated by a
       * call to <code>deallocate()</code>.
       * <p>
       * <b>FIXME:  Provide a way to avoid waiting forever.</b>
       */
      public Servlet allocate();
  
  
      /**
       * Return this previously allocated servlet to the pool of available
       * instances.  If this servlet class does not implement SingleThreadModel,
       * no action is actually required.
       *
       * @param servlet The servlet to be returned
       */
      public void deallocate(Servlet servlet);
  
  
      /**
       * Return the security role reference description associated with the
       * specified role name, if any; otherwise return <code>null</code>.
       *
       * @param name Security role used within this servlet
       */
      public String findSecurityDescription(String name);
  
  
      /**
       * Return the security role link associated with the specified role name,
       * if any.  If no mapping has been defined, the role name itself is
       * returned.
       *
       * @param name Security role used within this servlet
       */
      public String findSecurityLink(String name);
  
  
      /**
       * Return the set of security role reference names associated with
       * this servlet, if any; otherwise return a zero-length array.
       */
      public String[] findSecurityNames();
  
  
      /**
       * Load and initialize an instance of this servlet, if there is not already
       * at least one initialized instance.  This can be used, for example, to
       * load servlets that are marked in the deployment descriptor to be loaded
       * at server startup time.
       *
       * @exception ServletException if thrown by the init() method of the
       *  loaded servlet
       */
      public void load() throws ServletException;
  
  
      /**
       * Remove any security role reference for the specified role name.
       *
       * @param name Security role used within this servlet to be removed
       */
      public void removeSecurityRole(String name);
  
  
      /**
       * Unload all initialized instances of this servlet, after calling the
       * <code>destroy()</code> method for each instance.  This can be used,
       * for example, prior to shutting down the entire servlet engine, or
       * prior to reloading all of the classes from the Loader associated with
       * our Loader's repository.
       */
      public void unload();
  
  
  }
  
  
  

Mime
View raw message