001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.catalina;
019:
020: /**
021: * <p>Interface describing a collection of Valves that should be executed
022: * in sequence when the <code>invoke()</code> method is invoked. It is
023: * required that a Valve somewhere in the pipeline (usually the last one)
024: * must process the request and create the corresponding response, rather
025: * than trying to pass the request on.</p>
026: *
027: * <p>There is generally a single Pipeline instance associated with each
028: * Container. The container's normal request processing functionality is
029: * generally encapsulated in a container-specific Valve, which should always
030: * be executed at the end of a pipeline. To facilitate this, the
031: * <code>setBasic()</code> method is provided to set the Valve instance that
032: * will always be executed last. Other Valves will be executed in the order
033: * that they were added, before the basic Valve is executed.</p>
034: *
035: * @author Craig R. McClanahan
036: * @author Peter Donald
037: * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
038: */
039:
040: public interface Pipeline {
041:
042: // ------------------------------------------------------------- Properties
043:
044: /**
045: * <p>Return the Valve instance that has been distinguished as the basic
046: * Valve for this Pipeline (if any).
047: */
048: public Valve getBasic();
049:
050: /**
051: * <p>Set the Valve instance that has been distinguished as the basic
052: * Valve for this Pipeline (if any). Prioer to setting the basic Valve,
053: * the Valve's <code>setContainer()</code> will be called, if it
054: * implements <code>Contained</code>, with the owning Container as an
055: * argument. The method may throw an <code>IllegalArgumentException</code>
056: * if this Valve chooses not to be associated with this Container, or
057: * <code>IllegalStateException</code> if it is already associated with
058: * a different Container.</p>
059: *
060: * @param valve Valve to be distinguished as the basic Valve
061: */
062: public void setBasic(Valve valve);
063:
064: // --------------------------------------------------------- Public Methods
065:
066: /**
067: * <p>Add a new Valve to the end of the pipeline associated with this
068: * Container. Prior to adding the Valve, the Valve's
069: * <code>setContainer()</code> method will be called, if it implements
070: * <code>Contained</code>, with the owning Container as an argument.
071: * The method may throw an
072: * <code>IllegalArgumentException</code> if this Valve chooses not to
073: * be associated with this Container, or <code>IllegalStateException</code>
074: * if it is already associated with a different Container.</p>
075: *
076: * @param valve Valve to be added
077: *
078: * @exception IllegalArgumentException if this Container refused to
079: * accept the specified Valve
080: * @exception IllegalArgumentException if the specifie Valve refuses to be
081: * associated with this Container
082: * @exception IllegalStateException if the specified Valve is already
083: * associated with a different Container
084: */
085: public void addValve(Valve valve);
086:
087: /**
088: * Return the set of Valves in the pipeline associated with this
089: * Container, including the basic Valve (if any). If there are no
090: * such Valves, a zero-length array is returned.
091: */
092: public Valve[] getValves();
093:
094: /**
095: * Remove the specified Valve from the pipeline associated with this
096: * Container, if it is found; otherwise, do nothing. If the Valve is
097: * found and removed, the Valve's <code>setContainer(null)</code> method
098: * will be called if it implements <code>Contained</code>.
099: *
100: * @param valve Valve to be removed
101: */
102: public void removeValve(Valve valve);
103:
104: /**
105: * <p>Return the Valve instance that has been distinguished as the basic
106: * Valve for this Pipeline (if any).
107: */
108: public Valve getFirst();
109:
110: }
|