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   /**
   23    * <p>Interface describing a collection of Valves that should be executed
   24    * in sequence when the <code>invoke()</code> method is invoked.  It is
   25    * required that a Valve somewhere in the pipeline (usually the last one)
   26    * must process the request and create the corresponding response, rather
   27    * than trying to pass the request on.</p>
   28    *
   29    * <p>There is generally a single Pipeline instance associated with each
   30    * Container.  The container's normal request processing functionality is
   31    * generally encapsulated in a container-specific Valve, which should always
   32    * be executed at the end of a pipeline.  To facilitate this, the
   33    * <code>setBasic()</code> method is provided to set the Valve instance that
   34    * will always be executed last.  Other Valves will be executed in the order
   35    * that they were added, before the basic Valve is executed.</p>
   36    *
   37    * @author Craig R. McClanahan
   38    * @author Peter Donald
   39    * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (Tue, 24 Oct 2006) $
   40    */
   41   
   42   public interface Pipeline {
   43   
   44   
   45       // ------------------------------------------------------------- Properties
   46   
   47   
   48       /**
   49        * <p>Return the Valve instance that has been distinguished as the basic
   50        * Valve for this Pipeline (if any).
   51        */
   52       public Valve getBasic();
   53   
   54   
   55       /**
   56        * <p>Set the Valve instance that has been distinguished as the basic
   57        * Valve for this Pipeline (if any).  Prioer to setting the basic Valve,
   58        * the Valve's <code>setContainer()</code> will be called, if it
   59        * implements <code>Contained</code>, with the owning Container as an
   60        * argument.  The method may throw an <code>IllegalArgumentException</code>
   61        * if this Valve chooses not to be associated with this Container, or
   62        * <code>IllegalStateException</code> if it is already associated with
   63        * a different Container.</p>
   64        *
   65        * @param valve Valve to be distinguished as the basic Valve
   66        */
   67       public void setBasic(Valve valve);
   68   
   69   
   70       // --------------------------------------------------------- Public Methods
   71   
   72   
   73       /**
   74        * <p>Add a new Valve to the end of the pipeline associated with this
   75        * Container.  Prior to adding the Valve, the Valve's
   76        * <code>setContainer()</code> method will be called, if it implements
   77        * <code>Contained</code>, with the owning Container as an argument.
   78        * The method may throw an
   79        * <code>IllegalArgumentException</code> if this Valve chooses not to
   80        * be associated with this Container, or <code>IllegalStateException</code>
   81        * if it is already associated with a different Container.</p>
   82        *
   83        * @param valve Valve to be added
   84        *
   85        * @exception IllegalArgumentException if this Container refused to
   86        *  accept the specified Valve
   87        * @exception IllegalArgumentException if the specifie Valve refuses to be
   88        *  associated with this Container
   89        * @exception IllegalStateException if the specified Valve is already
   90        *  associated with a different Container
   91        */
   92       public void addValve(Valve valve);
   93   
   94   
   95       /**
   96        * Return the set of Valves in the pipeline associated with this
   97        * Container, including the basic Valve (if any).  If there are no
   98        * such Valves, a zero-length array is returned.
   99        */
  100       public Valve[] getValves();
  101   
  102   
  103       /**
  104        * Remove the specified Valve from the pipeline associated with this
  105        * Container, if it is found; otherwise, do nothing.  If the Valve is
  106        * found and removed, the Valve's <code>setContainer(null)</code> method
  107        * will be called if it implements <code>Contained</code>.
  108        *
  109        * @param valve Valve to be removed
  110        */
  111       public void removeValve(Valve valve);
  112   
  113   
  114       /**
  115        * <p>Return the Valve instance that has been distinguished as the basic
  116        * Valve for this Pipeline (if any).
  117        */
  118       public Valve getFirst();
  119   
  120   
  121   }

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