org.jtrim2.concurrent.query

Class AsyncReport

java.lang.Object

org.jtrim2.concurrent.query.AsyncReport

public final class AsyncReport
extends Object

Defines how an asynchronous data transfer has completed.

Note that this class does not have a public constructor and can only be initiated by the static factory method: getReport(Throwable, boolean).

The following two properties of the data transfer completion are supported:

• If it was canceled or not.
• The exception describing the error occurred while transferring the data.

When AsyncDataLink instances report that the data transferring was canceled, it should be interpreted as the final data received might not be the fully complete (but can be) data intended to be retrieved. Also when a non-null exception is attached to the AsyncReport instance, the final data might not be the fully complete data due to some errors while trying to retrieve the required data.

Thread safety

Instances of this class are completely safe to be accessed from multiple threads concurrently. Also, instances are immutable except that the attached exception (as every exception in Java) is mutable. Note however, that exceptions are safe to be accessed from multiple threads concurrently.

Synchronization transparency

The methods of this class are synchronization transparent.

See Also:

getReport(Throwable, boolean), AsyncDataLink, AsyncDataListener

Field Summary

Fields

Modifier and Type	Field and Description
static AsyncReport	CANCELED A canceled but error free data transfer.
static AsyncReport	SUCCESS A completely successful data transfer.

Method Summary

Modifier and Type	Method and Description
Throwable	getException() Returns the exception describing the error occurred during the data transfer of which completion this AsyncReport represents.
static AsyncReport	getReport(Throwable exception) Returns an AsyncReport instance with the specified exception attached to it and deriving the canceled state from the type of the exception.
static AsyncReport	getReport(Throwable exception, boolean canceled) Returns an AsyncReport instance with the specified exception attached to it and with the specified canceled state.
boolean	isCanceled() Returns true if this AsyncReport defines a canceled data transfer.
boolean	isSuccess() Returns true if this AsyncReport defines a completely successful completion of a data transfer.
String	toString() Returns the string representation of this AsyncReport in no particular format.

Methods inherited from class java.lang.Object

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

Field Detail

SUCCESS

public static final AsyncReport SUCCESS

A completely successful data transfer. This AsyncReport instance is not canceled and does not have an exception object attached to it.

This AsyncReport object is completely immutable.

CANCELED

public static final AsyncReport CANCELED

A canceled but error free data transfer. This AsyncReport instance is canceled and does not have an exception object attached to it.

This AsyncReport object is completely immutable.

Method Detail

getReport

public static AsyncReport getReport(Throwable exception)

Returns an AsyncReport instance with the specified exception attached to it and deriving the canceled state from the type of the exception. That is, if the exception is an instance of OperationCanceledException, the operations is assumed to be canceled.

Note that this method does not necessarily returns a new unique object if not necessary.

Parameters:

exception - the exception attached to the returned AsyncReport instance. This is the exception which will be returned by the getException() method of the created AsyncReport. This argument can be null which means that no exception is attached to the returned AsyncReport instance, that is the data retrieval process has terminate without errors.

Returns:

the AsyncReport instance with the specified exception attached to it and the derived canceled state. This method never returns null.

getReport

public static AsyncReport getReport(Throwable exception,
                                    boolean canceled)

Returns an AsyncReport instance with the specified exception attached to it and with the specified canceled state.

Note that this method does not necessarily returns a new unique object if not necessary.

Parameters:

exception - the exception attached to the returned AsyncReport instance. This is the exception which will be returned by the getException() method of the created AsyncReport. This argument can be null which means that no exception is attached to the returned AsyncReport instance, that is the data retrieval process has terminate without errors.

canceled - the canceled state of the returned AsyncReport instance. This value will be returned by the isCanceled method of the returned AsyncReport instance.

Returns:

the AsyncReport instance with the specified exception attached to it and with the specified canceled state. This method never returns null.

isSuccess

public boolean isSuccess()

Returns true if this AsyncReport defines a completely successful completion of a data transfer. That is, if it was not canceled and does not have an exception attached to it.

If this method returns true, a data transfer requested from an AsyncDataLink must have returned the complete requested data.

Returns:

true if this AsyncReport defines a completely successful completion of a data transfer, false otherwise

See Also:

isCanceled(), getException()

isCanceled

public boolean isCanceled()

Returns true if this AsyncReport defines a canceled data transfer.

If this method returns true, a data transfer requested from an AsyncDataLink may not have returned the complete requested data.

Returns:

true if this AsyncReport defines a canceled data transfer, false otherwise

getException

public Throwable getException()

Returns the exception describing the error occurred during the data transfer of which completion this AsyncReport represents.

If this method returns a non-null exception, a data transfer requested from an AsyncDataLink may not have returned the complete requested data.

Returns:

the exception describing the error occurred during the data transfer of which completion this AsyncReport represents or null if no error occurred while transferring the data

toString

public String toString()

Returns the string representation of this AsyncReport in no particular format.

This method is intended to be used for debugging only.

Overrides:

toString in class Object

Returns:

the string representation of this object in no particular format. This method never returns null.