001: /*
002: * Copyright 1999-2001,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.io.IOException;
020: import javax.servlet.ServletException;
021:
022: /**
023: * <p>A <b>Valve</b> is a request processing component associated with a
024: * particular Container. A series of Valves are generally associated with
025: * each other into a Pipeline. The detailed contract for a Valve is included
026: * in the description of the <code>invoke()</code> method below.</p>
027: *
028: * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept
029: * because a valve is what you use in a real world pipeline to control and/or
030: * modify flows through it.
031: *
032: * @author Craig R. McClanahan
033: * @author Gunnar Rjnning
034: * @author Peter Donald
035: * @version $Revision: 1.2 $ $Date: 2004/02/27 14:58:39 $
036: */
037:
038: public interface Valve {
039:
040: //-------------------------------------------------------------- Properties
041:
042: /**
043: * Return descriptive information about this Valve implementation.
044: */
045: public String getInfo();
046:
047: //---------------------------------------------------------- Public Methods
048:
049: /**
050: * <p>Perform request processing as required by this Valve.</p>
051: *
052: * <p>An individual Valve <b>MAY</b> perform the following actions, in
053: * the specified order:</p>
054: * <ul>
055: * <li>Examine and/or modify the properties of the specified Request and
056: * Response.
057: * <li>Examine the properties of the specified Request, completely generate
058: * the corresponding Response, and return control to the caller.
059: * <li>Examine the properties of the specified Request and Response, wrap
060: * either or both of these objects to supplement their functionality,
061: * and pass them on.
062: * <li>If the corresponding Response was not generated (and control was not
063: * returned, call the next Valve in the pipeline (if there is one) by
064: * executing <code>context.invokeNext()</code>.
065: * <li>Examine, but not modify, the properties of the resulting Response
066: * (which was created by a subsequently invoked Valve or Container).
067: * </ul>
068: *
069: * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
070: * <ul>
071: * <li>Change request properties that have already been used to direct
072: * the flow of processing control for this request (for instance,
073: * trying to change the virtual host to which a Request should be
074: * sent from a pipeline attached to a Host or Context in the
075: * standard implementation).
076: * <li>Create a completed Response <strong>AND</strong> pass this
077: * Request and Response on to the next Valve in the pipeline.
078: * <li>Consume bytes from the input stream associated with the Request,
079: * unless it is completely generating the response, or wrapping the
080: * request before passing it on.
081: * <li>Modify the HTTP headers included with the Response after the
082: * <code>invokeNext()</code> method has returned.
083: * <li>Perform any actions on the output stream associated with the
084: * specified Response after the <code>invokeNext()</code> method has
085: * returned.
086: * </ul>
087: *
088: * @param request The servlet request to be processed
089: * @param response The servlet response to be created
090: * @param context The valve context used to invoke the next valve
091: * in the current processing pipeline
092: *
093: * @exception IOException if an input/output error occurs, or is thrown
094: * by a subsequently invoked Valve, Filter, or Servlet
095: * @exception ServletException if a servlet error occurs, or is thrown
096: * by a subsequently invoked Valve, Filter, or Servlet
097: */
098: public void invoke(Request request, Response response,
099: ValveContext context) throws IOException, ServletException;
100:
101: }
|