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.Collection; 021 import java.util.EventObject; 022 023 /** 024 * This interface represents the context in which a stage is run. Ordinarily, 025 * the context will be provided by the pipeline in which the stage is embedded; 026 * however, this interface is also useful for creating isolated test environments 027 * in which a stage can be run. 028 * 029 * 030 */ 031 public interface StageContext { 032 /** 033 * Adds a {@link StageEventListener} to the context that will be notified by calls 034 * to {@link #raise(EventObject)}. 035 * @param listener The listener to be registered with the context. 036 */ 037 public void registerListener(StageEventListener listener); 038 039 /** 040 * Returns the collection of {@link StageEventListener}s registered with the 041 * context. 042 * @return the collection of {@link StageEventListener}s registered with the 043 * context. 044 */ 045 public Collection<StageEventListener> getRegisteredListeners(); 046 047 /** 048 * Notifies each registered listener of an event and propagates 049 * the event to any attached branches 050 * @param ev The event to be passed to registered listeners 051 */ 052 public void raise(EventObject ev); 053 054 /** 055 * Return the source feeder for the specified pipeline branch. 056 * @param branch the string identifer of the branch for which a feeder will be retrieved 057 * @return the {@link Feeder} for the first stage of the specified branch 058 */ 059 public Feeder getBranchFeeder(String branch); 060 061 /** 062 * This method is used by a stage driver to pass data from one stage to the next. 063 * @return the feeder for the downstream stage, or {@link Feeder#VOID} if no downstream 064 * stage exists. 065 * @param stage The stage from which "downstream" will be determined. Ordinarily a Stage implementation 066 * will call this method with a reference to itself. 067 * @return The {@link Feeder} for the subsequent stage. 068 */ 069 public Feeder getDownstreamFeeder(Stage stage); 070 071 /** 072 * A StageContext implementation provides a global environment for the 073 * stages being run. This method allows objects in the global environment 074 * to be accessed by the stages running in this context. 075 * 076 * @return the object corresponding to the specified string key, or null 077 * if no such key exists. 078 */ 079 public Object getEnv(String key); 080 }