Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    * 
    9    *      http://www.apache.org/licenses/LICENSE-2.0
   10    * 
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   
   19   package org.apache.catalina;
   20   
   21   
   22   import java.io.IOException;
   23   import javax.servlet.ServletException;
   24   
   25   import org.apache.catalina.connector.Request;
   26   import org.apache.catalina.connector.Response;
   27   
   28   
   29   /**
   30    * <p>A <b>Valve</b> is a request processing component associated with a
   31    * particular Container.  A series of Valves are generally associated with
   32    * each other into a Pipeline.  The detailed contract for a Valve is included
   33    * in the description of the <code>invoke()</code> method below.</p>
   34    *
   35    * <b>HISTORICAL NOTE</b>:  The "Valve" name was assigned to this concept
   36    * because a valve is what you use in a real world pipeline to control and/or
   37    * modify flows through it.
   38    *
   39    * @author Craig R. McClanahan
   40    * @author Gunnar Rjnning
   41    * @author Peter Donald
   42    * @version $Revision: 796156 $ $Date: 2009-07-21 08:29:47 +0200 (Tue, 21 Jul 2009) $
   43    */
   44   
   45   public interface Valve {
   46   
   47   
   48       //-------------------------------------------------------------- Properties
   49   
   50   
   51       /**
   52        * Return descriptive information about this Valve implementation.
   53        */
   54       public String getInfo();
   55   
   56   
   57       /**
   58        * Return the next Valve in the pipeline containing this Valve, if any.
   59        */
   60       public Valve getNext();
   61   
   62   
   63       /**
   64        * Set the next Valve in the pipeline containing this Valve.
   65        *
   66        * @param valve The new next valve, or <code>null</code> if none
   67        */
   68       public void setNext(Valve valve);
   69   
   70   
   71       //---------------------------------------------------------- Public Methods
   72   
   73   
   74       /**
   75        * Execute a periodic task, such as reloading, etc. This method will be
   76        * invoked inside the classloading context of this container. Unexpected
   77        * throwables will be caught and logged.
   78        */
   79       public void backgroundProcess();
   80   
   81   
   82       /**
   83        * <p>Perform request processing as required by this Valve.</p>
   84        *
   85        * <p>An individual Valve <b>MAY</b> perform the following actions, in
   86        * the specified order:</p>
   87        * <ul>
   88        * <li>Examine and/or modify the properties of the specified Request and
   89        *     Response.
   90        * <li>Examine the properties of the specified Request, completely generate
   91        *     the corresponding Response, and return control to the caller.
   92        * <li>Examine the properties of the specified Request and Response, wrap
   93        *     either or both of these objects to supplement their functionality,
   94        *     and pass them on.
   95        * <li>If the corresponding Response was not generated (and control was not
   96        *     returned, call the next Valve in the pipeline (if there is one) by
   97        *     executing <code>getNext().invoke()</code>.
   98        * <li>Examine, but not modify, the properties of the resulting Response
   99        *     (which was created by a subsequently invoked Valve or Container).
  100        * </ul>
  101        *
  102        * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
  103        * <ul>
  104        * <li>Change request properties that have already been used to direct
  105        *     the flow of processing control for this request (for instance,
  106        *     trying to change the virtual host to which a Request should be
  107        *     sent from a pipeline attached to a Host or Context in the
  108        *     standard implementation).
  109        * <li>Create a completed Response <strong>AND</strong> pass this
  110        *     Request and Response on to the next Valve in the pipeline.
  111        * <li>Consume bytes from the input stream associated with the Request,
  112        *     unless it is completely generating the response, or wrapping the
  113        *     request before passing it on.
  114        * <li>Modify the HTTP headers included with the Response after the
  115        *     <code>getNext().invoke()</code> method has returned.
  116        * <li>Perform any actions on the output stream associated with the
  117        *     specified Response after the <code>getNext().invoke()</code> method has
  118        *     returned.
  119        * </ul>
  120        *
  121        * @param request The servlet request to be processed
  122        * @param response The servlet response to be created
  123        *
  124        * @exception IOException if an input/output error occurs, or is thrown
  125        *  by a subsequently invoked Valve, Filter, or Servlet
  126        * @exception ServletException if a servlet error occurs, or is thrown
  127        *  by a subsequently invoked Valve, Filter, or Servlet
  128        */
  129       public void invoke(Request request, Response response)
  130           throws IOException, ServletException;
  131   
  132       
  133       /**
  134        * Process a Comet event.
  135        *
  136        * @param request The servlet request to be processed
  137        * @param response The servlet response to be created
  138        *
  139        * @exception IOException if an input/output error occurs, or is thrown
  140        *  by a subsequently invoked Valve, Filter, or Servlet
  141        * @exception ServletException if a servlet error occurs, or is thrown
  142        *  by a subsequently invoked Valve, Filter, or Servlet
  143        */
  144       public void event(Request request, Response response, CometEvent event)
  145           throws IOException, ServletException;
  146   
  147   
  148   }

Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]