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 }