public final class AsyncHelper extends Object
AsyncDataLink.
This class cannot be inherited or instantiated.
AsyncLinks,
AsyncQueries| 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. |
public static DataTransferException getTransferException(Throwable... exceptions)
DataTransferException from the specified
exceptions.
The exception will be created as follows:
null is returned.
DataTransferException, if it is not then
a new DataTransferException with the specified exception as its
cause.
DataTransferException is created and the specified exceptions
will be added to it as suppressed
exceptions.
exceptions - the array of exceptions to be represented by the
returned DataTransferException exception. This array cannot be
null and cannot contain null elements.DataTransferException representing the specified
exceptions or null if there was no exception specified
(empty array was passed)NullPointerException - thrown if the passed array of exceptions is
null or contains null elementspublic static <DataType> AsyncDataListener<OrderedData<DataType>> makeSafeOrderedListener(AsyncDataListener<? super DataType> outputListener)
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.DataType - the type of the data to be forwarded to the specified
listeneroutputListener - the AsyncDataListener to which the data
reported to the returned listener will be eventually forwarded. This
argument cannot be null.AsyncDataListener which forwards data (with an
additional index) to a specified listener in a thread-safe manner. This
method never returns null.makeSafeListener(AsyncDataListener)public static <DataType> AsyncDataListener<DataType> makeSafeListener(AsyncDataListener<? super DataType> outputListener)
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.
DataType - the type of the data to be forwarded to the specified
listeneroutputListener - the AsyncDataListener to which the data
reported to the returned listener will be eventually forwarded. This
argument cannot be null.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.makeSafeOrderedListener(AsyncDataListener)