001    package org.apache.turbine.pipeline;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    import java.io.IOException;
025    
026    import org.apache.turbine.util.TurbineException;
027    
028    /**
029     * The idea of a pipeline is being taken from Catalina
030     * in its entirety :-)
031     *
032     * I would like to take the idea further and implement
033     * Valves instead of hardcoding particular methods
034     * in a pipeline.
035     *
036     * It would be more flexible to specify Valves for
037     * a pipeline in an XML file (we can also rip off the
038     * digester rules from T4) and have invoke() as part
039     * of the interface.
040     *
041     * So a set of Valves would be added to the pipeline
042     * and the pipeline would 'invoke' each valve. In the
043     * case Turbine each Valve would produce some output
044     * to be sent out the pipe. I think with another days
045     * work this can be fully working. The first pipeline
046     * to be fully implemented will the ClassicPipeline
047     * will emulate the Turbine 2.1 way of doing things.
048     *
049     * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
050     * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
051     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
052     */
053    public interface Pipeline
054    {
055        /**
056         * Initializes this instance.  Called once by the Turbine servlet.
057         */
058        public void initialize()
059            throws Exception;
060    
061        /**
062         * <p>Add a new Valve to the end of the pipeline.</p>
063         *
064         * @param valve Valve to be added.
065         *
066         * @exception IllegalStateException If the pipeline has not been
067         * initialized.
068         */
069        public void addValve(Valve valve);
070    
071        /**
072         * Return the set of all Valves in the pipeline.  If there are no
073         * such Valves, a zero-length array is returned.
074         *
075         * @return An array of valves.
076         */
077        public Valve[] getValves();
078    
079        /**
080         * <p>Cause the specified request and response to be processed by
081         * the sequence of Valves associated with this pipeline, until one
082         * of these Valves decides to end the processing.</p>
083         *
084         * <p>The implementation must ensure that multiple simultaneous
085         * requests (on different threads) can be processed through the
086         * same Pipeline without interfering with each other's control
087         * flow.</p>
088         *
089         * @param data The run-time information, including the servlet
090         * request and response we are processing.
091         *
092         * @exception IOException an input/output error occurred.
093         */
094        public void invoke(PipelineData data)
095            throws TurbineException, IOException;
096    
097        /**
098         * Remove the specified Valve from the pipeline, if it is found;
099         * otherwise, do nothing.
100         *
101         * @param valve Valve to be removed.
102         */
103        public void removeValve(Valve valve);
104    }