KickJava   Java API By Example, From Geeks To Geeks.

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


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 /**
23  * <p>Interface describing a collection of Valves that should be executed
24  * in sequence when the <code>invoke()</code> method is invoked. It is
25  * required that a Valve somewhere in the pipeline (usually the last one)
26  * must process the request and create the corresponding response, rather
27  * than trying to pass the request on.</p>
28  *
29  * <p>There is generally a single Pipeline instance associated with each
30  * Container. The container's normal request processing functionality is
31  * generally encapsulated in a container-specific Valve, which should always
32  * be executed at the end of a pipeline. To facilitate this, the
33  * <code>setBasic()</code> method is provided to set the Valve instance that
34  * will always be executed last. Other Valves will be executed in the order
35  * that they were added, before the basic Valve is executed.</p>
36  *
37  * @author Craig R. McClanahan
38  * @author Peter Donald
39  * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
40  */
41
42 public interface Pipeline {
43
44
45     // ------------------------------------------------------------- Properties
46
47
48     /**
49      * <p>Return the Valve instance that has been distinguished as the basic
50      * Valve for this Pipeline (if any).
51      */
52     public Valve getBasic();
53
54
55     /**
56      * <p>Set the Valve instance that has been distinguished as the basic
57      * Valve for this Pipeline (if any). Prioer to setting the basic Valve,
58      * the Valve's <code>setContainer()</code> will be called, if it
59      * implements <code>Contained</code>, with the owning Container as an
60      * argument. The method may throw an <code>IllegalArgumentException</code>
61      * if this Valve chooses not to be associated with this Container, or
62      * <code>IllegalStateException</code> if it is already associated with
63      * a different Container.</p>
64      *
65      * @param valve Valve to be distinguished as the basic Valve
66      */
67     public void setBasic(Valve valve);
68
69
70     // --------------------------------------------------------- Public Methods
71
72
73     /**
74      * <p>Add a new Valve to the end of the pipeline associated with this
75      * Container. Prior to adding the Valve, the Valve's
76      * <code>setContainer()</code> method will be called, if it implements
77      * <code>Contained</code>, with the owning Container as an argument.
78      * The method may throw an
79      * <code>IllegalArgumentException</code> if this Valve chooses not to
80      * be associated with this Container, or <code>IllegalStateException</code>
81      * if it is already associated with a different Container.</p>
82      *
83      * @param valve Valve to be added
84      *
85      * @exception IllegalArgumentException if this Container refused to
86      * accept the specified Valve
87      * @exception IllegalArgumentException if the specifie Valve refuses to be
88      * associated with this Container
89      * @exception IllegalStateException if the specified Valve is already
90      * associated with a different Container
91      */
92     public void addValve(Valve valve);
93
94
95     /**
96      * Return the set of Valves in the pipeline associated with this
97      * Container, including the basic Valve (if any). If there are no
98      * such Valves, a zero-length array is returned.
99      */
100     public Valve[] getValves();
101
102
103     /**
104      * Remove the specified Valve from the pipeline associated with this
105      * Container, if it is found; otherwise, do nothing. If the Valve is
106      * found and removed, the Valve's <code>setContainer(null)</code> method
107      * will be called if it implements <code>Contained</code>.
108      *
109      * @param valve Valve to be removed
110      */
111     public void removeValve(Valve valve);
112
113
114     /**
115      * <p>Return the Valve instance that has been distinguished as the basic
116      * Valve for this Pipeline (if any).
117      */
118     public Valve getFirst();
119
120
121 }
122
Popular Tags