org.jtrim2.concurrent.query

Class AsyncHelper

java.lang.Object

org.jtrim2.concurrent.query.AsyncHelper

public final class AsyncHelper
extends Object

Contains useful helper methods for asynchronous data transferring using an AsyncDataLink.

This class cannot be inherited or instantiated.

Thread safety

Unless otherwise noted, methods of this class are safe to use by multiple threads concurrently.

Synchronization transparency

Unless otherwise noted, methods of this class are not synchronization transparent.

See Also:

AsyncLinks, AsyncQueries

Method Summary

Modifier and Type	Method and Description
static DataTransferException	getTransferException(Throwable... exceptions) Creates a single DataTransferException from the specified exceptions.
static <DataType> AsyncDataListener<DataType>	makeSafeListener(AsyncDataListener<? super DataType> outputListener) Creates an AsyncDataListener which forwards data to a specified listener in a thread-safe manner.
static <DataType> AsyncDataListener<OrderedData<DataType>>	makeSafeOrderedListener(AsyncDataListener<? super DataType> outputListener) Creates an AsyncDataListener which forwards data (with an additional index) to a specified listener in a thread-safe manner.

Methods inherited from class java.lang.Object

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

Method Detail

getTransferException

public static DataTransferException getTransferException(Throwable... exceptions)

Creates a single DataTransferException from the specified exceptions.

The exception will be created as follows:

• If there are no exceptions specified null is returned.
• If there is a single exception is specified: The specified exception is returned if it is a DataTransferException, if it is not then a new DataTransferException with the specified exception as its cause.
• If there are more than one exception specified: A new DataTransferException is created and the specified exceptions will be added to it as suppressed exceptions.

Parameters:

exceptions - the array of exceptions to be represented by the returned DataTransferException exception. This array cannot be null and cannot contain null elements.

Returns:

the DataTransferException representing the specified exceptions or null if there was no exception specified (empty array was passed)

Throws:

NullPointerException - thrown if the passed array of exceptions is null or contains null elements

makeSafeOrderedListener

public static <DataType> AsyncDataListener<OrderedData<DataType>> makeSafeOrderedListener(AsyncDataListener<? super DataType> outputListener)

Creates an AsyncDataListener which forwards data (with an additional index) to a specified listener in a thread-safe manner. That is, the onDataArrive and onDoneReceive method of the returned AsyncDataListener can be called concurrently from multiple threads and these methods of the specified listener will still not be called concurrently. Also data will be forwarded to the specified listener only if there were no data forwarded with a greater or equal index and the onDoneReceive method has not yet been called.

As an example see the following single threaded code:

 AsyncDataListener<OrderedData<String>> listener;
 listener = makeSafeOrderedListener(...);

 listener.onDataArrive(new OrderedData<>(1, "data1"));
 listener.onDataArrive(new OrderedData<>(3, "data3"));
 listener.onDataArrive(new OrderedData<>(2, "data2"));
 listener.onDoneReceive(AsyncReport.SUCCESS);
 listener.onDataArrive(new OrderedData<>(4, "data4"));
 listener.onDoneReceive(AsyncReport.CANCELED);
 

The above code will forward "data1" and "data3" to the wrapped listener (which should be written in the place of "...") only and in this order. Also only the AsyncReport.SUCCESS will be reported in the onDoneReceive method. That is, the "data3" line and the two lines below the first onDoneReceive call will be effectively ignored.

Type Parameters:

DataType - the type of the data to be forwarded to the specified listener

Parameters:

outputListener - the AsyncDataListener to which the data reported to the returned listener will be eventually forwarded. This argument cannot be null.

Returns:

the AsyncDataListener which forwards data (with an additional index) to a specified listener in a thread-safe manner. This method never returns null.

See Also:

makeSafeListener(AsyncDataListener)

makeSafeListener

public static <DataType> AsyncDataListener<DataType> makeSafeListener(AsyncDataListener<? super DataType> outputListener)

Creates an AsyncDataListener which forwards data to a specified listener in a thread-safe manner.

This method is similar to the makeSafeOrderedListener method, the only difference is that the listener returned by this method implicitly assumes the order of the datas from the order of the method calls.

More precisely, the onDataArrive and onDoneReceive method of the returned AsyncDataListener can be called concurrently from multiple threads and these methods of the specified listener will still not be called concurrently. Also data will be forwarded to the specified listener only if the onDoneReceive method has not yet been called.

As an example see the following single threaded code:

 AsyncDataListener<String> listener;
 listener = makeSafeOrderedListener(...);

 listener.onDataArrive("data1");
 listener.onDataArrive("data2");
 listener.onDoneReceive(AsyncReport.SUCCESS);
 listener.onDataArrive("data3");
 listener.onDoneReceive(AsyncReport.CANCELED);
 

The above code will forward "data1" and "data2" to the wrapped listener (which should be written in the place of "...") only and in this order. Also only the AsyncReport.SUCCESS will be reported in the onDoneReceive method. That is, the two lines below the first onDoneReceive call will be effectively ignored.

Note that although invoking two onDataArrive methods concurrently is safe regarding consistency, in practice this must be avoided. This must be avoided because there is no telling in what order will these datas be forwarded and the contract of AsyncDataListener requires that a data forwarded be at least as accurate as the previous ones. This implies that if the onDataArrive method is called concurrently the datas forwarded to them must be equivalent. In this case it was a waste of effort to forward all the data instead of just one of them.

Type Parameters:

DataType - the type of the data to be forwarded to the specified listener

Parameters:

outputListener - the AsyncDataListener to which the data reported to the returned listener will be eventually forwarded. This argument cannot be null.

Returns:

the AsyncDataListener which forwards data to a specified listener in a thread-safe manner. This method never returns null. This method may return the same listener passed in the argument if the specified listener already has the properties defined for the return value.

See Also:

makeSafeOrderedListener(AsyncDataListener)