org.apache.river.concurrent

Enum Ref

java.lang.Object

java.lang.Enum<Ref>

org.apache.river.concurrent.Ref

All Implemented Interfaces:

Serializable, Comparable<Ref>

public enum Ref
extends Enum<Ref>

Ref enum represents types of references available for use in java collection framework implementations.

Only use STRONG, WEAK_IDENTITY and TIME based references as keys in Maps, use of other reference types should be discouraged due to unpredictable results, when for example, an equal WEAK Reference Key disappears due to garbage collection, or SOFT reference keys aren't garbage collected as expected.

Map implementations delete their key -> value mapping when either the key or value References become unreachable. ConcurrentMap's will retry until putIfAbsent is successful when an existing Referrer key is cleared.

Only use STRONG and TIME based references in Queue's, other types break Queue's contract, null has special meaning, a cleared reference returns null.

Object.toString() is overridden in reference implementations to call toString() on the referent, if still reachable, otherwise the reference calls the superclass toString() method, where the superclass is a java Reference subclass. Consideration is being given to returning a null string "" instead, if you feel strongly about this, please contact the author.

Phantom references are not used, they are designed to replace Object.finalize() and remain unreachable, but not garbage collected until the PhantomReference also becomes unreachable, get() always returns null.

TIME and SOFT and SOFT_IDENTITY references update their access timestamp, when Referrer.get(), Referrer.equals() or Referrer.toString() is called. SOFT and SOFT_IDENTITY do so lazily and are not guaranteed to succeed in updating the access time. SOFT references also update their access timestamp when either Referrer.hashCode() or Comparable.compareTo() is called.

For sets and map keys that require traversal using a Comparator or Comparable, access times will be updated during each traversal. In these circumstances, SOFT and SOFT_IDENTITY references are typically not enqueued and do not behave as expected.

SOFT references are only suited for use in lists or as values in maps and not suitable for keys in hash or tree maps.

TIME references only update their access timestamp during traversal when a Comparator or Comparable returns zero (a successful match), or when equals is true. TIME references are suitable for use as keys in tree and hash based maps as well as sets and tasks in Queues. In fact TIME is the only referrer suitable for use in Queue's and their subtypes. Tasks in a Queue, if timed out, are first cancelled, then removed, they are not cleared as doing so could cause a null poll() return when a queue is not empty, which would violate the contract for Queue.

SOFT_IDENTITY references are suitable for use as keys in hash tables, hash maps and hash sets, since hashCode() does not update the access timestamp, while equals() does. SOFT_IDENTITY references are not recommended for use in tree maps, tree sets or queues.

Author:

Peter Firmstone.

See Also:

Reference, WeakReference, SoftReference, PhantomReference, Comparable

Enum Constant Summary

Enum Constants

Enum Constant and Description
SOFT SOFT References implement equals based on equality of the referent objects, while the referent is still reachable.
SOFT_IDENTITY SOFT_IDENTY References implement equals based on identity == of the referent objects.
STRONG STRONG References implement equals and hashCode() based on the equality of the underlying Object.
TIME TIME References implement equals based on equality of the referent objects.
WEAK WEAK References implement equals based on equality of the referent objects, while the referent is still reachable.
WEAK_IDENTITY WEAK_IDENTY References implement equals based on identity == of the referent objects.

Method Summary

Modifier and Type	Method and Description
static Ref	valueOf(String name) Returns the enum constant of this type with the specified name.
static Ref[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

TIME

public static final Ref TIME

TIME References implement equals based on equality of the referent objects. Time references are STRONG references that are removed after a period of no access, even if they are strongly referenced outside the cache, they are removed. TIME references don't rely on Garbage Collection algorithms.

TIME References support cancellation of tasks implementing Future, when the reference times out, if it contains a Future, it is cancelled.

A call to equals(), get() or toString(), will cause the timestamp on the reference to be updated, whereas hashCode() will not, in addition, Comparators and referents that implement Comparable, only update the timestamp if they return 0. This allows referents to be inspected without update when they don't match.

TIME References require synchronisation for iteration, so during cleaning periods, a synchronised Collection or Map will be locked. A lock is still obtained for iterating over Concurrent Maps and Collections, however this does not normally synchronise access between threads, only other cleaning task threads.

See Also:

Future

SOFT

public static final Ref SOFT

SOFT References implement equals based on equality of the referent objects, while the referent is still reachable. The hashCode implementation is based on the referent implementation of hashCode, while the referent is reachable.

SOFT References implement Comparable allowing the referent Objects to be compared if they implement Comparable. If the referent Object doesn't implement Comparable, the hashCode's of the Reference is compared instead. If the referent Objects don't implement Comparable, then they shouldn't really be used in sorted collections.

Garbage collection must be the same as SoftReference.

See Also:

SoftReference, WeakReference, Comparable

SOFT_IDENTITY

public static final Ref SOFT_IDENTITY

SOFT_IDENTY References implement equals based on identity == of the referent objects.

Garbage collection must be the same as SoftReference.

See Also:

SoftReference

WEAK

public static final Ref WEAK

WEAK References implement equals based on equality of the referent objects, while the referent is still reachable. The hashCode implementation is based on the referent implementation of hashCode, while the referent is reachable.

WEAK References implement comparable allowing the referent Objects to be compared if they implement Comparable. If the referent Object doesn't implement Comparable, the hashCode's of the Reference is compared instead. If the referent Object's don't implement Comparable, then they shouldn't really be used in sorted collections.

Garbage collection must be the same as WeakReference.

See Also:

WeakReference, Comparable

WEAK_IDENTITY

public static final Ref WEAK_IDENTITY

WEAK_IDENTY References implement equals based on identity == of the referent objects.

Garbage collection must be the same as WeakReference.

See Also:

WeakReference

STRONG

public static final Ref STRONG

STRONG References implement equals and hashCode() based on the equality of the underlying Object.

STRONG References implement Comparable allowing the referent Objects to be compared if they implement Comparable. If the referent Object doesn't implement Comparable, the hashCode's of the Reference is compared instead. If the referent Object's don't implement Comparable, then they shouldn't really be used in sorted collections.

Garbage collection doesn't occur unless the Reference is cleared.

See Also:

Comparable

Method Detail

values

public static Ref[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Ref c : Ref.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Ref valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null