org.jtrim2.concurrent.query.io

Class AsyncChannelLink<DataType>

java.lang.Object

org.jtrim2.concurrent.query.io.AsyncChannelLink<DataType>

Type Parameters:

DataType - the type of data to be provided by this AsyncDataLink

All Implemented Interfaces:

AsyncDataLink<DataType>

public final class AsyncChannelLink<DataType>
extends Object
implements AsyncDataLink<DataType>

Defines an AsyncDataLink which allows to read an arbitrary Channel and process its content to be provided as asynchronously.

The implementations relies on two executors, namely: processorExecutor and cancelExecutor. When the data is requested from AsyncChannelLink it will submit a task to processorExecutor which will actually open a new channel which is then processed in the same task. In this task will the AsyncDataListener be notified of the data to be provided.

When a data retrieval request is canceled through the returned AsyncDataController, the basic action taken is to cancel the task submitted to the processorExecutor and if the task has not yet been started processing the channel, it will be canceled without actually starting to process it. When however, the opened channel implements the InterruptibleChannel, it will even be asynchronously closed, so reads while processing the channel will cause ClosedChannelException to be thrown which is interpreted as a cancellation. Since closing the channel might be an external call, it is actually done in a task submitted to cancelExecutor.

Note that although actual canceling of the processing of a channel may take some time, the AsyncChannelLink listening for the data will see as if requesting a cancel request is almost instantaneous regardless how long actually the canceling takes.

Thread safety

As required by AsyncDataLink, methods of this class are safe to be accessed by multiple threads concurrently.

Synchronization transparency

The methods of this class are not synchronization transparent.

See Also:

ChannelOpener, ChannelProcessor

Constructor Summary

Constructors

Constructor and Description
AsyncChannelLink(TaskExecutor processorExecutor, TaskExecutor cancelExecutor, ChannelOpener<? extends ChannelType> channelOpener, ChannelProcessor<? extends DataType,ChannelType> channelProcessor) Creates a new AsyncChannelLink with the specified executors, ChannelOpener and ChannelProcessor.

Method Summary

Modifier and Type	Method and Description
AsyncDataController	getData(CancellationToken cancelToken, AsyncDataListener<? super DataType> dataListener) Starts retrieving the data which is linked to this AsyncDataLink.

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncChannelLink

public AsyncChannelLink(TaskExecutor processorExecutor,
                        TaskExecutor cancelExecutor,
                        ChannelOpener<? extends ChannelType> channelOpener,
                        ChannelProcessor<? extends DataType,ChannelType> channelProcessor)

Creates a new AsyncChannelLink with the specified executors, ChannelOpener and ChannelProcessor.

Type Parameters:

ChannelType - the type of the channel to be opened by the channelOpener and then processed by channelProcessor

Parameters:

processorExecutor - the executor to which tasks will be submitted to process a channel opened by channelOpener. This argument may not be null.

cancelExecutor - the executor to which tasks will be submitted to asynchronously close channels if the request for processing it has been canceled. This executor can be the same as processorExecutor, note however that in this case, the processing of the channel may block the task which is submitted to cancel it (by closing the channel). This argument cannot be null.

channelOpener - the ChannelOpener which must open a new channel to be processed by channelProcessor. The ChannelOpener must always open a channel to the same source (e.g.: with files, to the same file) to preserve the contract of the AsyncDataLink. This argument cannot be null.

channelProcessor - the ChannelProcessor which must process open channels and forward the data it reads from it to the AsyncDataLink. This argument cannot be null.

Throws:

NullPointerException - thrown if any of the arguments is null

Method Detail

getData

public AsyncDataController getData(CancellationToken cancelToken,
                                   AsyncDataListener<? super DataType> dataListener)

Starts retrieving the data which is linked to this AsyncDataLink. The data will be forwarded to the specified listener usually asynchronously on a separate thread. Note however that this method may also forward the data synchronously on the current thread to the listener if it is readily available and does not need some expensive operation to load.

Once this method has been called successfully, the onDoneReceive method of the listener must be called eventually regardless what happens. Failing to call this method is a serious failure of the AsyncDataLink implementation.

Implementation note: The state of progress of the data retrieval process can possibly be a different type of object than the one provided by the channel processor.

Specified by:

getData in interface AsyncDataLink<DataType>

Parameters:

cancelToken - the CancellationToken signaling if the data retrieval process need to be canceled. Implementations may ignore cancellation requests but they should cancel the data retrieval and call the onDoneReceive method of the listener, signaling that the data retrieval cannot be completed due to cancellation. This argument cannot be null.

dataListener - the listener to which the data is to be forwarded. This argument cannot be null.

Returns:

the AsyncDataController which can be used to control the way it is being loaded and request the progress of the data retrieving process. This method must never return null.