org.apache.commons.pipeline.driver
Class AbstractStageDriver

java.lang.Object
  org.apache.commons.pipeline.driver.AbstractStageDriver

All Implemented Interfaces:

StageDriver

Direct Known Subclasses:

DedicatedThreadStageDriver, SynchronousStageDriver, ThreadPoolStageDriver

public abstract class AbstractStageDriver
extends Object
implements StageDriver

This interface is used to define how processing for a stage is started, stopped, and run. AbstractStageDriver implementations may run stages in one or more threads, and use the StageMonitor interface to provide communication between the stage, the driver, and the enclosing pipeline.

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.commons.pipeline.StageDriver

StageDriver.State

Field Summary

protected StageContext	context The context for the stage being run
protected StageDriver.State	currentState The current state of processing.
protected List<Throwable>	errors List of errors that have occurred.
protected FaultTolerance	faultTolerance Enumerated value indicating the fault tolerance level of the StageDriver.
protected List<ProcessingException>	processingExceptions List of processing failures that have occurred.
protected Stage	stage The stage to run.

Constructor Summary

AbstractStageDriver(Stage stage, StageContext context)
Creates a StageDriver for the specified stage.

AbstractStageDriver(Stage stage, StageContext context, FaultTolerance faultTolerance)
Creates a StageDriver for the specified stage.

Method Summary

abstract void	finish() This method waits for the stage(s) queue(s) to empty and any processor thread(s) to exit cleanly and then calls release() to release any resources acquired during processing, if possible.
List<Throwable>	getFatalErrors() Returns a list of unrecoverable errors that occurred during stage processing.
FaultTolerance	getFaultTolerance() Getter for property faultTolerant.
abstract Feeder	getFeeder() This method is used to provide a communication channel between the context in which the driver is being run and the managed stage.
List<ProcessingException>	getProcessingExceptions() Returns a list of errors that occurred while processing data objects, along with the objects that were being processed when the errors were generated.
Stage	getStage() Returns the Stage being run by this StageDriver.
StageDriver.State	getState() Return the current state of stage processing.
protected boolean	isInState(StageDriver.State... states) Atomically tests to determine whether or not the driver is in the one of the specified states.
protected void	recordFatalError(Throwable error) Store a fatal error.
protected void	recordProcessingException(Object data, Throwable error) Store processing failure information for the specified data object.
void	setFaultTolerance(FaultTolerance faultTolerance) Sets the failure tolerance flag for the worker thread.
protected void	setState(StageDriver.State nextState) Set the current state of stage processing and notify any listeners that may be waiting on a state change.
abstract void	start() This method is used to start the driver, run the preprocess() method of the attached stage and to then begin processing any objects fed to this driver's Feeder.
protected boolean	testAndSetState(StageDriver.State testState, StageDriver.State nextState) This method performs an atomic conditional state transition change to the value specified by the nextState parameter if and only if the current state is equal to the test state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stage

protected Stage stage

The stage to run.

context

protected StageContext context

The context for the stage being run

currentState

protected volatile StageDriver.State currentState

The current state of processing. In most drivers, this is used for thread control.

faultTolerance

protected FaultTolerance faultTolerance

Enumerated value indicating the fault tolerance level of the StageDriver.

processingExceptions

protected List<ProcessingException> processingExceptions

List of processing failures that have occurred.

errors

protected List<Throwable> errors

List of errors that have occurred.

Constructor Detail

AbstractStageDriver

public AbstractStageDriver(Stage stage,
                           StageContext context)

Creates a StageDriver for the specified stage.

Parameters:

stage - The stage for which the driver will be created

context - The context in which to run the stage

AbstractStageDriver

public AbstractStageDriver(Stage stage,
                           StageContext context,
                           FaultTolerance faultTolerance)

Creates a StageDriver for the specified stage.

Parameters:

stage - The stage for which the driver will be created

context - The context in which to run the stage

Method Detail

getStage

public Stage getStage()

Returns the Stage being run by this StageDriver.

Specified by:

getStage in interface StageDriver

Returns:

The stage being run by this StageDriver instance

getFeeder

public abstract Feeder getFeeder()

This method is used to provide a communication channel between the context in which the driver is being run and the managed stage.

Specified by:

getFeeder in interface StageDriver

Returns:

the Feeder used to feed objects to the managed stage for processing.

getState

public StageDriver.State getState()

Return the current state of stage processing.

Specified by:

getState in interface StageDriver

Returns:

the current state of processing

isInState

protected boolean isInState(StageDriver.State... states)

Atomically tests to determine whether or not the driver is in the one of the specified states.

setState

protected void setState(StageDriver.State nextState)

Set the current state of stage processing and notify any listeners that may be waiting on a state change.

testAndSetState

protected boolean testAndSetState(StageDriver.State testState,
                                  StageDriver.State nextState)

This method performs an atomic conditional state transition change to the value specified by the nextState parameter if and only if the current state is equal to the test state.

start

public abstract void start()
                    throws StageException

This method is used to start the driver, run the preprocess() method of the attached stage and to then begin processing any objects fed to this driver's Feeder.

Specified by:

start in interface StageDriver

Throws:

StageException - Thrown if there is an error during stage startup. In most cases, such errors will be handled internally by the driver.

finish

public abstract void finish()
                     throws StageException

This method waits for the stage(s) queue(s) to empty and any processor thread(s) to exit cleanly and then calls release() to release any resources acquired during processing, if possible.

Specified by:

finish in interface StageDriver

Throws:

StageException - Thrown if there is an error during driver shutdown. Ordinarily such exceptions will be handled internally.

setFaultTolerance

public final void setFaultTolerance(FaultTolerance faultTolerance)

Sets the failure tolerance flag for the worker thread. If faultTolerance is set to CHECKED, StageExceptions thrown by the Stage.process(Object) method will not interrupt queue processing, but will simply be logged with a severity of ERROR. If faultTolerance is set to ALL, runtime exceptions will also be logged and otherwise ignored.

Parameters:

faultTolerance - the flag value

getFaultTolerance

public final FaultTolerance getFaultTolerance()

Getter for property faultTolerant.

Returns:

Value of property faultTolerant.

recordFatalError

protected void recordFatalError(Throwable error)

Store a fatal error.

Parameters:

error - The error to be stored for later analysis

getFatalErrors

public List<Throwable> getFatalErrors()

Returns a list of unrecoverable errors that occurred during stage processing.

Specified by:

getFatalErrors in interface StageDriver

Returns:

A list of unrecoverable errors that occurred during stage processing.

recordProcessingException

protected void recordProcessingException(Object data,
                                         Throwable error)

Store processing failure information for the specified data object.

Parameters:

data - The data being processed at the time of the error

error - The error encountered

getProcessingExceptions

public List<ProcessingException> getProcessingExceptions()

Returns a list of errors that occurred while processing data objects, along with the objects that were being processed when the errors were generated.

Specified by:

getProcessingExceptions in interface StageDriver

Returns:

The list of non-fatal processing errors.