com.tagtraum.jipes

Class SignalPipeline<I,O>

java.lang.Object

com.tagtraum.jipes.SignalPipeline<I,O>

Type Parameters:

I - type of the input values

O - type of the output values

All Implemented Interfaces:

SignalProcessor<I,O>

public class SignalPipeline<I,O>
extends Object
implements SignalProcessor<I,O>

A signal pipeline is a straight chain (that is every chain element has exactly one child) of multiple SignalProcessors.

It has a head and a tail and is created using these two processors. Building pipelines is useful for creating blackbox building blocks that in turn can be used for building more complex processing graphs.

The structure of a pipeline is meant to be immutable, however, since you hand the processor chain to it when constructing the pipeline, this is not enforced programmatically.

Author:

Hendrik Schreiber

Constructor Summary

Constructors

Constructor and Description
SignalPipeline(SignalProcessor<?,?>... processors) Creates a signal processor pipeline from the given processors (in that same order).
SignalPipeline(SignalProcessor<I,?> first, SignalProcessor<?,O> last, boolean verifyStraightChain) Creates a pipeline with the given head and tail.

Method Summary

Modifier and Type	Method and Description
<O2> SignalProcessor<O,O2>	connectTo(SignalProcessor<O,O2> oSignalProcessor) Connects this processor to another processor to forward processed data to.
<O2> SignalProcessor<O,O2>	disconnectFrom(SignalProcessor<O,O2> oSignalProcessor) Disconnects a child processor.
boolean	equals(Object o)
void	flush() Asks to complete all pending operations.
SignalProcessor<O,?>[]	getConnectedProcessors() Lists all connected processors.
SignalProcessor<I,?>	getFirstProcessor() First processor of this pipeline.
Object	getId() Arbitrary object to identify a processor.
O	getOutput() First calls SignalProcessor.flush(), then returns the pending output, should there be any.
<T extends SignalProcessor> T	getProcessorWithClass(Class<T> klass) Returns the first processor that is an instance of the given Class.
SignalProcessor<?,?>	getProcessorWithId(Object id) Returns the first processor with the given id.
int	hashCode()
<O2> SignalPipeline<I,O2>	joinWith(SignalProcessor<O,O2> processor) Creates a new pipeline from this pipeline's head to the given processor by connecting this pipeline's tail to the given processor and using the current head and the newly added processor as tail.
void	process(I i) Asks this processor to work on the provided data and pipe the output to the connected processors' own SignalProcessor.process(Object) method. Implementing methods must not modify or hold on to the provided data.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SignalPipeline

public SignalPipeline(SignalProcessor<I,?> first,
                      SignalProcessor<?,O> last,
                      boolean verifyStraightChain)
               throws IllegalArgumentException

Creates a pipeline with the given head and tail. Note that there must be a straight chain of parent/children relationships between the head and the tail before constructing this pipeline. I.e. it is the caller's responsibility to create the connections.

Parameters:

first - first/head processor

last - last/tail processor

verifyStraightChain - indicates whether you want to make sure that every chain element has exactly one child and that there is a connection between head and tail

Throws:

IllegalArgumentException - if their is no straight connection between head and tail, i.e. one processor along the way has more than old child (only thrown when verifyStraightChain == true)

See Also:

SignalPipeline(com.tagtraum.jipes.SignalProcessor[])

SignalPipeline

public SignalPipeline(SignalProcessor<?,?>... processors)

Creates a signal processor pipeline from the given processors (in that same order). This constructor not only creates the pipeline object, but also creates the links between its processors by calling their SignalProcessor.connectTo(com.tagtraum.jipes.SignalProcessor) methods. Note that this way of creating a processing chain works around type checking mechanisms. I.e. if one processor's output type does not match the next processor's input type, most likely a ClassCastException will be thrown at runtime.

If you want to wrap a series of processors that are already connected, use SignalPipeline(SignalProcessor, SignalProcessor, boolean).

Parameters:

processors - array of processors that are supposed to make a pipeline (starting with the head, ending with the tail)

See Also:

SignalProcessor.connectTo(com.tagtraum.jipes.SignalProcessor)

Method Detail

getFirstProcessor

public SignalProcessor<I,?> getFirstProcessor()

First processor of this pipeline.

Returns:

first processor

getProcessorWithId

public SignalProcessor<?,?> getProcessorWithId(Object id)
                                        throws IllegalStateException

Returns the first processor with the given id.

Parameters:

id - id must not be null

Returns:

the found processor or null

Throws:

IllegalStateException - if this pipeline is not a line, but a tree or graph

getProcessorWithClass

public <T extends SignalProcessor> T getProcessorWithClass(Class<T> klass)
                                                    throws IllegalStateException

Returns the first processor that is an instance of the given Class.

Parameters:

klass - klass must not be null

Returns:

the found processor or null

Throws:

IllegalStateException - if this pipeline is not a line, but a tree or graph

joinWith

public <O2> SignalPipeline<I,O2> joinWith(SignalProcessor<O,O2> processor)

Creates a new pipeline from this pipeline's head to the given processor by connecting this pipeline's tail to the given processor and using the current head and the newly added processor as tail.

The original pipeline remains unchanged.

Type Parameters:

O2 - new output type

Parameters:

processor - processor to append

Returns:

new pipeline

process

public void process(I i)
             throws IOException

Description copied from interface: SignalProcessor

Asks this processor to work on the provided data and pipe the output to the connected processors' own SignalProcessor.process(Object) method.
Implementing methods must not modify or hold on to the provided data. In other words: the provided object does not belong to you, its values are only guaranteed to be stable for the duration of the call.

If you need to hold on to data, create a copy of the provided data via a copy constructor or the Object.clone() method.

It is the responsibility of implementing classes to call the SignalProcessor.process(Object) method of any connected processors. To manage connected processors classes may want to use a SignalProcessorSupport instance.

Specified by:

process in interface SignalProcessor<I,O>

Parameters:

i - data to process

Throws:

IOException - if a processing error occurs

See Also:

SignalProcessor.getConnectedProcessors()

flush

public void flush()
           throws IOException

Description copied from interface: SignalProcessor

Asks to complete all pending operations. This method may be called multiple times without any adverse effects. It's the implementation's responsibility to call its kids' SignalProcessor.flush() method.

Specified by:

flush in interface SignalProcessor<I,O>

Throws:

IOException - if a processing error occurs

getOutput

public O getOutput()
            throws IOException

Description copied from interface: SignalProcessor

First calls SignalProcessor.flush(), then returns the pending output, should there be any. Note that this call may only succeed once to preserve memory.

Specified by:

getOutput in interface SignalProcessor<I,O>

Returns:

output, if available. If not, null is returned

Throws:

IOException - if a processing error occurs

getId

public Object getId()

Description copied from interface: SignalProcessor

Arbitrary object to identify a processor. This is useful for associating with results provided by SignalProcessor.getOutput().

Specified by:

getId in interface SignalProcessor<I,O>

Returns:

arbitrary non-null object. If this method returns null, potential results will not be associated with an identifier and potentially dropped

See Also:

SignalPump.pump()

connectTo

public <O2> SignalProcessor<O,O2> connectTo(SignalProcessor<O,O2> oSignalProcessor)

Description copied from interface: SignalProcessor

Connects this processor to another processor to forward processed data to. This method returns its parameter and therefore encourages method chaining to build processing chains/pipelines.

Specified by:

connectTo in interface SignalProcessor<I,O>

Type Parameters:

O2 - output type of the processor we want to connect to

Parameters:

oSignalProcessor - processor

Returns:

the just added processor

See Also:

SignalProcessor.disconnectFrom(SignalProcessor), SignalProcessor.getConnectedProcessors(), SignalPipeline

disconnectFrom

public <O2> SignalProcessor<O,O2> disconnectFrom(SignalProcessor<O,O2> oSignalProcessor)

Description copied from interface: SignalProcessor

Disconnects a child processor.

Specified by:

disconnectFrom in interface SignalProcessor<I,O>

Type Parameters:

O2 - output type of the processor we want to disconnect from

Parameters:

oSignalProcessor - processor

Returns:

the processor, if it was indeed removed

See Also:

SignalProcessor.connectTo(SignalProcessor), SignalProcessor.getConnectedProcessors()

getConnectedProcessors

public SignalProcessor<O,?>[] getConnectedProcessors()

Description copied from interface: SignalProcessor

Lists all connected processors.

Specified by:

getConnectedProcessors in interface SignalProcessor<I,O>

Returns:

array of registered processors, never null

See Also:

SignalProcessor.disconnectFrom(SignalProcessor), SignalProcessor.connectTo(SignalProcessor)

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object