1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.pipeline; 19 20 /** 21 * <p>A Stage represents a set of tasks that can be performed on objects 22 * in a queue, and methods used to communicate with other stages 23 * in a {@link Pipeline}.</p> 24 */ 25 public interface Stage { 26 27 /** 28 * <p>Initialization takes place when the stage is added to a pipeline. 29 * Implementations of this method should perform any necessary setup that 30 * is required for the driver to be able to correctly run the stage.</p> 31 * <p><strong>NOTE:</strong> Since this method is run when the stage is 32 * added to the pipeline, certain information (such as the downstream 33 * feeder for the stage) may not yet be available until the pipeline is 34 * fully constructoed.</p> 35 * @param context the {@link StageContext} within which the stage sill be run 36 */ 37 public void init(StageContext context); 38 39 /** 40 * Implementations of this method should perform any necessary setup that 41 * needs to be done before any data is processed. 42 * Preprocessing is performed after initialization. 43 * 44 * @throws StageException any checked Exception thrown by the implementation should 45 * be wrapped in a {@link StageException} 46 */ 47 public void preprocess() throws StageException; 48 49 /** 50 * Implementations of this method should atomically process a single data 51 * object and transfer any feed objects resulting from this processing to 52 * the downstream {@link Feeder}. This {@link Feeder} can be obtained from 53 * the stage context made available during {@link #init initialization}. 54 * 55 * NOTE: Implementations of this method must be thread-safe! 56 * 57 * @param obj an object to be processed 58 * @throws StageException any checked Exception thrown by the implementation should 59 * be wrapped in a {@link StageException} 60 */ 61 public void process(Object obj) throws StageException; 62 63 /** 64 * Implementations of this method should do any additional processing or 65 * finalization necessary after all data objects have been processed 66 * by the stage. 67 * @throws StageException any checked Exception thrown by the implementation should 68 * be wrapped in a {@link StageException} 69 */ 70 public void postprocess() throws StageException; 71 72 /** 73 * Implementations of this method should clean up any lingering resources 74 * that might otherwise be left allocated if an exception is thrown during 75 * processing (or pre/postprocessing). 76 */ 77 public void release(); 78 }