001: /*
002: * Copyright 1999-2001,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.io.IOException;
020: import javax.servlet.ServletException;
021:
022: /**
023: * <p>Interface describing a collection of Valves that should be executed
024: * in sequence when the <code>invoke()</code> method is invoked. It is
025: * required that a Valve somewhere in the pipeline (usually the last one)
026: * must process the request and create the corresponding response, rather
027: * than trying to pass the request on.</p>
028: *
029: * <p>There is generally a single Pipeline instance associated with each
030: * Container. The container's normal request processing functionality is
031: * generally encapsulated in a container-specific Valve, which should always
032: * be executed at the end of a pipeline. To facilitate this, the
033: * <code>setBasic()</code> method is provided to set the Valve instance that
034: * will always be executed last. Other Valves will be executed in the order
035: * that they were added, before the basic Valve is executed.</p>
036: *
037: * @author Craig R. McClanahan
038: * @author Peter Donald
039: * @version $Revision: 1.2 $ $Date: 2004/02/27 14:58:38 $
040: */
041:
042: public interface Pipeline {
043:
044: // ------------------------------------------------------------- Properties
045:
046: /**
047: * <p>Return the Valve instance that has been distinguished as the basic
048: * Valve for this Pipeline (if any).
049: */
050: public Valve getBasic();
051:
052: /**
053: * <p>Set the Valve instance that has been distinguished as the basic
054: * Valve for this Pipeline (if any). Prioer to setting the basic Valve,
055: * the Valve's <code>setContainer()</code> will be called, if it
056: * implements <code>Contained</code>, with the owning Container as an
057: * argument. The method may throw an <code>IllegalArgumentException</code>
058: * if this Valve chooses not to be associated with this Container, or
059: * <code>IllegalStateException</code> if it is already associated with
060: * a different Container.</p>
061: *
062: * @param valve Valve to be distinguished as the basic Valve
063: */
064: public void setBasic(Valve valve);
065:
066: // --------------------------------------------------------- Public Methods
067:
068: /**
069: * <p>Add a new Valve to the end of the pipeline associated with this
070: * Container. Prior to adding the Valve, the Valve's
071: * <code>setContainer()</code> method will be called, if it implements
072: * <code>Contained</code>, with the owning Container as an argument.
073: * The method may throw an
074: * <code>IllegalArgumentException</code> if this Valve chooses not to
075: * be associated with this Container, or <code>IllegalStateException</code>
076: * if it is already associated with a different Container.</p>
077: *
078: * @param valve Valve to be added
079: *
080: * @exception IllegalArgumentException if this Container refused to
081: * accept the specified Valve
082: * @exception IllegalArgumentException if the specifie Valve refuses to be
083: * associated with this Container
084: * @exception IllegalStateException if the specified Valve is already
085: * associated with a different Container
086: */
087: public void addValve(Valve valve);
088:
089: /**
090: * Return the set of Valves in the pipeline associated with this
091: * Container, including the basic Valve (if any). If there are no
092: * such Valves, a zero-length array is returned.
093: */
094: public Valve[] getValves();
095:
096: /**
097: * Cause the specified request and response to be processed by the Valves
098: * associated with this pipeline, until one of these valves causes the
099: * response to be created and returned. The implementation must ensure
100: * that multiple simultaneous requests (on different threads) can be
101: * processed through the same Pipeline without interfering with each
102: * other's control flow.
103: *
104: * @param request The servlet request we are processing
105: * @param response The servlet response we are creating
106: *
107: * @exception IOException if an input/output error occurs
108: * @exception ServletException if a servlet exception is thrown
109: */
110: public void invoke(Request request, Response response)
111: throws IOException, ServletException;
112:
113: /**
114: * Remove the specified Valve from the pipeline associated with this
115: * Container, if it is found; otherwise, do nothing. If the Valve is
116: * found and removed, the Valve's <code>setContainer(null)</code> method
117: * will be called if it implements <code>Contained</code>.
118: *
119: * @param valve Valve to be removed
120: */
121: public void removeValve(Valve valve);
122:
123: }
|