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 import java.util.List;
21
22 /**
23 * This interface is used to define how processing for a stage is started,
24 * stopped, and run. StageDriver implementations may run stages in one or
25 * more threads, and use the {@link StageContext} interface to provide
26 * communication between the stage and the context it is run, usually
27 * a pipeline.
28 *
29 *
30 */
31 public interface StageDriver {
32 /**
33 * This enumeration represents possible states of the a stage driver during
34 * processing.
35 */
36 public enum State {
37 /** Resources have been released and all stage activity has stopped, or
38 * the stage has never been started. This is the default state. */
39 STOPPED,
40 /** The stage driver has started and the preprocess() method is being run. */
41 STARTED,
42 /** Preprocessing is complete and objects are being processed.*/
43 RUNNING,
44 /** A stop has been requested - the stage will finish processing,
45 * then postprocess and shut down. */
46 STOP_REQUESTED,
47 /** Postprocessing tasks are complete; the stage is shutting down. */
48 FINISHED,
49 /** A fatal error has occurred that has caused the driver to stop in an
50 * inconsistent state. The driver cannot be restarted from the error state.
51 * The error(s) can be obtained using the getFatalErrors method. */
52 ERROR
53 }
54
55 /**
56 * This method is used to start the driver, run the
57 * {@link Stage#preprocess() preprocess()} method of the attached stage
58 * and to then begin processing any objects fed to this driver's Feeder.
59 *
60 * @throws org.apache.commons.pipeline.StageException Thrown if there is an error during stage startup. In most cases, such errors
61 * will be handled internally by the driver.
62 */
63 public void start() throws StageException;
64
65 /**
66 * This method waits for the stage(s) queue(s) to empty and any processor thread(s) to exit
67 * cleanly and then calls release() to release any resources acquired during processing, if possible.
68 *
69 * @throws org.apache.commons.pipeline.StageException Thrown if there is an error during driver shutdown. Ordinarily such
70 * exceptions will be handled internally.
71 */
72 public void finish() throws StageException;
73
74 /**
75 * This method is used to provide a communication channel between the context
76 * in which the driver is being run and the managed stage.
77 *
78 * @return the Feeder used to feed objects to the managed stage for processing.
79 */
80 public Feeder getFeeder();
81
82 /**
83 * Returns the Stage being run by this StageDriver.
84 *
85 * @return The stage being run by this StageDriver instance
86 */
87 public Stage getStage();
88
89 /**
90 * Returns the current state of stage processing.
91 *
92 * @return The current state
93 */
94 public State getState();
95
96 /**
97 * Returns a list of unrecoverable errors that occurred during stage
98 * processing.
99 *
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 }