io.atlassian.util.concurrent

Class ResettableLazyReference<T>

java.lang.Object

io.atlassian.util.concurrent.ResettableLazyReference<T>

Type Parameters:

T - the type of the contained element.

All Implemented Interfaces:

Supplier<T>

@ThreadSafe
public abstract class ResettableLazyReference<T>
extends Object
implements Supplier<T>

Lazily loaded reference that is not constructed until required. This class is used to maintain a reference to an object that is expensive to create, but may need to be reset and recomputed at a later time. Object creation is guaranteed to be thread-safe and the first thread that calls get() will be the one that creates it.

Usage: clients need to implement the create() method to return the object this reference will hold.

For instance:

 final ResettableLazyReference<MyObject> ref = new ResettableLazyReference() {
   protected MyObject create() throws Exception {
     // Do expensive object construction here
     return new MyObject();
   }
 };
 

Then call get() to get a reference to the referenced object:

 MyObject myLazyLoadedObject = ref.get()
 

NOTE: Interruption policy is that if you want to be cancellable while waiting for another thread to create the value, instead of calling get() call getInterruptibly(). However, If your create() method is interrupted and throws an InterruptedException, it is treated as an application exception and will be the causal exception inside the runtime LazyReference.InitializationException that get() or getInterruptibly() throws and your create() will not be called again.

Constructor Summary

Constructors

Constructor and Description
ResettableLazyReference()

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancel the initializing operation if it has not already run.
protected abstract T	create() The object factory method, guaranteed to be called once and only once.
T	get() Get the lazily loaded reference in a non-cancellable manner.
T	getInterruptibly() Get the lazily loaded reference in a cancellable manner.
boolean	isInitialized() Has the create() reference been initialized.
protected void	onReset(LazyReference<T> oldValue) Template extension method for providing custom reset behavior.
void	reset() Reset the internal reference.
LazyReference<T>	resets() Reset the internal reference and returns a LazyReference of the old value.

Methods inherited from class java.lang.Object

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

Constructor Detail

ResettableLazyReference

public ResettableLazyReference()

Method Detail

create

protected abstract T create()
                     throws Exception

The object factory method, guaranteed to be called once and only once.

Returns:

the object that get() and getInterruptibly() will return.

Throws:

Exception - if anything goes wrong, rethrown as an Initializationjava.lang.Exception from get() and getInterruptibly()

get

public final T get()

Get the lazily loaded reference in a non-cancellable manner. If your create() method throws an Exception calls to get() will throw an InitializationException which wraps the previously thrown exception.

Specified by:

get in interface Supplier<T>

Returns:

the object that create() created.

Throws:

LazyReference.InitializationException - if the create() method throws an exception. The Throwable.getCause() will contain the exception thrown by the create() method

getInterruptibly

public final T getInterruptibly()
                         throws InterruptedException

Get the lazily loaded reference in a cancellable manner. If your create() method throws an Exception, calls to get() will throw a RuntimeException which wraps the previously thrown exception.

Returns:

the object that create() created.

Throws:

LazyReference.InitializationException - if the create() method throws an exception. The Throwable.getCause() will contain the exception thrown by the create() method

InterruptedException - If the calling thread is Interrupted while waiting for another thread to create the value (if the creating thread is interrupted while blocking on something, the InterruptedException will be thrown as the causal exception of the LazyReference.InitializationException to everybody calling this method).

reset

public final void reset()

Reset the internal reference. Anyone currently in the process of calling get() will still force that and receive the old reference. Note: this method was made final in 3.0. Override onReset(LazyReference) to implement custom reset behavior.

resets

public final LazyReference<T> resets()

Reset the internal reference and returns a LazyReference of the old value. Anyone currently in the process of calling get() will still force that and receive the old reference however.

Returns:

A lazy reference of the old value that may or may not already be initialized. Calling the supplier may block and cause the initialization to occur.

onReset

protected void onReset(LazyReference<T> oldValue)

Template extension method for providing custom reset behavior.

Parameters:

oldValue - the old LazyReference, guaranteed that nobody else has access to it anymore.

Since:

2.6

isInitialized

public final boolean isInitialized()

Has the create() reference been initialized.

Returns:

true if the task is complete and has not been reset.

cancel

public final void cancel()

Cancel the initializing operation if it has not already run. Will try and interrupt if it is currently running.