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.commons.pipeline;
019    
020    import java.util.List;
021    
022    /**
023     * This interface is used to define how processing for a stage is started,
024     * stopped, and run. StageDriver implementations may run stages in one or
025     * more threads, and use the {@link StageContext} interface to provide
026     * communication between the stage and the context it is run, usually
027     * a pipeline.
028     *
029     *
030     */
031    public interface StageDriver {
032        /**
033         * This enumeration represents possible states of the a stage driver during
034         * processing.
035         */
036        public enum State {
037            /** Resources have been released and all stage activity has stopped, or
038             * the stage has never been started. This is the default state. */
039            STOPPED,
040            /** The stage driver has started and the preprocess() method is being run. */
041            STARTED,
042            /** Preprocessing is complete and objects are being processed.*/
043            RUNNING,
044            /** A stop has been requested - the stage will finish processing,
045             * then postprocess and shut down. */
046            STOP_REQUESTED,
047            /** Postprocessing tasks are complete; the stage is shutting down. */
048            FINISHED,
049            /** A fatal error has occurred that has caused the driver to stop in an
050             * inconsistent state. The driver cannot be restarted from the error state.
051             * The error(s) can be obtained using the getFatalErrors method. */
052            ERROR
053        }
054        
055        /**
056         * This method is used to start the driver, run the
057         * {@link Stage#preprocess() preprocess()} method of the attached stage
058         * and to then begin processing any objects fed to this driver's Feeder.
059         *
060         * @throws org.apache.commons.pipeline.StageException Thrown if there is an error during stage startup. In most cases, such errors
061         * will be handled internally by the driver.
062         */
063        public void start() throws StageException;
064        
065        /**
066         * This method waits for the stage(s) queue(s) to empty and any processor thread(s) to exit
067         * cleanly and then calls release() to release any resources acquired during processing, if possible.
068         *
069         * @throws org.apache.commons.pipeline.StageException Thrown if there is an error during driver shutdown. Ordinarily such
070         * exceptions will be handled internally.
071         */
072        public void finish() throws StageException;
073        
074        /**
075         * This method is used to provide a communication channel between the context
076         * in which the driver is being run and the managed stage.
077         *
078         * @return the Feeder used to feed objects to the managed stage for processing.
079         */
080        public Feeder getFeeder();
081        
082        /**
083         * Returns the Stage being run by this StageDriver.
084         *
085         * @return The stage being run by this StageDriver instance
086         */
087        public Stage getStage();
088        
089        /**
090         * Returns the current state of stage processing.
091         *
092         * @return The current state
093         */
094        public State getState();
095        
096        /**
097         * Returns a list of unrecoverable errors that occurred during stage
098         * processing.
099         *
100         * @return A list of unrecoverable errors that occurred during stage processing.
101         */
102        public List<Throwable> getFatalErrors();
103        
104        /**
105         * Returns a list of errors that occurred while processing data objects,
106         * along with the objects that were being processed when the errors
107         * were generated.
108         *
109         * @return The list of non-fatal processing errors.
110         */
111        public List<ProcessingException> getProcessingExceptions();
112        
113    }