KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > catalina > Valve


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */

17
18
19 package org.apache.catalina;
20
21
22 import java.io.IOException JavaDoc;
23 import javax.servlet.ServletException JavaDoc;
24
25 import org.apache.catalina.connector.Request;
26 import org.apache.catalina.connector.Response;
27
28
29 /**
30  * <p>A <b>Valve</b> is a request processing component associated with a
31  * particular Container. A series of Valves are generally associated with
32  * each other into a Pipeline. The detailed contract for a Valve is included
33  * in the description of the <code>invoke()</code> method below.</p>
34  *
35  * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept
36  * because a valve is what you use in a real world pipeline to control and/or
37  * modify flows through it.
38  *
39  * @author Craig R. McClanahan
40  * @author Gunnar Rjnning
41  * @author Peter Donald
42  * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
43  */

44
45 public interface Valve {
46
47
48     //-------------------------------------------------------------- Properties
49

50
51     /**
52      * Return descriptive information about this Valve implementation.
53      */

54     public String JavaDoc getInfo();
55
56
57     /**
58      * Return the next Valve in the pipeline containing this Valve, if any.
59      */

60     public Valve getNext();
61
62
63     /**
64      * Set the next Valve in the pipeline containing this Valve.
65      *
66      * @param valve The new next valve, or <code>null</code> if none
67      */

68     public void setNext(Valve valve);
69
70
71     //---------------------------------------------------------- Public Methods
72

73
74     /**
75      * Execute a periodic task, such as reloading, etc. This method will be
76      * invoked inside the classloading context of this container. Unexpected
77      * throwables will be caught and logged.
78      */

79     public void backgroundProcess();
80
81
82     /**
83      * <p>Perform request processing as required by this Valve.</p>
84      *
85      * <p>An individual Valve <b>MAY</b> perform the following actions, in
86      * the specified order:</p>
87      * <ul>
88      * <li>Examine and/or modify the properties of the specified Request and
89      * Response.
90      * <li>Examine the properties of the specified Request, completely generate
91      * the corresponding Response, and return control to the caller.
92      * <li>Examine the properties of the specified Request and Response, wrap
93      * either or both of these objects to supplement their functionality,
94      * and pass them on.
95      * <li>If the corresponding Response was not generated (and control was not
96      * returned, call the next Valve in the pipeline (if there is one) by
97      * executing <code>context.invokeNext()</code>.
98      * <li>Examine, but not modify, the properties of the resulting Response
99      * (which was created by a subsequently invoked Valve or Container).
100      * </ul>
101      *
102      * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
103      * <ul>
104      * <li>Change request properties that have already been used to direct
105      * the flow of processing control for this request (for instance,
106      * trying to change the virtual host to which a Request should be
107      * sent from a pipeline attached to a Host or Context in the
108      * standard implementation).
109      * <li>Create a completed Response <strong>AND</strong> pass this
110      * Request and Response on to the next Valve in the pipeline.
111      * <li>Consume bytes from the input stream associated with the Request,
112      * unless it is completely generating the response, or wrapping the
113      * request before passing it on.
114      * <li>Modify the HTTP headers included with the Response after the
115      * <code>invokeNext()</code> method has returned.
116      * <li>Perform any actions on the output stream associated with the
117      * specified Response after the <code>invokeNext()</code> method has
118      * returned.
119      * </ul>
120      *
121      * @param request The servlet request to be processed
122      * @param response The servlet response to be created
123      *
124      * @exception IOException if an input/output error occurs, or is thrown
125      * by a subsequently invoked Valve, Filter, or Servlet
126      * @exception ServletException if a servlet error occurs, or is thrown
127      * by a subsequently invoked Valve, Filter, or Servlet
128      */

129     public void invoke(Request request, Response response)
130         throws IOException JavaDoc, ServletException JavaDoc;
131
132     
133     /**
134      * Process a Comet event.
135      *
136      * @param request The servlet request to be processed
137      * @param response The servlet response to be created
138      *
139      * @exception IOException if an input/output error occurs, or is thrown
140      * by a subsequently invoked Valve, Filter, or Servlet
141      * @exception ServletException if a servlet error occurs, or is thrown
142      * by a subsequently invoked Valve, Filter, or Servlet
143      */

144     public void event(Request request, Response response, CometEvent event)
145         throws IOException JavaDoc, ServletException JavaDoc;
146
147
148 }
149
Popular Tags