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    }