org.apache.commons.pipeline
Class Pipeline

java.lang.Object
  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