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    /**
021     * <p>A Stage represents a set of tasks that can be performed on objects
022     * in a queue, and methods used to communicate with other stages
023     * in a {@link Pipeline}.</p>
024         */
025    public interface Stage {
026        
027        /**
028         * <p>Initialization takes place when the stage is added to a pipeline.
029         * Implementations of this method should perform any necessary setup that
030         * is required for the driver to be able to correctly run the stage.</p>
031         * <p><strong>NOTE:</strong> Since this method is run when the stage is 
032         * added to the pipeline, certain information (such as the downstream
033         * feeder for the stage) may not yet be available until the pipeline is
034         * fully constructoed.</p>
035         * @param context the {@link StageContext} within which the stage sill be run
036         */
037        public void init(StageContext context);
038        
039        /**
040         * Implementations of this method should perform any necessary setup that
041         * needs to be done before any data is processed.
042         * Preprocessing is performed after initialization.
043         *
044         * @throws StageException any checked Exception thrown by the implementation should
045         * be wrapped in a {@link StageException}
046         */
047        public void preprocess() throws StageException;
048        
049        /**
050         * Implementations of this method should atomically process a single data
051         * object and transfer any feed objects resulting from this processing to
052         * the downstream {@link Feeder}. This {@link Feeder} can be obtained from 
053         * the stage context made available during {@link #init initialization}.
054         *
055         * NOTE: Implementations of this method must be thread-safe!
056         *
057         * @param obj an object to be processed
058         * @throws StageException any checked Exception thrown by the implementation should
059         * be wrapped in a {@link StageException}
060         */
061        public void process(Object obj) throws StageException;
062        
063        /**
064         * Implementations of this method should do any additional processing or
065         * finalization necessary after all data objects have been processed
066         * by the stage.
067         * @throws StageException any checked Exception thrown by the implementation should
068         * be wrapped in a {@link StageException}
069         */
070        public void postprocess() throws StageException;
071        
072        /**
073         * Implementations of this method should clean up any lingering resources
074         * that might otherwise be left allocated if an exception is thrown during
075         * processing (or pre/postprocessing).
076         */
077        public void release();
078    }