com.antelmann.util
Class ReferenceHolder<T>

java.lang.Object
  com.antelmann.util.ReferenceHolder<T>

All Implemented Interfaces:

Refreshable, ValueRetriever<T>, Wrapped<ValueRetriever<T>>

Direct Known Subclasses:

SoftHolder, WeakHolder

public abstract class ReferenceHolder<T>
extends Object
implements ValueRetriever<T>, Wrapped<ValueRetriever<T>>, Refreshable

useful to easily cache a large value 'softly' or 'weakly' through a ValueRetriever using a Reference. If the reference is garbage collected, the value is re-retrieved via the embedded ValueRetriever.

Since:

29.05.2011, 19:33:41

Author:

Holger Antelmann

Constructor Summary

protected

ReferenceHolder(com.antelmann.util.ReferenceHolder.Kind kind, ValueRetriever<T> retriever)

Method Summary

boolean	clear() releases the instance and returns true only if it was previously held in memory.
T	getRelevantValue() if the value is still cached via the embedded reference, it is returned; otherwise it is re-retrieved (and again cached).
T	getValue() returns getRelevantValue() but wraps occurring exceptions into RuntimeExceptions (convenience method)
boolean	isAvailable() returns true only if the reference is currently cached
boolean	isWired()
void	refreshContent() refreshes the embedded content
void	setCurrentValue(T value) allows to manually set the value independent of the embedded retriever.
void	setRetriever(ValueRetriever<T> retriever)
void	setWired(boolean flag) allows to 'hold' the value in memory, so that it won't be garbage-collected and not re-retrieved until unwired.
ValueRetriever<T>	unwrap() returns the embedded instance that this wrapper encloses

Methods inherited from class java.lang.Object

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

Constructor Detail

ReferenceHolder

protected ReferenceHolder(com.antelmann.util.ReferenceHolder.Kind kind,
                          ValueRetriever<T> retriever)

Method Detail

setRetriever

public void setRetriever(ValueRetriever<T> retriever)

isAvailable

public boolean isAvailable()

returns true only if the reference is currently cached

isWired

public boolean isWired()

setWired

public void setWired(boolean flag)

allows to 'hold' the value in memory, so that it won't be garbage-collected and not re-retrieved until unwired. So, if the instance is wired, it is not so 'soft'/'weak' anymore, which kind of takes away the original purpose of this class. A potential use for this is to prevent the potentially expensive call to the retriever for a limited series of operations while ensuring that there is still only one instance of the value in memory for different callers.

clear

@Warning(value="using this method may result in having multiple instance of the retrieved value in memory if the value was held im memory elsewhere")
public boolean clear()

releases the instance and returns true only if it was previously held in memory. Note that if true is returned, the released instance itself may still be wired in memory (held by whomever still has a reference to it). If that reference is held while getRelevantValue() is called again, you may end up with more than one instance of the retrieved value in memory. Note that calling this method also 'unwires' the content for this instance.

Returns:

true only if the data was actually cleared

See Also:

setWired(boolean)

refreshContent

public void refreshContent()
                    throws IOException

Description copied from interface: Refreshable

refreshes the embedded content

Specified by:

refreshContent in interface Refreshable

Throws:

IOException - if the refresh failed

getValue

public T getValue()
           throws RuntimeException

returns getRelevantValue() but wraps occurring exceptions into RuntimeExceptions (convenience method)

Throws:

RuntimeException

getRelevantValue

public T getRelevantValue()
                   throws IOException

if the value is still cached via the embedded reference, it is returned; otherwise it is re-retrieved (and again cached).

Specified by:

getRelevantValue in interface ValueRetriever<T>

Throws:

IOException - if any resource to fulfill the request is not accessible

setCurrentValue

public void setCurrentValue(T value)

allows to manually set the value independent of the embedded retriever. There is no guarantee, however, that the given value is then returned by getRelevantValue(), unless the caller ensures that the value may not be garbage-collected through keeping a hard link to its value.

See Also:

setWired(boolean)

unwrap

public ValueRetriever<T> unwrap()

Description copied from interface: Wrapped

returns the embedded instance that this wrapper encloses

Specified by:

unwrap in interface Wrapped<ValueRetriever<T>>