    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    }