Valve (Tomcat API Documentation)
Keywords: org.apache.catalina.Valve interface

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.catalina
Interface Valve

All Known Subinterfaces:
  ClusterValve

All Known Implementing Classes:
  AccessLogValve, AuthenticatorBase, BasicAuthenticator, ClusterSingleSignOn, CometConnectionManagerValve, DigestAuthenticator, ErrorReportValve, ExtendedAccessLogValve, FastCommonAccessLogValve, FormAuthenticator, JDBCAccessLogValve, JvmRouteBinderValve, NonLoginAuthenticator, PersistentValve, RemoteAddrValve, RemoteHostValve, ReplicationValve, RequestDumperValve, RequestFilterValve, SemaphoreValve, SingleSignOn, SSLAuthenticator, SSLValve, ValveBase, WebdavFixValve

    public interface Valve

A Valve 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 `invoke()` method below.

HISTORICAL NOTE: 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.

Version:
  $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (Tue, 24 Oct 2006) $
Author:
  Craig R. McClanahan, Gunnar Rjnning, Peter Donald

Method Summary
`void` | `backgroundProcess()` Execute a periodic task, such as reloading, etc.
`void` | `event(Request request, Response response, CometEvent event)` Process a Comet event.
`java.lang.String` | `getInfo()` Return descriptive information about this Valve implementation.
`Valve` | `getNext()` Return the next Valve in the pipeline containing this Valve, if any.
`void` | `invoke(Request request, Response response)` Perform request processing as required by this Valve.
`void` | `setNext(Valve valve)` Set the next Valve in the pipeline containing this Valve.

Method Detail

### getInfo

    java.lang.String getInfo()

  Return descriptive information about this Valve implementation.

### getNext

    Valve getNext()

  Return the next Valve in the pipeline containing this Valve, if any.

### setNext

    void setNext(Valve valve)

  Set the next Valve in the pipeline containing this Valve.

  Parameters:
    `valve` - The new next valve, or `null` if none

### backgroundProcess

    void backgroundProcess()

  Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.

### invoke

    void invoke(Request request,
                Response response)
                throws java.io.IOException,
                       javax.servlet.ServletException

  Perform request processing as required by this Valve.

  An individual Valve MAY perform the following actions, in the specified order:

  - Examine and/or modify the properties of the specified Request and Response.
  - Examine the properties of the specified Request, completely generate the corresponding Response, and return control to the caller.
  - Examine the properties of the specified Request and Response, wrap either or both of these objects to supplement their functionality, and pass them on.
  - 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 `context.invokeNext()`.
  - Examine, but not modify, the properties of the resulting Response (which was created by a subsequently invoked Valve or Container).

  A Valve MUST NOT do any of the following things:

  - Change request properties that have already been used to direct the flow of processing control for this request (for instance, trying to change the virtual host to which a Request should be sent from a pipeline attached to a Host or Context in the standard implementation).
  - Create a completed Response AND pass this Request and Response on to the next Valve in the pipeline.
  - Consume bytes from the input stream associated with the Request, unless it is completely generating the response, or wrapping the request before passing it on.
  - Modify the HTTP headers included with the Response after the `invokeNext()` method has returned.
  - Perform any actions on the output stream associated with the specified Response after the `invokeNext()` method has returned.

  Parameters:
    `request` - The servlet request to be processed
    `response` - The servlet response to be created
  Throws:
    `java.io.IOException` - if an input/output error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
    `javax.servlet.ServletException` - if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet

### event

    void event(Request request,
               Response response,
               CometEvent event)
               throws java.io.IOException,
                      javax.servlet.ServletException

  Process a Comet event.

  Parameters:
    `request` - The servlet request to be processed
    `response` - The servlet response to be created
  Throws:
    `java.io.IOException` - if an input/output error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
    `javax.servlet.ServletException` - if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2008 Apache Software Foundation. All Rights Reserved.