com.codename1.util

Class AsyncResource<V>

java.lang.Object

java.util.Observable

com.codename1.util.AsyncResource<V>

Direct Known Subclasses:

AsyncMedia.PauseRequest, AsyncMedia.PlayRequest, BrowserWindow.EvalRequest, 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.

Since:

7.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and 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 and Description
AsyncResource()

Method Summary

Modifier and Type	Method and 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 java.util.Observable

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

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncResource

public AsyncResource()

Method Detail

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.

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:

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

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

InterruptedException - if timeout occurs.

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.

Since:

7.0

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.

Returns:

isDone

public boolean isDone()

Checks if the resource loading is done. This will be true even if the resource loading failed with an error.

Returns:

isReady

public boolean isReady()

Checks if the resource is ready.

Returns:

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.

Returns:

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 -

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.

Since:

7.0

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.

Since:

7.0

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

Since:

7.0

await

public void await()
           throws AsyncResource.AsyncExecutionException

Waits and blocks until this AsyncResource is done.

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

Since:

7.0

addListener

public void addListener(AsyncResource<V> resource)

Adds another AsyncResource as a listener to this async resource.

Parameters:

resource -

Since:

7.0

onResult

public void onResult(AsyncResult<V> onResult)

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

Parameters:

onResult - A callback that handles both the ready() case and the except() case. Use isCancelled(java.lang.Throwable) to test the error parameter of AsyncResult.onReady(java.lang.Object, java.lang.Throwable) to see if if was caused by a cancellation.

Since:

7.0

asPromise

public Promise<V> asPromise()

Wraps this AsyncResource object as a Promise

Returns:

A Promise wrapping this AsyncResource.

Since:

8.0