You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@apache.org on 2001/01/23 03:49:38 UTC
cvs commit: jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina Contained.java ValveContext.java Pipeline.java Valve.java
craigmcc 01/01/22 18:49:38
Modified: catalina/src/share/org/apache/catalina Pipeline.java
Valve.java
Added: catalina/src/share/org/apache/catalina Contained.java
ValveContext.java
Log:
First of several check-ins that implement the changes to the Valve API,
per the revised release plan. The changes simplify Valve creation and
reduce dependencies on the implementation of pipelines. For most valves
(that extend ValveBase), only two changes are required:
(1) Change the invoke() method signature to:
public void invoke(Reqeust request, Response response,
ValveContext valveContext)
throws IOException, ServletException;
(2) Change calls to invokeNext() to:
valveContext.invokeNext(request, response);
Additional changes include:
- Pipeline is now implemented as a separate object, with a class that can
be reused across Container implementations.
- New "Contained" interface encapsulates the method signatures required
when a class has a relationship with exactly one Container.
- New "ValveContext" interface encapsulates the functionality necessary
to call the next Valve in a Pipeline (if any) without exposing anything
about the mechanism actually used. This interface is analogous to the
javax.servlet.FilterConfig interface in the 2.3 servlet API.
Other check-ins are split to avoid going over the line count limit.
Revision Changes Path
1.2 +77 -23 jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Pipeline.java
Index: Pipeline.java
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Pipeline.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Pipeline.java 2000/08/11 05:24:10 1.1
+++ Pipeline.java 2001/01/23 02:49:37 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Pipeline.java,v 1.1 2000/08/11 05:24:10 craigmcc Exp $
- * $Revision: 1.1 $
- * $Date: 2000/08/11 05:24:10 $
+ * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Pipeline.java,v 1.2 2001/01/23 02:49:37 craigmcc Exp $
+ * $Revision: 1.2 $
+ * $Date: 2001/01/23 02:49:37 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -65,37 +65,70 @@
package org.apache.catalina;
+import java.io.IOException;
+import javax.servlet.ServletException;
+
+
/**
- * An optional interface, normally implemented by a Container, that indicates
- * support for a pipeline of <b>Valves</b> is present. When pipeline support
- * is present, the Container's <code>invoke()</code> method will call the
- * <code>invoke()</code> method of the first added Valve, which will either
- * generate the response or pass the request on to the next Valve in the
- * pipeline.
- * <p>
- * The Container must ensure that at least one Valve in the pipeline actually
- * generates the response and returns. Typically, this is accomplished by
- * configuring the Container's normal processing (in the absence of any
- * other Valves) as a Valve that always appears last in the pipeline.
+ * <p>Interface describing a collection of Valves that should be executed
+ * in sequence when the <code>invoke()</code> method is invoked. It is
+ * required that a Valve somewhere in the pipeline (usually the last one)
+ * must process the request and create the corresponding response, rather
+ * than trying to pass the request on.</p>
+ *
+ * <p>There is generally a single Pipeline instance associated with each
+ * Container. The container's normal request processing functionality is
+ * generally encapsulated in a container-specific Valve, which should always
+ * be executed at the end of a pipeline. To facilitate this, the
+ * <code>setBasic()</code> method is provided to set the Valve instance that
+ * will always be executed last. Other Valves will be executed in the order
+ * that they were added, before the basic Valve is executed.</p>
*
* @author Craig R. McClanahan
- * @version $Revision: 1.1 $ $Date: 2000/08/11 05:24:10 $
+ * @author Peter Donald
+ * @version $Revision: 1.2 $ $Date: 2001/01/23 02:49:37 $
*/
public interface Pipeline {
+ // ------------------------------------------------------------- Properties
+
+
+ /**
+ * <p>Return the Valve instance that has been distinguished as the basic
+ * Valve for this Pipeline (if any).
+ */
+ public Valve getBasic();
+
+
+ /**
+ * <p>Set the Valve instance that has been distinguished as the basic
+ * Valve for this Pipeline (if any). Prioer to setting the basic Valve,
+ * the Valve's <code>setContainer()</code> will be called, if it
+ * implements <code>Contained</code>, with the owning Container as an
+ * argument. The method may throw an <code>IllegalArgumentException</code>
+ * if this Valve chooses not to be associated with this Container, or
+ * <code>IllegalStateException</code> if it is already associated with
+ * a different Container.</p>
+ *
+ * @param valve Valve to be distinguished as the basic Valve
+ */
+ public void setBasic(Valve valve);
+
+
// --------------------------------------------------------- Public Methods
/**
- * Add a new Valve to the end of the pipeline associated with this
+ * <p>Add a new Valve to the end of the pipeline associated with this
* Container. Prior to adding the Valve, the Valve's
- * <code>setContainer</code> method must be called, with this Container
- * as an argument. The method may throw an
+ * <code>setContainer()</code> method will be called, if it implements
+ * <code>Contained</code>, with the owning Container as an argument.
+ * The method may throw an
* <code>IllegalArgumentException</code> if this Valve chooses not to
* be associated with this Container, or <code>IllegalStateException</code>
- * if it is already associated with a different Container.
+ * if it is already associated with a different Container.</p>
*
* @param valve Valve to be added
*
@@ -110,15 +143,36 @@
/**
- * Return the first Valve in the pipeline associated with this Container.
- * If there are no such Valves, <code>null</code> is returned.
+ * Return the set of Valves in the pipeline associated with this
+ * Container, including the basic Valve (if any). If there are no
+ * such Valves, a zero-length array is returned.
+ */
+ public Valve[] getValves();
+
+
+ /**
+ * Cause the specified request and response to be processed by the Valves
+ * associated with this pipeline, until one of these valves causes the
+ * response to be created and returned. The implementation must ensure
+ * that multiple simultaneous requests (on different threads) can be
+ * processed through the same Pipeline without interfering with each
+ * other's control flow.
+ *
+ * @param request The servlet request we are processing
+ * @param response The servlet response we are creating
+ *
+ * @exception IOException if an input/output error occurs
+ * @exception ServletException if a servlet exception is thrown
*/
- public Valve findValves();
+ public void invoke(Request request, Response response)
+ throws IOException, ServletException;
/**
* Remove the specified Valve from the pipeline associated with this
- * Container, if it is found; otherwise, do nothing.
+ * Container, if it is found; otherwise, do nothing. If the Valve is
+ * found and removed, the Valve's <code>setContainer(null)</code> method
+ * will be called if it implements <code>Contained</code>.
*
* @param valve Valve to be removed
*/
1.2 +28 -69 jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Valve.java
Index: Valve.java
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Valve.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Valve.java 2000/08/11 05:24:12 1.1
+++ Valve.java 2001/01/23 02:49:37 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Valve.java,v 1.1 2000/08/11 05:24:12 craigmcc Exp $
- * $Revision: 1.1 $
- * $Date: 2000/08/11 05:24:12 $
+ * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Valve.java,v 1.2 2001/01/23 02:49:37 craigmcc Exp $
+ * $Revision: 1.2 $
+ * $Date: 2001/01/23 02:49:37 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -70,17 +70,19 @@
/**
- * A <b>Valve</b> is a request processing component associated with a
- * particular Container. A series of Valves may be associated with the
- * same Container, creating a request processing pipeline.
- * <p>
+ * <p>A <b>Valve</b> is a request processing component associated with a
+ * particular Container. A series of Valves are generally associated with
+ * each other into a Pipeline. The detailed contract for a Valve is included
+ * in the description of the <code>invoke()</code> method below.</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/08/11 05:24:12 $
+ * @author Peter Donald
+ * @version $Revision: 1.2 $ $Date: 2001/01/23 02:49:37 $
*/
public interface Valve {
@@ -90,66 +92,19 @@
/**
- * Return the Container with which this Valve is associated, if any.
- */
- public Container getContainer();
-
-
- /**
- * Set the Container with which this Valve is associated.
- *
- * @param container The newly associated Container
- *
- * @exception IllegalArgumentException if this Valve refused to be
- * associated with the specified Container
- * @exception IllegalStateException if this Valve is already
- * associated a different Container.
- */
- public void setContainer(Container container);
-
-
- /**
* Return descriptive information about this Valve implementation.
*/
public String getInfo();
- /**
- * Return the next Valve in the pipeline containing this Valve, if any.
- */
- public Valve getNext();
-
-
- /**
- * Set the next Valve in the pipeline containing this Valve.
- *
- * @param valve The new next valve, or <code>null</code> if none
- */
- public void setNext(Valve valve);
-
-
- /**
- * Return the previous Valve in the pipeline containing this Valve, if any.
- */
- public Valve getPrevious();
-
-
- /**
- * Set the previous Valve in the pipeline containing this Valve.
- *
- * @param valve The new previous valve, or <code>null</code> if none
- */
- public void setPrevious(Valve valve);
-
-
//---------------------------------------------------------- Public Methods
/**
- * Perform request processing as required by this Valve.
- * <p>
- * An individual Valve <b>MAY</b> perform the following actions, in
- * the specified order:
+ * <p>Perform request processing as required by this Valve.</p>
+ *
+ * <p>An individual Valve <b>MAY</b> perform the following actions, in
+ * the specified order:</p>
* <ul>
* <li>Examine and/or modify the properties of the specified Request and
* Response.
@@ -160,12 +115,12 @@
* and pass them on.
* <li>If the corresponding Response was not generated (and control was not
* returned, call the next Valve in the pipeline (if there is one) by
- * executing <code>getNext().invoke()</code>.
+ * executing <code>context.invokeNext()</code>.
* <li>Examine, but not modify, the properties of the resulting Response
* (which was created by a subsequently invoked Valve or Container).
* </ul>
- * <p>
- * A Valve <b>MUST NOT</b> do any of the following things:
+ *
+ * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
* <ul>
* <li>Change request properties that have already been used to direct
* the flow of processing control for this request (for instance,
@@ -178,20 +133,24 @@
* unless it is completely generating the response, or wrapping the
* request before passing it on.
* <li>Modify the HTTP headers included with the Response after the
- * next <code>invoke()</code> has returned.
+ * <code>invokeNext()</code> method has returned.
* <li>Perform any actions on the output stream associated with the
- * specified Response after the next <code>invoke()</code> has
+ * specified Response after the <code>invokeNext()</code> method has
* returned.
* </ul>
- * <p>
*
* @param request The servlet request to be processed
* @param response The servlet response to be created
+ * @param context The valve context used to invoke the next valve
+ * in the current processing pipeline
*
- * @exception IOException if an input/output error occurs
- * @exception ServletException if a servlet error occurs
+ * @exception IOException if an input/output error occurs, or is thrown
+ * by a subsequently invoked Valve, Filter, or Servlet
+ * @exception ServletException if a servlet error occurs, or is thrown
+ * by a subsequently invoked Valve, Filter, or Servlet
*/
- public void invoke(Request request, Response response)
+ public void invoke(Request request, Response response,
+ ValveContext context)
throws IOException, ServletException;
1.1 jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Contained.java
Index: Contained.java
===================================================================
/*
* $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Contained.java,v 1.1 2001/01/23 02:49:37 craigmcc Exp $
* $Revision: 1.1 $
* $Date: 2001/01/23 02:49:37 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2001 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.catalina;
/**
* <p>Decoupling interface which specifies that an implementing class is
* associated with at most one <strong>Container</strong> instance.</p>
*
* @author Craig R. McClanahan
* @author Peter Donald
* @version $Revision: 1.1 $ $Date: 2001/01/23 02:49:37 $
*/
public interface Contained {
//-------------------------------------------------------------- Properties
/**
* Return the <code>Container</code> with which this instance is associated
* (if any); otherwise return <code>null</code>.
*/
public Container getContainer();
/**
* Set the <code>Container</code> with which this instance is associated.
*
* @param container The Container instance with which this instance is to
* be associated, or <code>null</code> to disassociate this instance
* from any Container
*/
public void setContainer(Container container);
}
1.1 jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/ValveContext.java
Index: ValveContext.java
===================================================================
/*
* $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/ValveContext.java,v 1.1 2001/01/23 02:49:37 craigmcc Exp $
* $Revision: 1.1 $
* $Date: 2001/01/23 02:49:37 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2001 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.catalina;
import java.io.IOException;
import javax.servlet.ServletException;
/**
* <p>A <b>ValveContext</b> is the mechanism by which a Valve can trigger the
* execution of the next Valve in a Pipeline, without having to know anything
* about the internal implementation mechanisms. An instance of a class
* implementing this interface is passed as a parameter to the
* <code>Valve.invoke()</code> method of each executed Valve.</p>
*
* <p><strong>IMPLEMENTATION NOTE</strong>: It is up to the implementation of
* ValveContext to ensure that simultaneous requests being processed (by
* separate threads) through the same Pipeline do not interfere with each
* other's flow of control.</p>
*
* @author Craig R. McClanahan
* @author Gunnar Rjnning
* @author Peter Donald
* @version $Revision: 1.1 $ $Date: 2001/01/23 02:49:37 $
*/
public interface ValveContext {
//-------------------------------------------------------------- Properties
/**
* Return descriptive information about this ValveContext implementation.
*/
public String getInfo();
//---------------------------------------------------------- Public Methods
/**
* Cause the <code>invoke()</code> method of the next Valve that is part of
* the Pipeline currently being processed (if any) to be executed, passing
* on the specified request and response objects plus this
* <code>ValveContext</code> instance. Exceptions thrown by a subsequently
* executed Valve (or a Filter or Servlet at the application level) will be
* passed on to our caller.
*
* If there are no more Valves to be executed, an appropriate
* ServletException will be thrown by this ValveContext.
*
* @param request The request currently being processed
* @param response The response currently being created
*
* @exception IOException if thrown by a subsequent Valve, Filter, or
* Servlet
* @exception ServletException if thrown by a subsequent Valve, Filter,
* or Servlet
* @exception ServletException if there are no further Valves configured
* in the Pipeline currently being processed
*/
public void invokeNext(Request request, Response response)
throws IOException, ServletException;
}