|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.lang.ref.Reference<T>
java.lang.ref.WeakReference<T>
com.atlassian.util.concurrent.LazyReference<T>
@ThreadSafe public abstract class LazyReference<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 and
must be constructed once and once only. This reference behaves as though the
final
keyword has been used (you cannot reset it once it has
been constructed). 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 LazyReference<MyObject> ref = new LazyReference() { 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.
Implementation note. This class extends WeakReference
as
Reference
does not have a public constructor. WeakReference is
preferable as it does not have any members and therefore doesn't increase the
memory footprint. As we never pass a referent through to the super-class and
override get()
, the garbage collection semantics of WeakReference
are irrelevant. The referenced object will not become eligible for GC unless
the object holding the reference to this object is collectible.
Nested Class Summary | |
---|---|
static class |
LazyReference.InitializationException
If the factory create() method threw an exception,
this wraps it. |
Constructor Summary | |
---|---|
LazyReference()
|
Method Summary | |
---|---|
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. |
Methods inherited from class java.lang.ref.Reference |
---|
clear, enqueue, isEnqueued |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public LazyReference()
Method Detail |
---|
protected abstract T create() throws java.lang.Exception
get()
and getInterruptibly()
will return.
LazyReference.InitializationException
- if anything goes wrong, rethrown as an
InitializationException from get()
and
getInterruptibly()
java.lang.Exception
public final T get()
create()
method throws an Exception calls to
get()
will throw an InitializationException which wraps the
previously thrown exception.
get
in interface Supplier<T>
get
in class java.lang.ref.Reference<T>
create()
created.
LazyReference.InitializationException
- if the create()
method throws an
exception. The Throwable.getCause()
will contain
the exception thrown by the create()
methodpublic final T getInterruptibly() throws java.lang.InterruptedException
create()
method throws an Exception, calls to
get()
will throw a RuntimeException which wraps the
previously thrown exception.
create()
created.
LazyReference.InitializationException
- if the create()
method throws an
exception. The Throwable.getCause()
will contain
the exception thrown by the create()
method
java.lang.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).public boolean isInitialized()
create()
reference been initialized.
public void cancel()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |