# Class AsyncResource<V>

java.lang.Object
java.util.Observable
com.codename1.util.AsyncResource<V>

Direct Known Subclasses:
  `AsyncMedia.PauseRequest, AsyncMedia.PlayRequest, BleScan, BrowserWindow.EvalRequest, ClassicDiscovery, MessageEvent.PromptPromise, Oauth2.RefreshTokenRequest`

public class AsyncResource<V> extends Observable
A wrapper for an object that needs to be loaded asynchronously. This can serve as a handle for the object to be passed around irrespective of whether the object has finished loading. Conceptually this is very similar to Futures and Promises.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `AsyncResource.AsyncExecutionException`
  Exception to wrap exceptions that are thrown during asynchronous execution.
  `static class`
  `AsyncResource.CancellationException`
  Exception thrown when the AsyncResource is cancelled.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AsyncResource()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(AsyncResource<V> resource)`
  Adds another AsyncResource as a listener to this async resource.
  `static AsyncResource<Boolean>`
  `all(AsyncResource<?>... resources)`
  Creates a single AsyncResource that will fire its ready() only when all of the provided resources are ready.
  `static AsyncResource<Boolean>`
  `all(Collection<AsyncResource<?>> resources)`
  Creates a single AsyncResource that will fire its ready() only when all of the provided resources are ready.
  `Promise<V>`
  `asPromise()`
  Wraps this AsyncResource object as a `Promise`
  `void`
  `await()`
  Waits and blocks until this AsyncResource is done.
  `static void`
  `await(AsyncResource<?>... resources)`
  Waits for a set of AsyncResources to be complete.
  `static void`
  `await(Collection<AsyncResource<?>> resources)`
  Waits for a set of AsyncResources to be complete.
  `boolean`
  `cancel(boolean mayInterruptIfRunning)`
  Cancels loading the resource.
  `void`
  `complete(V value)`
  Sets the resource value.
  `void`
  `error(Throwable t)`
  Sets the error for this resource in the case that it could not be loaded.
  `AsyncResource<V>`
  `except(SuccessCallback<Throwable> callback)`
  Sets callback to run if an error occurs.
  `AsyncResource<V>`
  `except(SuccessCallback<Throwable> callback, EasyThread t)`
  Sets callback to run if an error occurs.
  `V`
  `get()`
  Gets the resource synchronously.
  `V`
  `get(int timeout)`
  Gets the resource synchronously.
  `V`
  `get(V defaultVal)`
  Gets the resource if it is ready.
  `boolean`
  `isCancelled()`
  Checks if the resource loading was cancelled.
  `static boolean`
  `isCancelled(Throwable t)`
  Returns true if the provided throwable was caused by a cancellation of an AsyncResource.
  `boolean`
  `isDone()`
  Checks if the resource loading is done.
  `boolean`
  `isReady()`
  Checks if the resource is ready.
  `void`
  `onResult(AsyncResult<V> onResult)`
  Combines ready() and except() into a single callback with 2 parameters.
  `AsyncResource<V>`
  `ready(SuccessCallback<V> callback)`
  Runs the provided callback when the resource is ready.
  `AsyncResource<V>`
  `ready(SuccessCallback<V> callback, EasyThread t)`
  Runs the provided callback when the resource is ready.
  `void`
  `waitFor()`
  Wait for loading to complete.

  ### Methods inherited from class Observable

  `addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### AsyncResource

    public AsyncResource()

- ## Method Details

  - ### isCancelled

    public static boolean isCancelled(Throwable t)

    Returns true if the provided throwable was caused by a cancellation of an AsyncResource.

    ###### Parameters

    - `t`: The exception to check for a cancellation.

    ###### Returns

    True if the exception was caused by cancelling an AsyncResource.

  - ### all

    public static AsyncResource<Boolean> all(AsyncResource<?>... resources)

    Creates a single AsyncResource that will fire its ready() only when all of the provided resources are ready. And will fire an exception if any of the provided resources fires an exception.

    ###### Parameters

    - `resources`: One ore more resources to wrap.

    ###### Returns

    A combined AsyncResource.

  - ### all

    public static AsyncResource<Boolean> all(Collection<AsyncResource<?>> resources)

    Creates a single AsyncResource that will fire its ready() only when all of the provided resources are ready. And will fire an exception if any of the provided resources fires an exception.

    ###### Parameters

    - `resources`: One ore more resources to wrap.

    ###### Returns

    A combined AsyncResource.

  - ### await

    public static void await(Collection<AsyncResource<?>> resources) throws AsyncResource.AsyncExecutionException

    Waits for a set of AsyncResources to be complete. If any of them fires an exception, then this method will throw a RuntimeException with that exception as the cause.

    ###### Parameters

    - `resources`: The resources to wait for.
    Throws:
      `AsyncResource.AsyncExecutionException`

  - ### await

    public static void await(AsyncResource<?>... resources) throws AsyncResource.AsyncExecutionException

    Waits for a set of AsyncResources to be complete. If any of them fires an exception, then this method will throw a RuntimeException with that exception as the cause.

    ###### Parameters

    - `resources`: The resources to wait for.
    Throws:
      `AsyncResource.AsyncExecutionException`

  - ### cancel

    public boolean cancel(boolean mayInterruptIfRunning)

    Cancels loading the resource.

    ###### Parameters

    - `mayInterruptIfRunning`

    ###### Returns

    True if the resource loading was cancelled. False if the loading was already done.

    Cancellation notifies observers, which is how a waiter learns the resource became terminal. It used to call `setChanged()` and stop there, leaving the flag set with nothing notified: a thread inside `get()` adds an observer, checks `isDone()`, and then waits, so a cancel landing after that check woke nobody and the waiter blocked forever on a resource that had already finished.

    It deliberately does not run the callbacks registered through `ready(SuccessCallback)` or `except(SuccessCallback)`. Cancelling means the caller has stopped listening, and publishing to it anyway would contradict a contract the rest of the framework is built on and tests -- see the AI language and vision suites, which assert that a cancelled operation delivers neither a value nor an error even when the backend answers afterwards. Observers are the internal wake mechanism for `get()` and `waitFor()`; they are not the application's callbacks.

    One consequence worth knowing: cleanup wired through `onResult(AsyncResult)` does not run on cancellation either. Anything that must be released has to be released by whoever owns it. A per-operation timeout timer, for instance, survives until its deadline and then retires itself on finding the resource already done.

  - ### waitFor

    public void waitFor()
    Wait for loading to complete. If on EDT, this will use invokeAndBlock to safely block until loading is complete.

  - ### get

    public V get()

    Gets the resource synchronously. This will wait until either the resource failed with an exception, or the loading was canceled, or was done without error.

    If on edt, this uses invokeAndBlock to block safely.

    ###### Returns

    The wrapped resource.

    ###### Throws

    - `AsyncExecutionException`: if the resource failed with an error. To get the actual error, use `Throwable#getCause()`.

  - ### get

    public V get(int timeout) throws InterruptedException

    Gets the resource synchronously. This will wait until either the resource failed with an exception, or the loading was canceled, or was done without error.

    If on edt, this uses invokeAndBlock to block safely.

    ###### Parameters

    - `timeout`: Timeout

    ###### Returns

    The wrapped resource.

    ###### Throws

    - `AsyncExecutionException`: if the resource failed with an error. To get the actual error, use `Throwable#getCause()`.

    - `InterruptedException`: if timeout occurs.

    Throws:
      `InterruptedException`

  - ### get

    public V get(V defaultVal)

    Gets the resource if it is ready. If it is not ready, then it will simply return the provided defaultVal.

    ###### Parameters

    - `defaultVal`

    ###### Returns

    Either the resource value, or the provided default.

  - ### isCancelled

    public boolean isCancelled()
    Checks if the resource loading was cancelled.

  - ### isDone

    public boolean isDone()
    Checks if the resource loading is done. This will be true even if the resource loading failed with an error.

  - ### isReady

    public boolean isReady()
    Checks if the resource is ready.

  - ### ready

    public AsyncResource<V> ready(SuccessCallback<V> callback, EasyThread t)

    Runs the provided callback when the resource is ready.

    If an `EasyThread` is provided, then the callback will be run on that thread. If an EasyThread is not provided, and this call is made on the EDT, then the callback will be run on the EDT. Otherwise, the callback will occur on whatever thread the `#complete(java.lang.Object)` call is called on.

    ###### Parameters

    - `callback`: Callback to run when the resource is ready.

    - `t`: Optional EasyThread on which the callback should be run.

    ###### Returns

    Self for chaining

  - ### ready

    public AsyncResource<V> ready(SuccessCallback<V> callback)

    Runs the provided callback when the resource is ready.

    If this call is made on the EDT, then the callback will be run on the EDT. Otherwise, it will be run on whatever thread the complete() methdo is invoked on.

    ###### Parameters

    - `callback`: The callback to be run when the resource is ready.

    ###### Returns

    Self for chaining.

  - ### except

    public AsyncResource<V> except(SuccessCallback<Throwable> callback, EasyThread t)

    Sets callback to run if an error occurs.

    If an `EasyThread` is provided, then the callback will be run on that thread. If an EasyThread is not provided, and this call is made on the EDT, then the callback will be run on the EDT. Otherwise, the callback will occur on whatever thread the `#complete(java.lang.Object)` call is called on.

    ###### Parameters

    - `callback`: Callback to run on error.

    - `t`: Optional EasyThread to run callback on.

    ###### Returns

    Self for chaining.

  - ### except

    public AsyncResource<V> except(SuccessCallback<Throwable> callback)

    Sets callback to run if an error occurs. If this call is made on the EDT, then the callback will be run on the EDT. Otherwise it will be run on whatever thread the error() method is invoked on.

    ###### Parameters

    - `callback`: The callback to run in case of error.

  - ### complete

    public void complete(V value)

    Sets the resource value. This will trigger the ready callbacks to be run.

    ###### Parameters

    - `value`: The value to set for the resource.

  - ### error

    public void error(Throwable t)

    Sets the error for this resource in the case that it could not be loaded. This will trigger the error callbacks.

    ###### Parameters

    - `t`

  - ### await

    public void await() throws AsyncResource.AsyncExecutionException

    Waits and blocks until this AsyncResource is done.

    ###### Throws

    - `com.codename1.util.AsyncResource.AsyncExecutionException`
    Throws:
      `AsyncResource.AsyncExecutionException`

  - ### addListener

    public void addListener(AsyncResource<V> resource)

    Adds another AsyncResource as a listener to this async resource.

    ###### Parameters

    - `resource`

  - ### onResult

    public void onResult(AsyncResult<V> onResult)

    Combines ready() and except() into a single callback with 2 parameters.

    ###### Parameters

    - `onResult`: @param onResult A callback that handles both the ready() case and the except() case. Use `#isCancelled(java.lang.Throwable)` to test the error parameter of `java.lang.Throwable)` to see if if was caused by a cancellation.

  - ### asPromise

    public Promise<V> asPromise()

    Wraps this AsyncResource object as a `Promise`

    ###### Returns

    A Promise wrapping this AsyncResource.