View Javadoc

    1   package org.apache.turbine.pipeline;
    2
    3
    4   /*
    5    * Licensed to the Apache Software Foundation (ASF) under one
    6    * or more contributor license agreements.  See the NOTICE file
    7    * distributed with this work for additional information
    8    * regarding copyright ownership.  The ASF licenses this file
    9    * to you under the Apache License, Version 2.0 (the
    10   * "License"); you may not use this file except in compliance
    11   * with the License.  You may obtain a copy of the License at
    12   *
    13   *   http://www.apache.org/licenses/LICENSE-2.0
    14   *
    15   * Unless required by applicable law or agreed to in writing,
    16   * software distributed under the License is distributed on an
    17   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    18   * KIND, either express or implied.  See the License for the
    19   * specific language governing permissions and limitations
    20   * under the License.
    21   */
    22
    23
    24  import java.io.IOException;
    25
    26  import org.apache.turbine.util.TurbineException;
    27
    28  /**
    29   * <p>A <b>Valve</b> is a request processing component.  A series of
    30   * Valves are generally associated with each other into a Pipeline.
    31   * The detailed contract for a Valve is included in the description of
    32   * the <code>invoke()</code> method below.</p>
    33   *
    34   * <b>HISTORICAL NOTE</b>:  The "Valve" name was assigned to this concept
    35   * because a valve is what you use in a real world pipeline to control and/or
    36   * modify flows through it.
    37   *
    38   * @author Craig R. McClanahan
    39   * @author Gunnar Rjnning
    40   * @author Peter Donald
    41   * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    42   *
    43   * @see #invoke(PipelineData, ValveContext)
    44   */
    45  public interface Valve
    46  {
    47      /**
    48       * <p>Perform request processing as required by this Valve.</p>
    49       *
    50       * <p>An individual Valve <b>MAY</b> perform the following actions, in
    51       * the specified order:</p>
    52       * <ul>
    53       * <li>Examine and/or modify the properties of the specified Request and
    54       *     Response.
    55       * <li>Examine the properties of the specified Request, completely generate
    56       *     the corresponding Response, and return control to the caller.
    57       * <li>Examine the properties of the specified Request and Response, wrap
    58       *     either or both of these objects to supplement their functionality,
    59       *     and pass them on.
    60       * <li>If the corresponding Response was not generated (and control was not
    61       *     returned, call the next Valve in the pipeline (if there is one) by
    62       *     executing <code>context.invokeNext()</code>.
    63       * <li>Examine, but not modify, the properties of the resulting Response
    64       *     (which was created by a subsequently invoked Valve via a
    65       *     call to <code>context.invokeNext()</code>).
    66       * </ul>
    67       *
    68       * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
    69       * <ul>
    70       * <li>Change request properties that have already been used to direct
    71       *     the flow of processing control for this request.
    72       * <li>Create a completed Response <strong>AND</strong> pass this
    73       *     Request and Response on to the next Valve in the pipeline.
    74       * <li>Consume bytes from the input stream associated with the Request,
    75       *     unless it is completely generating the response, or wrapping the
    76       *     request before passing it on.
    77       * <li>Modify the HTTP headers included with the Response after the
    78       *     <code>invokeNext()</code> method has returned.
    79       * <li>Perform any actions on the output stream associated with the
    80       *     specified Response after the <code>invokeNext()</code> method has
    81       *     returned.
    82       * </ul>
    83       *
    84       * @param pipelineData The run-time information, including the servlet
    85       * request and response we are processing.
    86       * @param context The valve context used to invoke the next valve
    87       *  in the current processing pipeline
    88       *
    89       * @throws IOException Thrown by a subsequent Valve.
    90       * @throws TurbineException Thrown by a subsequent Valve.
    91       */
    92      public void invoke(PipelineData pipelineData, ValveContext context)
    93          throws IOException, TurbineException;
    94
    95      /**
    96       * Initialize the valve before using in a pipeline.
    97       * @throws Exception if initialization fails
    98       */
    99      public void initialize()
    100         throws Exception;
    101 }