1 package org.apache.turbine; 2 3 /* ==================================================================== 4 * The Apache Software License, Version 1.1 5 * 6 * Copyright (c) 2001 The Apache Software Foundation. All rights 7 * reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions 11 * are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 16 * 2. Redistributions in binary form must reproduce the above copyright 17 * notice, this list of conditions and the following disclaimer in 18 * the documentation and/or other materials provided with the 19 * distribution. 20 * 21 * 3. The end-user documentation included with the redistribution, 22 * if any, must include the following acknowledgment: 23 * "This product includes software developed by the 24 * Apache Software Foundation (http://www.apache.org/)." 25 * Alternately, this acknowledgment may appear in the software itself, 26 * if and wherever such third-party acknowledgments normally appear. 27 * 28 * 4. The names "Apache" and "Apache Software Foundation" and 29 * "Apache Turbine" must not be used to endorse or promote products 30 * derived from this software without prior written permission. For 31 * written permission, please contact apache@apache.org. 32 * 33 * 5. Products derived from this software may not be called "Apache", 34 * "Apache Turbine", nor may "Apache" appear in their name, without 35 * prior written permission of the Apache Software Foundation. 36 * 37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 48 * SUCH DAMAGE. 49 * ==================================================================== 50 * 51 * This software consists of voluntary contributions made by many 52 * individuals on behalf of the Apache Software Foundation. For more 53 * information on the Apache Software Foundation, please see 54 * <http://www.apache.org/>. 55 */ 56 57 import java.io.IOException; 58 59 /** 60 * <p>A <b>Valve</b> is a request processing component. A series of 61 * Valves are generally associated with each other into a Pipeline. 62 * The detailed contract for a Valve is included in the description of 63 * the <code>invoke()</code> method below.</p> 64 * 65 * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept 66 * because a valve is what you use in a real world pipeline to control and/or 67 * modify flows through it. 68 * 69 * @author Craig R. McClanahan 70 * @author Gunnar Rjnning 71 * @author Peter Donald 72 * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a> 73 * 74 * @see #invoke(RunData, ValveContext) 75 */ 76 public interface Valve 77 { 78 /** 79 * <p>Perform request processing as required by this Valve.</p> 80 * 81 * <p>An individual Valve <b>MAY</b> perform the following actions, in 82 * the specified order:</p> 83 * <ul> 84 * <li>Examine and/or modify the properties of the specified Request and 85 * Response. 86 * <li>Examine the properties of the specified Request, completely generate 87 * the corresponding Response, and return control to the caller. 88 * <li>Examine the properties of the specified Request and Response, wrap 89 * either or both of these objects to supplement their functionality, 90 * and pass them on. 91 * <li>If the corresponding Response was not generated (and control was not 92 * returned, call the next Valve in the pipeline (if there is one) by 93 * executing <code>context.invokeNext()</code>. 94 * <li>Examine, but not modify, the properties of the resulting Response 95 * (which was created by a subsequently invoked Valve via a 96 * call to <code>context.invokeNext()</code>). 97 * </ul> 98 * 99 * <p>A Valve <b>MUST NOT</b> do any of the following things:</p> 100 * <ul> 101 * <li>Change request properties that have already been used to direct 102 * the flow of processing control for this request. 103 * <li>Create a completed Response <strong>AND</strong> pass this 104 * Request and Response on to the next Valve in the pipeline. 105 * <li>Consume bytes from the input stream associated with the Request, 106 * unless it is completely generating the response, or wrapping the 107 * request before passing it on. 108 * <li>Modify the HTTP headers included with the Response after the 109 * <code>invokeNext()</code> method has returned. 110 * <li>Perform any actions on the output stream associated with the 111 * specified Response after the <code>invokeNext()</code> method has 112 * returned. 113 * </ul> 114 * 115 * @param data The run-time information, including the servlet 116 * request and response we are processing. 117 * @param context The valve context used to invoke the next valve 118 * in the current processing pipeline 119 * 120 * @exception IOException Thrown by a subsequent Valve. 121 * @exception TurbineException Thrown by a subsequent Valve. 122 */ 123 public void invoke(RunData data, ValveContext context) 124 throws IOException, TurbineException; 125 126 /** 127 * Initialize the valve before using in a pipeline. 128 */ 129 public void initialize() 130 throws Exception; 131 } 132