public class AsyncResource<V>

Object
Observable
AsyncResource

Known subtypesClassicDiscovery, BleScan, Oauth2.RefreshTokenRequest, AsyncMedia.PauseRequest, AsyncMedia.PlayRequest, BrowserWindow.EvalRequest, MessageEvent.PromptPromise

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 types

`class AsyncResource.AsyncExecutionException`	Exception to wrap exceptions that are thrown during asynchronous execution.
`class AsyncResource.CancellationException`	Exception thrown when the AsyncResource is cancelled.

Constructors

public AsyncResource()

Methods

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

Inherited methods

From Observable

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

From Object

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

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 Throwable: 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 AsyncResource<?>...: 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 Collection<AsyncResource<?>>: 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 Collection<AsyncResource<?>>: 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 AsyncResource<?>...: The resources to wait for.

Throws

AsyncResource.AsyncExecutionException

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Cancels loading the resource.

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 int: 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.

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.

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 SuccessCallback<V>: Callback to run when the resource is ready.
t EasyThread: 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 SuccessCallback<V>: 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.

Parameters

callback SuccessCallback<Throwable>: Callback to run on error.
t EasyThread: 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 SuccessCallback<Throwable>: 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 V: 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.

await

public void await()
throws AsyncResource.AsyncExecutionException

Waits and blocks until this AsyncResource is done.

Throws

com.codename1.util.AsyncResource.AsyncExecutionException

addListener

public void addListener(AsyncResource<V> resource)

Adds another AsyncResource as a listener to this async resource.

onResult

public void onResult(AsyncResult<V> onResult)

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

Parameters

onResult AsyncResult<V>: 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.