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.stage;
19
20 import org.apache.commons.logging.Log;
21 import org.apache.commons.logging.LogFactory;
22 import org.apache.commons.pipeline.Feeder;
23 import org.apache.commons.pipeline.Stage;
24 import org.apache.commons.pipeline.StageContext;
25 import org.apache.commons.pipeline.StageException;
26 import org.apache.commons.pipeline.validation.ConsumedTypes;
27 import org.apache.commons.pipeline.validation.ProducesConsumed;
28
29 /**
30 * This is a simple base class for Stages with no-op implementations of the
31 * {@link #preprocess()}, {@link #process()}, {@link #postprocess()},
32 * and {@link #release()} methods.
33 */
34 @ConsumedTypes(Object.class)
35 @ProducesConsumed()
36 public abstract class BaseStage implements Stage {
37 private Log log = LogFactory.getLog(BaseStage.class);
38
39 /**
40 * The context in which the stage runs.
41 */
42 protected StageContext context;
43
44 /**
45 * Feeder for the next downstream stage in the pipeline. This value
46 * is lazily initialized by the process() method.
47 */
48 private Feeder downstreamFeeder;
49
50 /**
51 * This implementation of init() simply stores a reference to the
52 * stage context.
53 */
54 public void init(StageContext context) {
55 this.context = context;
56 }
57
58 /**
59 * No-op implementation. This method should be overridden to provide
60 * preprocessing capability for the stage.
61 *
62 * @throws StageException an Exception thrown by an overriding implementation should
63 * be wrapped in a {@link StageException}
64 * @see Stage#preprocess()
65 */
66 public void preprocess() throws StageException {
67 }
68
69 /**
70 * The only operation performed by this implementation of process()
71 * is to feed the specified object to the downstream feeder.
72 * This method should be overridden to provide processing capability for the stage.
73 *
74 * @param obj Object to be passed to downstream pipeline.
75 * @throws StageException an Exception thrown by an overriding implementation should
76 * be wrapped in a {@link StageException}
77 */
78 public void process(Object obj) throws StageException {
79 this.emit(obj);
80 }
81
82 /**
83 * No-op implementation. This method should be overridden to provide
84 * postprocessing capability for the stage.
85 *
86 * @throws StageException an Exception thrown by an overriding implementation should
87 * be wrapped in a {@link StageException}
88 */
89 public void postprocess() throws StageException {
90 }
91
92 /**
93 * No-op implementation. This method should be overridden to provide
94 * resource release capability for the stage.
95 *
96 * Implementations overriding this method should clean up any lingering resources
97 * that might otherwise be left allocated if an exception is thrown during
98 * processing.
99 *
100 * @see Stage#release()
101 */
102 public void release() {
103 }
104
105 /**
106 * Convenience method to feed the specified object to the next stage downstream.
107 */
108 public final void emit(Object obj) {
109 if (log.isDebugEnabled()) log.debug(this.getClass() + " is emitting object " + obj);
110 if (this.downstreamFeeder == null) this.downstreamFeeder = context.getDownstreamFeeder(this);
111 this.downstreamFeeder.feed(obj);
112 }
113
114 /**
115 * Convenience method to feed the specified object to the first stage of the specified branch.
116 */
117 public final void emit(String branch, Object obj) {
118 this.context.getBranchFeeder(branch).feed(obj);
119 }
120 }