Package 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:

  • Field Summary

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

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • 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 Details

    • 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

      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.