org.apache.commons.pipeline
Class Pipeline

java.lang.Object
  extended by org.apache.commons.pipeline.Pipeline
All Implemented Interfaces:
Runnable, StageContext

public class Pipeline
extends Object
implements Runnable, StageContext

This class represents a processing system consisting of a number of stages and branches. Each stage contains a queue and manages one or more threads that process data in that stage's queue and allow processed data to be passed along to subsequent stages and onto branches of the pipeline.

This class allows all stages in the pipeline to be managed collectively with methods to start and stop processing for all stages, as well as a simple framework for asynchronous event-based communication between stages.


Field Summary
static String MAIN_BRANCH
          The branch key for the main line of production.
 
Constructor Summary
Pipeline()
          Creates and initializes a new Pipeline.
 
Method Summary
 void addBranch(String key, Pipeline branch)
          Adds a branch to the pipeline.
 void addLifecycleJob(PipelineLifecycleJob job)
          Adds a job to be onStart on startup to the pipeline.
 void addStage(Stage stage, StageDriverFactory driverFactory)
          Adds a Stage object to the end of this Pipeline.
 void finish()
          This method iterates over the stages in the pipeline, looking up a StageDriver for each stage and using that driver to request that the stage finish execution.
 Map<String,Pipeline> getBranches()
          Returns an unmodifiable map of branch pipelines, keyed by branch identifier.
 Feeder getBranchFeeder(String branch)
          Return the source feeder for the specified pipeline branch.
 Feeder getDownstreamFeeder(Stage stage)
          This method is used by a stage driver to pass data from one stage to the next.
 Object getEnv(String key)
          A StageContext implementation provides a global environment for the stages being run.
 Pipeline getParent()
          Returns the parent of this pipeline, if it is a branch
 Collection<StageEventListener> getRegisteredListeners()
          Returns the collection of StageEventListeners registered with the context.
 Feeder getSourceFeeder()
          Returns a feeder for the first stage if the pipeline is not empty
 StageDriver getStageDriver(Stage stage)
          Return the StageDriver for the specified Stage.
 List<StageDriver> getStageDrivers()
          Returns an unmodifiable list of stage drivers that have been added to the pipeline.
 List<Stage> getStages()
          Returns an unmodifiable list of stages that have been added to this pipeline.
 Feeder getTerminalFeeder()
          Gets the feeder that receives output from the final stage.
 PipelineValidator getValidator()
          Returns the validator being used to validate the pipeline structure, or null if no validation is being performed..
 void raise(EventObject ev)
          Asynchronously notifies each registered listener of an event and propagates the event to any attached branches and the parent pipeline.
 void registerListener(StageEventListener listener)
          Adds a StageEventListener to the context that will be notified by calls to StageContext.raise(EventObject).
 void run()
          Runs the pipeline from start to finish.
 void setEnv(String key, Object value)
          Sets the value corresponding to the specified environment variable key.
 void setTerminalFeeder(Feeder terminalFeeder)
          Sets the terminal feeder used to handle any output from the final stage.
 void setValidator(PipelineValidator validator)
          Sets the validator used to validate the pipeline as it is contstructed.
 void start()
          This method iterates over the stages in the pipeline, looking up a StageDriver for each stage and using that driver to start the stage.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAIN_BRANCH

public static final String MAIN_BRANCH
The branch key for the main line of production. This value is reserved and may not be used as a key for other branch pipelines.

See Also:
Constant Field Values
Constructor Detail

Pipeline

public Pipeline()
Creates and initializes a new Pipeline.

Method Detail

registerListener

public void registerListener(StageEventListener listener)
Adds a StageEventListener to the context that will be notified by calls to StageContext.raise(EventObject).

Specified by:
registerListener in interface StageContext
Parameters:
listener - The listener to be registered with the context.

getRegisteredListeners

public Collection<StageEventListener> getRegisteredListeners()
Returns the collection of StageEventListeners registered with the context.

Specified by:
getRegisteredListeners in interface StageContext
Returns:
the collection of StageEventListeners registered with the context.

raise

public void raise(EventObject ev)
Asynchronously notifies each registered listener of an event and propagates the event to any attached branches and the parent pipeline.

Specified by:
raise in interface StageContext
Parameters:
ev - The event to be sent to registered listeners

getDownstreamFeeder

public Feeder getDownstreamFeeder(Stage stage)
This method is used by a stage driver to pass data from one stage to the next.

Specified by:
getDownstreamFeeder in interface StageContext
Parameters:
stage - The stage from which "downstream" will be determined. Ordinarily a Stage implementation will call this method with a reference to itself.
Returns:
the feeder for the downstream stage, or Feeder.VOID if no downstream stage exists.

getBranchFeeder

public Feeder getBranchFeeder(String branch)
Return the source feeder for the specified pipeline branch.

Specified by:
getBranchFeeder in interface StageContext
Parameters:
branch - the string identifer of the branch for which a feeder will be retrieved
Returns:
the Feeder for the first stage of the specified branch

getEnv

public Object getEnv(String key)
A StageContext implementation provides a global environment for the stages being run. This method allows objects in the global environment to be accessed by the stages running in this context.

Specified by:
getEnv in interface StageContext
Returns:
the object corresponding to the specified string key, or null if no such key exists.

setEnv

public void setEnv(String key,
                   Object value)
Sets the value corresponding to the specified environment variable key.


addStage

public final void addStage(Stage stage,
                           StageDriverFactory driverFactory)
                    throws ValidationException
Adds a Stage object to the end of this Pipeline. If a PipelineValidator has been set using setValidator(org.apache.commons.pipeline.validation.PipelineValidator), it will be used to validate that the appended Stage can consume the output of the previous stage of the pipeline. It does NOT validate the ability or availability of branches to consume data produced by the appended stage.

Parameters:
stage - the stage to be added to the pipeline
driverFactory - the factory that will be used to create a StageDriver that will run the stage
Throws:
ValidationException - if there is a non-null validator set for this pipeline and an error is encountered validating the addition of the stage to the pipeline.

getStages

public final List<Stage> getStages()
Returns an unmodifiable list of stages that have been added to this pipeline.

Returns:
A list of the stages that have been added to the pipeline

getStageDriver

public final StageDriver getStageDriver(Stage stage)
Return the StageDriver for the specified Stage.

Returns:
the StageDriver for the specified Stage.

getStageDrivers

public final List<StageDriver> getStageDrivers()
Returns an unmodifiable list of stage drivers that have been added to the pipeline.

Returns:
the list of drivers for stages in the pipeline

addBranch

public void addBranch(String key,
                      Pipeline branch)
               throws ValidationException
Adds a branch to the pipeline.

Parameters:
key - the string identifier that will be used to refer to the added branch
pipeline - the branch pipeline
Throws:
ValidationException - if the pipeline has a non-null PipelineValidator and the branch cannot consume the data produced for the branch by stages in the pipeline.

getBranches

public Map<String,Pipeline> getBranches()
Returns an unmodifiable map of branch pipelines, keyed by branch identifier.

Returns:
the map of registered branch pipelines, keyed by branch identifier

getSourceFeeder

public Feeder getSourceFeeder()
Returns a feeder for the first stage if the pipeline is not empty

Returns:
the feeder to feed the first stage of the pipeline

getTerminalFeeder

public Feeder getTerminalFeeder()
Gets the feeder that receives output from the final stage.

Returns:
the terminal feeder being used to handle any output from the final stage. The default is Feeder.VOID

setTerminalFeeder

public void setTerminalFeeder(Feeder terminalFeeder)
Sets the terminal feeder used to handle any output from the final stage.

Parameters:
terminalFeeder - the Feeder that will receive any output from the final stage

addLifecycleJob

public void addLifecycleJob(PipelineLifecycleJob job)
Adds a job to be onStart on startup to the pipeline.


start

public void start()
           throws StageException
This method iterates over the stages in the pipeline, looking up a StageDriver for each stage and using that driver to start the stage. Startups may occur sequentially or in parallel, depending upon the stage driver used. If a the stage has not been configured with a StageDriver, we will use the default, non-threaded SynchronousStageDriver.

Throws:
StageException - Thrown if there is an error during pipeline startup

finish

public void finish()
            throws StageException
This method iterates over the stages in the pipeline, looking up a StageDriver for each stage and using that driver to request that the stage finish execution. The StageDriver#finish(Stage) method will block until the stage's queue is exhausted, so this method may be used to safely finalize all stages without the risk of losing data in the queues.

Throws:
StageException - Thrown if there is an unhandled error during stage shutdown

run

public void run()
Runs the pipeline from start to finish.

Specified by:
run in interface Runnable

getValidator

public PipelineValidator getValidator()
Returns the validator being used to validate the pipeline structure, or null if no validation is being performed..

Returns:
Validator used to validate pipeline structure.

setValidator

public void setValidator(PipelineValidator validator)
Sets the validator used to validate the pipeline as it is contstructed. Setting the validator to null disables validation

Parameters:
validator - Validator used to validate pipeline structure.

getParent

public Pipeline getParent()
Returns the parent of this pipeline, if it is a branch

Returns:
parent Pipeline, or null if this is the main pipeline


Copyright © 2004-2009 The Apache Software Foundation. All Rights Reserved.