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 }