001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Valve.java,v 1.4 2001/07/22 20:13:30 pier Exp $
003: * $Revision: 1.4 $
004: * $Date: 2001/07/22 20:13:30 $
005: *
006: * ====================================================================
007: *
008: * The Apache Software License, Version 1.1
009: *
010: * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
011: * reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions
015: * are met:
016: *
017: * 1. Redistributions of source code must retain the above copyright
018: * notice, this list of conditions and the following disclaimer.
019: *
020: * 2. Redistributions in binary form must reproduce the above copyright
021: * notice, this list of conditions and the following disclaimer in
022: * the documentation and/or other materials provided with the
023: * distribution.
024: *
025: * 3. The end-user documentation included with the redistribution, if
026: * any, must include the following acknowlegement:
027: * "This product includes software developed by the
028: * Apache Software Foundation (http://www.apache.org/)."
029: * Alternately, this acknowlegement may appear in the software itself,
030: * if and wherever such third-party acknowlegements normally appear.
031: *
032: * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
033: * Foundation" must not be used to endorse or promote products derived
034: * from this software without prior written permission. For written
035: * permission, please contact apache@apache.org.
036: *
037: * 5. Products derived from this software may not be called "Apache"
038: * nor may "Apache" appear in their names without prior written
039: * permission of the Apache Group.
040: *
041: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
042: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
043: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
044: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
045: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
046: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
047: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
048: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
049: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
050: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
051: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
052: * SUCH DAMAGE.
053: * ====================================================================
054: *
055: * This software consists of voluntary contributions made by many
056: * individuals on behalf of the Apache Software Foundation. For more
057: * information on the Apache Software Foundation, please see
058: * <http://www.apache.org/>.
059: *
060: * [Additional notices, if required by prior licensing conditions]
061: *
062: */
063:
064: package org.apache.catalina;
065:
066: import java.io.IOException;
067: import javax.servlet.ServletException;
068:
069: /**
070: * <p>A <b>Valve</b> is a request processing component associated with a
071: * particular Container. A series of Valves are generally associated with
072: * each other into a Pipeline. The detailed contract for a Valve is included
073: * in the description of the <code>invoke()</code> method below.</p>
074: *
075: * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept
076: * because a valve is what you use in a real world pipeline to control and/or
077: * modify flows through it.
078: *
079: * @author Craig R. McClanahan
080: * @author Gunnar Rjnning
081: * @author Peter Donald
082: * @version $Revision: 1.4 $ $Date: 2001/07/22 20:13:30 $
083: */
084:
085: public interface Valve {
086:
087: //-------------------------------------------------------------- Properties
088:
089: /**
090: * Return descriptive information about this Valve implementation.
091: */
092: public String getInfo();
093:
094: //---------------------------------------------------------- Public Methods
095:
096: /**
097: * <p>Perform request processing as required by this Valve.</p>
098: *
099: * <p>An individual Valve <b>MAY</b> perform the following actions, in
100: * the specified order:</p>
101: * <ul>
102: * <li>Examine and/or modify the properties of the specified Request and
103: * Response.
104: * <li>Examine the properties of the specified Request, completely generate
105: * the corresponding Response, and return control to the caller.
106: * <li>Examine the properties of the specified Request and Response, wrap
107: * either or both of these objects to supplement their functionality,
108: * and pass them on.
109: * <li>If the corresponding Response was not generated (and control was not
110: * returned, call the next Valve in the pipeline (if there is one) by
111: * executing <code>context.invokeNext()</code>.
112: * <li>Examine, but not modify, the properties of the resulting Response
113: * (which was created by a subsequently invoked Valve or Container).
114: * </ul>
115: *
116: * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
117: * <ul>
118: * <li>Change request properties that have already been used to direct
119: * the flow of processing control for this request (for instance,
120: * trying to change the virtual host to which a Request should be
121: * sent from a pipeline attached to a Host or Context in the
122: * standard implementation).
123: * <li>Create a completed Response <strong>AND</strong> pass this
124: * Request and Response on to the next Valve in the pipeline.
125: * <li>Consume bytes from the input stream associated with the Request,
126: * unless it is completely generating the response, or wrapping the
127: * request before passing it on.
128: * <li>Modify the HTTP headers included with the Response after the
129: * <code>invokeNext()</code> method has returned.
130: * <li>Perform any actions on the output stream associated with the
131: * specified Response after the <code>invokeNext()</code> method has
132: * returned.
133: * </ul>
134: *
135: * @param request The servlet request to be processed
136: * @param response The servlet response to be created
137: * @param context The valve context used to invoke the next valve
138: * in the current processing pipeline
139: *
140: * @exception IOException if an input/output error occurs, or is thrown
141: * by a subsequently invoked Valve, Filter, or Servlet
142: * @exception ServletException if a servlet error occurs, or is thrown
143: * by a subsequently invoked Valve, Filter, or Servlet
144: */
145: public void invoke(Request request, Response response,
146: ValveContext context) throws IOException, ServletException;
147:
148: }
|