Holger's Java API

## 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>>`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads