org.apache.river.concurrent

Class RC

java.lang.Object

org.apache.river.concurrent.RC

public class RC
extends Object

This class contains static methods for decorating collections with reference capability. Classes implementing Interfaces from the Java Collections Framework are supported. Freshly constructed empty collections are passed to these static methods as parameters and returned decorated with the desired reference capability. Referrer is an interface equivalent to Reference, as terms they are used interchangeably.

Referents in these collections may implement Comparable or a Comparator may be used for sorting. When Comparator's are utilised, they must first be encapsulated comparator(java.util.Comparator), before passing to a constructor for your preferred underlying Collection implementation.

Comparable is not supported for IDENTITY == referenced Collections, in this case a Comparator must be used.

All other references support Comparable, if the referent Object doesn't implement Comparable, then Object.hashCode() is used for sorting. If two referent Objects have identical hashCodes, but are unequal and do not implement Comparable, their references will also have identical hashCodes, so only one of the referents can be added to a SortedSet or SortedMap. This can be fixed by using a Comparator.

For all intents and purposes these utilities behave the same as your preferred underlying Collection implementation, with the exception of Reference reachability. An Object or Key,Value entry is removed from a Collection or Map, upon becoming eligible for garbage collection. The parameter gcCycle controls how often the underlying collection is cleaned of enqueued references. TIME references are collected after one gcCycle of no access, shorter cycle times will cause increased collection and removal of TIME based references, but have no effect on collection of soft or weak references, only the rate of removal of enqueued references.

Note that TIME based references with rapid gcCycle's will not scale well. Longer gcCycle's will scale.

Synchronisation must be implemented by the encapsulated Collection, removal of enqued references is performed by background Executor threads. Your chosen encapsulated Collection must also be mutable. Objects will be removed automatically from encapsulated Collections when they are eligible for garbage collection, object's that implement AutoCloseable will automatically have their resources freed after removal, external synchronisation of decorated collections is not supported.

If you're using Iterators, you must synchronise on the underlying Collection or Map, if iterating through keys or values, this doesn't apply to concurrent collections that are guaranteed not to throw a ConcurrentModificationException.

An Unmodifiable wrapper Collections.unmodifiableCollection(java.util.Collection) may be used externally to prevent additions to the underlying Collections, referents will still be removed as they become unreachable however.

Note that any Sub List, Sub Set or Sub Map obtained by any of the Java Collections Framework interfaces, must be views of the underlying Collection, if the Collection uses defensive copies instead of views, References could potentially remain in one copy after garbage collection, causing null returns. If using standard Java Collections Framework implementations, these problems don't occur as all Sub Lists, Sub Sets or Sub Maps are views only.

Map.entrySet() view instances returned preserve your chosen reference behaviour, they even support Set.add(java.lang.Object) or Set.addAll(java.util.Collection) methods, although you'll be hard pressed to find a standard java implementation that does. If you have a Map with a Set of Entry's implementing add, the implementation will need a Comparator, that compares Entry's only by their keys, to avoid duplicating keys, primarily because an Entry hashCode includes the both key and value in its calculation. Map.Entry.hashCode()

All other Map.entrySet() methods are fully implemented and supported.

Map.Entry view instances returned by these methods preserve reference behaviour, all methods are fully implemented and supported.

Set and it's sub interfaces SortedSet and NavigableSet, return views that preserve reference behaviour, all methods are fully implemented and supported.

Map and it's sub interfaces SortedMap, NavigableMap, ConcurrentMap and ConcurrentNavigableMap return views that preserve reference behaviour, all methods are fully implemented and supported.

List returns views that preserve reference behaviour, all methods are fully implemented and supported.

Queue and it's sub interfaces Deque, BlockingQueue and BlockingDeque return views that preserve reference behaviour, all methods are fully implemented and supported.

Iterator and ListIterator views preserve reference behaviour, all methods are fully implemented and supported.

RC stands for Referrer Collection and is abbreviated due to the length of generic parameter arguments typically required.

Author:

Peter Firmstone.

See Also:

Ref, Referrer, Reference

Method Summary

Modifier and Type	Method and Description
static <T> BlockingDeque<T>	blockingDeque(BlockingDeque<Referrer<T>> internal, Ref type, long gcCycle) Decorate a BlockingDeque for holding references so it appears as a BlockingDeque containing referents.
static <T> BlockingQueue<T>	blockingQueue(BlockingQueue<Referrer<T>> internal, Ref type, long gcCycle) Decorate a BlockingQueue for holding references so it appears as a BlockingQueue containing referents.
static <T> Collection<T>	collection(Collection<Referrer<T>> internal, Ref type, long gcCycle) Decorate a Collection for holding references so it appears as a Collection containing referents.
static <T> Comparator<Referrer<T>>	comparator(Comparator<? super T> comparator) When using a Comparator in SortedSet's and SortedMap's, the Comparator must be encapsulated using this method, to order the Set or Map by referents and not References.
static <K,V> ConcurrentMap<K,V>	concurrentMap(ConcurrentMap<Referrer<K>,Referrer<V>> internal, Ref key, Ref value, long gcKeyCycle, long gcValCycle) Decorate a ConcurrentMap for holding references so it appears as a ConcurrentMap containing referents.
static <K,V> ConcurrentNavigableMap<K,V>	concurrentNavigableMap(ConcurrentNavigableMap<Referrer<K>,Referrer<V>> internal, Ref key, Ref value, long gcKeyCycle, long gcValCycle) Decorate a ConcurrentNavigableMap for holding references so it appears as a ConcurrentNavigableMap containing referents.
static <T> Deque<T>	deque(Deque<Referrer<T>> internal, Ref type, long gcCycle) Decorate a Deque for holding references so it appears as a Deque containing referents.
static <T> List<T>	list(List<Referrer<T>> internal, Ref type, long gcCycle) Decorate a List for holding references so it appears as a List containing referents.
static <K,V> Map<K,V>	map(Map<Referrer<K>,Referrer<V>> internal, Ref key, Ref value, long gcKeyCycle, long gcValCycle) Decorate a Map for holding references so it appears as a Map containing referents.
static <K,V> NavigableMap<K,V>	navigableMap(NavigableMap<Referrer<K>,Referrer<V>> internal, Ref key, Ref value, long gcKeyCycle, long gcValCycle) Decorate a NavigableMap for holding Referrers so it appears as a NavigableMap containing referents.
static <T> NavigableSet<T>	navigableSet(NavigableSet<Referrer<T>> internal, Ref type, long gcCycle) Decorate a NavigableSet for holding references so it appears as a NavigableSet containing referents.
static <T> Queue<T>	queue(Queue<Referrer<T>> internal, Ref type, long gcCycle) Decorate a Queue for holding references so it appears as a Queue containing referents.
static <T> Set<T>	set(Set<Referrer<T>> internal, Ref type, long gcCycle) Decorate a Set for holding references so it appears as a Set containing referents.
static <K,V> SortedMap<K,V>	sortedMap(SortedMap<Referrer<K>,Referrer<V>> internal, Ref key, Ref value, long gcKeyCycle, long gcValCycle) Decorate a SortedMap for holding references so it appears as a SortedMap containing referents.
static <T> SortedSet<T>	sortedSet(SortedSet<Referrer<T>> internal, Ref type, long gcCycle) Decorate a SortedSet for holding references so it appears as a SortedSet containing referents.

Methods inherited from class java.lang.Object

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

Method Detail

comparator

public static <T> Comparator<Referrer<T>> comparator(Comparator<? super T> comparator)

When using a Comparator in SortedSet's and SortedMap's, the Comparator must be encapsulated using this method, to order the Set or Map by referents and not References.

Type Parameters:

T - referent type.

Parameters:

comparator - for referents.

Returns:

Decorated Comparator for Referrers

collection

public static <T> Collection<T> collection(Collection<Referrer<T>> internal,
                                           Ref type,
                                           long gcCycle)

Decorate a Collection for holding references so it appears as a Collection containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - Collection for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated Collection.

list

public static <T> List<T> list(List<Referrer<T>> internal,
                               Ref type,
                               long gcCycle)

Decorate a List for holding references so it appears as a List containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - List for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated List.

set

public static <T> Set<T> set(Set<Referrer<T>> internal,
                             Ref type,
                             long gcCycle)

Decorate a Set for holding references so it appears as a Set containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - Set for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated Set.

sortedSet

public static <T> SortedSet<T> sortedSet(SortedSet<Referrer<T>> internal,
                                         Ref type,
                                         long gcCycle)

Decorate a SortedSet for holding references so it appears as a SortedSet containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - SortedSet for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated SortedSet

navigableSet

public static <T> NavigableSet<T> navigableSet(NavigableSet<Referrer<T>> internal,
                                               Ref type,
                                               long gcCycle)

Decorate a NavigableSet for holding references so it appears as a NavigableSet containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - NavigableSet for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

NavigableSet<Referrer<T>> decorated as NavigableSet<T>

queue

public static <T> Queue<T> queue(Queue<Referrer<T>> internal,
                                 Ref type,
                                 long gcCycle)

Decorate a Queue for holding references so it appears as a Queue containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - Queue for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated Queue.

deque

public static <T> Deque<T> deque(Deque<Referrer<T>> internal,
                                 Ref type,
                                 long gcCycle)

Decorate a Deque for holding references so it appears as a Deque containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - Deque for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Deque<Referrer<T>> decorated as Deque<T>

blockingQueue

public static <T> BlockingQueue<T> blockingQueue(BlockingQueue<Referrer<T>> internal,
                                                 Ref type,
                                                 long gcCycle)

Decorate a BlockingQueue for holding references so it appears as a BlockingQueue containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - BlockingQueue for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated BlockingQueue

blockingDeque

public static <T> BlockingDeque<T> blockingDeque(BlockingDeque<Referrer<T>> internal,
                                                 Ref type,
                                                 long gcCycle)

Decorate a BlockingDeque for holding references so it appears as a BlockingDeque containing referents.

Type Parameters:

T - referent type.

Parameters:

internal - BlockingDeque for holding Referrer objects.

type - Referrer implementation required.

gcCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated BlockingDeque

map

public static <K,V> Map<K,V> map(Map<Referrer<K>,Referrer<V>> internal,
                                 Ref key,
                                 Ref value,
                                 long gcKeyCycle,
                                 long gcValCycle)

Decorate a Map for holding references so it appears as a Map containing referents.

Type Parameters:

K - key referent type

V - value referent type

Parameters:

internal - Map for holding Referrer objects

key - Referrer implementation required, as defined by Ref

value - Referrer implementation required, as defined by Ref

gcKeyCycle - scheduled cleaning task interval in milliseconds.

gcValCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated Map

sortedMap

public static <K,V> SortedMap<K,V> sortedMap(SortedMap<Referrer<K>,Referrer<V>> internal,
                                             Ref key,
                                             Ref value,
                                             long gcKeyCycle,
                                             long gcValCycle)

Decorate a SortedMap for holding references so it appears as a SortedMap containing referents.

Type Parameters:

K - key referent type

V - value referent type

Parameters:

internal - SortedMap for holding Referrer objects

key - Referrer implementation required, as defined by Ref

value - Referrer implementation required, as defined by Ref

gcKeyCycle - scheduled cleaning task interval in milliseconds.

gcValCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated SortedMap

navigableMap

public static <K,V> NavigableMap<K,V> navigableMap(NavigableMap<Referrer<K>,Referrer<V>> internal,
                                                   Ref key,
                                                   Ref value,
                                                   long gcKeyCycle,
                                                   long gcValCycle)

Decorate a NavigableMap for holding Referrers so it appears as a NavigableMap containing referents.

Type Parameters:

K - key referent type

V - value referent type

Parameters:

internal - NavigableMap for holding Referrer objects

key - Referrer implementation required, as defined by Ref

value - Referrer implementation required, as defined by Ref

gcKeyCycle - scheduled cleaning task interval in milliseconds.

gcValCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated NavigableMap

concurrentMap

public static <K,V> ConcurrentMap<K,V> concurrentMap(ConcurrentMap<Referrer<K>,Referrer<V>> internal,
                                                     Ref key,
                                                     Ref value,
                                                     long gcKeyCycle,
                                                     long gcValCycle)

Decorate a ConcurrentMap for holding references so it appears as a ConcurrentMap containing referents.

Type Parameters:

K - - key type.

V - - value type.

Parameters:

internal - - for holding references.

key - - key reference type.

value - - value reference type.

gcKeyCycle - scheduled cleaning task interval in milliseconds.

gcValCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated ConcurrentMap

concurrentNavigableMap

public static <K,V> ConcurrentNavigableMap<K,V> concurrentNavigableMap(ConcurrentNavigableMap<Referrer<K>,Referrer<V>> internal,
                                                                       Ref key,
                                                                       Ref value,
                                                                       long gcKeyCycle,
                                                                       long gcValCycle)

Decorate a ConcurrentNavigableMap for holding references so it appears as a ConcurrentNavigableMap containing referents.

Type Parameters:

K - key referent type

V - value referent type

Parameters:

internal - NavigableMap for holding Referrer objects

key - Referrer implementation required, as defined by Ref

value - Referrer implementation required, as defined by Ref

gcKeyCycle - scheduled cleaning task interval in milliseconds.

gcValCycle - scheduled cleaning task interval in milliseconds.

Returns:

Decorated ConcurrentNavigableMap