com.github.dm.jrt.channel

Interface StreamingChannel<IN,OUT>

Type Parameters:

IN - the input data type.

OUT - the output data type.

All Superinterfaces:

Channel, Channel.InputChannel<IN>, Channel.OutputChannel<OUT>, IOChannel<IN,OUT>, Iterable<OUT>, Iterator<OUT>

public interface StreamingChannel<IN,OUT>
extends IOChannel<IN,OUT>

Interface defining a streaming channel, that is, an I/O channel in which data are processed by one or more routine invocations.

This type of channel is mainly meant to act as a processing pipeline in which each input produces one or more results.
Streaming channels can be concatenated to form a new channel, or used as inputs for other channels or routine invocations.
Note that a streaming channel must always be closed in order to correctly terminate the lifecycle of the involved invocations.

Created by davide-maestroni on 09/24/2015.

Nested Class Summary

Nested classes/interfaces inherited from interface com.github.dm.jrt.channel.Channel

Channel.InputChannel<IN>, Channel.OutputChannel<OUT>

Method Summary

Methods

Modifier and Type	Method and Description
StreamingChannel<IN,OUT>	after(long delay, TimeUnit timeUnit) Tells the channel to delay the transfer of data of the specified time duration. Note that an abortion command will be delayed as well.
StreamingChannel<IN,OUT>	after(TimeDuration delay) Tells the channel to delay the transfer of data of the specified time duration. Note that an abortion command will be delayed as well.
StreamingChannel<IN,OUT>	afterMax(long timeout, TimeUnit timeUnit) Tells the channel to wait at the max the specified time duration for the next result to be available.
StreamingChannel<IN,OUT>	afterMax(TimeDuration timeout) Tells the channel to wait at the max the specified time duration for the next result to be available.
StreamingChannel<IN,OUT>	allInto(Collection<? super OUT> results) Consumes all the results by waiting for the routine to complete at the maximum for the set timeout, and put them into the specified collection.
StreamingChannel<IN,OUT>	close() Closes the channel input. If the channel is already closed, this method has no effect.
<BEFORE> StreamingChannel<BEFORE,OUT>	combine(IOChannel<BEFORE,? extends IN> channel) Creates a new streaming channel which is the concatenation of the specified channel and this one.
<AFTER> StreamingChannel<IN,AFTER>	concat(IOChannel<? super OUT,AFTER> channel) Creates a new streaming channel which is the concatenation of this channel and the specified one.
StreamingChannel<IN,OUT>	eventuallyAbort() Tells the channel to abort the invocation execution in case no result is available before the timeout has elapsed.
StreamingChannel<IN,OUT>	eventuallyAbort(Throwable reason) Tells the channel to abort the invocation execution in case no result is available before the timeout has elapsed.
StreamingChannel<IN,OUT>	eventuallyExit() Tells the channel to break execution in case no result is available before the timeout has elapsed.
StreamingChannel<IN,OUT>	eventuallyThrow() Tells the channel to throw an ExecutionTimeoutException in case no result is available before the timeout has elapsed.
StreamingChannel<IN,OUT>	immediately() Tells the channel to not wait for results to be available.
StreamingChannel<IN,OUT>	now() Tells the channel to not delay the transfer of data.
StreamingChannel<IN,OUT>	orderByCall() Tells the channel to sort the passed input data based on the order of the calls to the pass methods.
StreamingChannel<IN,OUT>	orderByChance() Tells the channel to avoid sorting the passed input in any particular order.
StreamingChannel<IN,OUT>	orderByDelay() Tells the channel to sort the passed input data based on the specific delay. Note that only the inputs passed with a 0 delay will be delivered in the same order as they are passed to the channel, while the others will be delivered as soon as the dedicated runner handles the specific execution.
StreamingChannel<IN,OUT>	pass(Channel.OutputChannel<? extends IN> channel) Passes the data returned by the specified channel to this one.
StreamingChannel<IN,OUT>	pass(IN... inputs) Passes the specified input data to this channel.
StreamingChannel<IN,OUT>	pass(IN input) Passes the specified input to this channel.
StreamingChannel<IN,OUT>	pass(Iterable<? extends IN> inputs) Passes the data returned by the specified iterable to this channel.
StreamingChannel<IN,OUT>	passTo(OutputConsumer<? super OUT> consumer) Binds this channel to the specified consumer.
StreamingChannel<IN,OUT>	skip(int count) Skips the first count available results by waiting at the maximum for the set timeout.

Methods inherited from interface com.github.dm.jrt.channel.IOChannel

asInput, asOutput

Methods inherited from interface com.github.dm.jrt.channel.Channel.OutputChannel

all, checkComplete, hasNext, isBound, next, next, passTo

Methods inherited from interface com.github.dm.jrt.channel.Channel

abort, abort, isEmpty, isOpen

Methods inherited from interface java.util.Iterator

remove

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

after

@NotNull
StreamingChannel<IN,OUT> after(@NotNull
                                     TimeDuration delay)

Tells the channel to delay the transfer of data of the specified time duration.
Note that an abortion command will be delayed as well. Note, however, that a delayed abortion will not prevent the invocation from completing, as input data do.

Specified by:

after in interface Channel.InputChannel<IN>

Specified by:

after in interface IOChannel<IN,OUT>

Parameters:

delay - the delay.

Returns:

this channel.

after

@NotNull
StreamingChannel<IN,OUT> after(long delay,
                                     @NotNull
                                     TimeUnit timeUnit)

Tells the channel to delay the transfer of data of the specified time duration.
Note that an abortion command will be delayed as well. Note, however, that a delayed abortion will not prevent the invocation from completing, as input data do.

Specified by:

after in interface Channel.InputChannel<IN>

Specified by:

after in interface IOChannel<IN,OUT>

Parameters:

delay - the delay value.

timeUnit - the delay time unit.

Returns:

this channel.

now

@NotNull
StreamingChannel<IN,OUT> now()

Tells the channel to not delay the transfer of data.

Specified by:

now in interface Channel.InputChannel<IN>

Specified by:

now in interface IOChannel<IN,OUT>

Returns:

this channel.

orderByCall

@NotNull
StreamingChannel<IN,OUT> orderByCall()

Tells the channel to sort the passed input data based on the order of the calls to the pass methods.

By default no particular order is applied.

Specified by:

orderByCall in interface Channel.InputChannel<IN>

Specified by:

orderByCall in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.InputChannel.orderByChance(), Channel.InputChannel.orderByDelay()

orderByChance

@NotNull
StreamingChannel<IN,OUT> orderByChance()

Tells the channel to avoid sorting the passed input in any particular order.

This is the default behavior.

Specified by:

orderByChance in interface Channel.InputChannel<IN>

Specified by:

orderByChance in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.InputChannel.orderByCall(), Channel.InputChannel.orderByDelay()

orderByDelay

@NotNull
StreamingChannel<IN,OUT> orderByDelay()

Tells the channel to sort the passed input data based on the specific delay.
Note that only the inputs passed with a 0 delay will be delivered in the same order as they are passed to the channel, while the others will be delivered as soon as the dedicated runner handles the specific execution.

By default no particular order is applied.

Specified by:

orderByDelay in interface Channel.InputChannel<IN>

Specified by:

orderByDelay in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.InputChannel.orderByCall(), Channel.InputChannel.orderByChance()

pass

@NotNull
StreamingChannel<IN,OUT> pass(@Nullable
                                    Channel.OutputChannel<? extends IN> channel)

Passes the data returned by the specified channel to this one.

Note that the output channel will be bound as a result of the call, thus effectively preventing any other consumer from getting data from it.

Specified by:

pass in interface Channel.InputChannel<IN>

Specified by:

pass in interface IOChannel<IN,OUT>

Parameters:

channel - the output channel.

Returns:

this channel.

pass

@NotNull
StreamingChannel<IN,OUT> pass(@Nullable
                                    Iterable<? extends IN> inputs)

Passes the data returned by the specified iterable to this channel.

Specified by:

pass in interface Channel.InputChannel<IN>

Specified by:

pass in interface IOChannel<IN,OUT>

Parameters:

inputs - the iterable returning the input data.

Returns:

this channel.

pass

@NotNull
StreamingChannel<IN,OUT> pass(@Nullable
                                    IN input)

Passes the specified input to this channel.

Specified by:

pass in interface Channel.InputChannel<IN>

Specified by:

pass in interface IOChannel<IN,OUT>

Parameters:

input - the input.

Returns:

this channel.

pass

@NotNull
StreamingChannel<IN,OUT> pass(@Nullable
                                    IN... inputs)

Passes the specified input data to this channel.

Specified by:

pass in interface Channel.InputChannel<IN>

Specified by:

pass in interface IOChannel<IN,OUT>

Parameters:

inputs - the input data.

Returns:

this channel.

afterMax

@NotNull
StreamingChannel<IN,OUT> afterMax(@NotNull
                                        TimeDuration timeout)

Tells the channel to wait at the max the specified time duration for the next result to be available.

By default the timeout is set to 0 to avoid unexpected deadlocks.

Specified by:

afterMax in interface Channel.OutputChannel<OUT>

Specified by:

afterMax in interface IOChannel<IN,OUT>

Parameters:

timeout - the maximum timeout.

Returns:

this channel.

afterMax

@NotNull
StreamingChannel<IN,OUT> afterMax(long timeout,
                                        @NotNull
                                        TimeUnit timeUnit)

Tells the channel to wait at the max the specified time duration for the next result to be available.

By default the timeout is set to 0 to avoid unexpected deadlocks.

Specified by:

afterMax in interface Channel.OutputChannel<OUT>

Specified by:

afterMax in interface IOChannel<IN,OUT>

Parameters:

timeout - the maximum timeout value.

timeUnit - the timeout time unit.

Returns:

this channel.

allInto

@NotNull
StreamingChannel<IN,OUT> allInto(@NotNull
                                       Collection<? super OUT> results)

Consumes all the results by waiting for the routine to complete at the maximum for the set timeout, and put them into the specified collection.

Specified by:

allInto in interface Channel.OutputChannel<OUT>

Specified by:

allInto in interface IOChannel<IN,OUT>

Parameters:

results - the collection to fill.

Returns:

this channel.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(), Channel.OutputChannel.eventuallyAbort(Throwable), Channel.OutputChannel.eventuallyExit(), Channel.OutputChannel.eventuallyThrow()

eventuallyAbort

@NotNull
StreamingChannel<IN,OUT> eventuallyAbort()

Tells the channel to abort the invocation execution in case no result is available before the timeout has elapsed.

By default an ExecutionTimeoutException exception will be thrown.

Specified by:

eventuallyAbort in interface Channel.OutputChannel<OUT>

Specified by:

eventuallyAbort in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(Throwable), Channel.OutputChannel.eventuallyExit(), Channel.OutputChannel.eventuallyThrow()

eventuallyAbort

@NotNull
StreamingChannel<IN,OUT> eventuallyAbort(@Nullable
                                               Throwable reason)

Tells the channel to abort the invocation execution in case no result is available before the timeout has elapsed.

By default an ExecutionTimeoutException exception will be thrown.

Specified by:

eventuallyAbort in interface Channel.OutputChannel<OUT>

Specified by:

eventuallyAbort in interface IOChannel<IN,OUT>

Parameters:

reason - the throwable object identifying the reason of the invocation abortion.

Returns:

this channel.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(), Channel.OutputChannel.eventuallyExit(), Channel.OutputChannel.eventuallyThrow()

eventuallyExit

@NotNull
StreamingChannel<IN,OUT> eventuallyExit()

Tells the channel to break execution in case no result is available before the timeout has elapsed.

By default an ExecutionTimeoutException exception will be thrown.

Specified by:

eventuallyExit in interface Channel.OutputChannel<OUT>

Specified by:

eventuallyExit in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(), Channel.OutputChannel.eventuallyAbort(Throwable), Channel.OutputChannel.eventuallyThrow()

eventuallyThrow

@NotNull
StreamingChannel<IN,OUT> eventuallyThrow()

Tells the channel to throw an ExecutionTimeoutException in case no result is available before the timeout has elapsed.

This is the default behavior.

Specified by:

eventuallyThrow in interface Channel.OutputChannel<OUT>

Specified by:

eventuallyThrow in interface IOChannel<IN,OUT>

Returns:

this channel.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(), Channel.OutputChannel.eventuallyAbort(Throwable), Channel.OutputChannel.eventuallyExit()

immediately

@NotNull
StreamingChannel<IN,OUT> immediately()

Tells the channel to not wait for results to be available.

By default the timeout is set to 0 to avoid unexpected deadlocks.

Specified by:

immediately in interface Channel.OutputChannel<OUT>

Specified by:

immediately in interface IOChannel<IN,OUT>

Returns:

this channel.

passTo

@NotNull
StreamingChannel<IN,OUT> passTo(@NotNull
                                      OutputConsumer<? super OUT> consumer)

Binds this channel to the specified consumer. After the call, all the output will be passed only to the consumer. Attempting to read through the dedicated methods will cause an IllegalStateException to be thrown.
Note that the consumer methods will be called on the runner thread.

Specified by:

passTo in interface Channel.OutputChannel<OUT>

Specified by:

passTo in interface IOChannel<IN,OUT>

Parameters:

consumer - the consumer instance.

Returns:

this channel.

skip

@NotNull
StreamingChannel<IN,OUT> skip(int count)

Skips the first count available results by waiting at the maximum for the set timeout.

Specified by:

skip in interface Channel.OutputChannel<OUT>

Specified by:

skip in interface IOChannel<IN,OUT>

Returns:

the first available results.

See Also:

Channel.OutputChannel.afterMax(TimeDuration), Channel.OutputChannel.afterMax(long, TimeUnit), Channel.OutputChannel.immediately(), Channel.OutputChannel.eventuallyAbort(), Channel.OutputChannel.eventuallyAbort(Throwable), Channel.OutputChannel.eventuallyExit(), Channel.OutputChannel.eventuallyThrow()

close

@NotNull
StreamingChannel<IN,OUT> close()

Closes the channel input.
If the channel is already closed, this method has no effect.

Note that this method must be always called when done with the channel.

Specified by:

close in interface IOChannel<IN,OUT>

Returns:

this channel.

combine

@NotNull
<BEFORE> StreamingChannel<BEFORE,OUT> combine(@NotNull
                                                    IOChannel<BEFORE,? extends IN> channel)

Creates a new streaming channel which is the concatenation of the specified channel and this one.

Note that this channel will be closed as a result of the call.

Type Parameters:

BEFORE - the concatenation input type.

Parameters:

channel - the channel after which to concatenate this one.

Returns:

the concatenated channel.

concat

@NotNull
<AFTER> StreamingChannel<IN,AFTER> concat(@NotNull
                                                IOChannel<? super OUT,AFTER> channel)

Creates a new streaming channel which is the concatenation of this channel and the specified one.

Note that the passed channel will be closed as a result of the call.

Type Parameters:

AFTER - the concatenation output type.

Parameters:

channel - the channel to concatenate after this one.

Returns:

the concatenated channel.