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.Collection;
21 import java.util.EventObject;
22
23 /**
24 * This interface represents the context in which a stage is run. Ordinarily,
25 * the context will be provided by the pipeline in which the stage is embedded;
26 * however, this interface is also useful for creating isolated test environments
27 * in which a stage can be run.
28 *
29 *
30 */
31 public interface StageContext {
32 /**
33 * Adds a {@link StageEventListener} to the context that will be notified by calls
34 * to {@link #raise(EventObject)}.
35 * @param listener The listener to be registered with the context.
36 */
37 public void registerListener(StageEventListener listener);
38
39 /**
40 * Returns the collection of {@link StageEventListener}s registered with the
41 * context.
42 * @return the collection of {@link StageEventListener}s registered with the
43 * context.
44 */
45 public Collection<StageEventListener> getRegisteredListeners();
46
47 /**
48 * Notifies each registered listener of an event and propagates
49 * the event to any attached branches
50 * @param ev The event to be passed to registered listeners
51 */
52 public void raise(EventObject ev);
53
54 /**
55 * Return the source feeder for the specified pipeline branch.
56 * @param branch the string identifer of the branch for which a feeder will be retrieved
57 * @return the {@link Feeder} for the first stage of the specified branch
58 */
59 public Feeder getBranchFeeder(String branch);
60
61 /**
62 * This method is used by a stage driver to pass data from one stage to the next.
63 * @return the feeder for the downstream stage, or {@link Feeder#VOID} if no downstream
64 * stage exists.
65 * @param stage The stage from which "downstream" will be determined. Ordinarily a Stage implementation
66 * will call this method with a reference to itself.
67 * @return The {@link Feeder} for the subsequent stage.
68 */
69 public Feeder getDownstreamFeeder(Stage stage);
70
71 /**
72 * A StageContext implementation provides a global environment for the
73 * stages being run. This method allows objects in the global environment
74 * to be accessed by the stages running in this context.
75 *
76 * @return the object corresponding to the specified string key, or null
77 * if no such key exists.
78 */
79 public Object getEnv(String key);
80 }