org.geotools.util

Class CanonicalSet<E>

Object

AbstractCollection<E>

AbstractSet<E>

WeakHashSet<E>

CanonicalSet<E>

Type Parameters:

E - The type of elements in the set.

All Implemented Interfaces:

Iterable<E>, Collection<E>, Set<E>, CheckedCollection<E>

public class CanonicalSet<E>
extends WeakHashSet<E>

A canonical set of objects, used to optimize memory use. The operation of this set is similar in spirit to the String.intern() method. The following example shows a convenient way to use CanonicalSet as an internal pool of immutable objects.

 public Foo create(String definition) {
      Foo created = new Foo(definition);
      return (Foo) canonicalSet.unique(created);
 }
 

The CanonicalSet has a get(T) method that is not part of the Set interface. This get method retrieves an entry from this set that is equals to the supplied object. The unique(T) method combines a get followed by a put operation if the specified object was not in the set.

The set of objects is held by weak references as explained in WeakHashSet. The CanonicalSet class is thread-safe.

Since:

2.4

Author:

Martin Desruisseaux (IRD), Jody Garnett

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CanonicalSet(Class<E> type) Constructs a CanonicalSet for elements of the specified type.

Method Summary

Modifier and Type	Method and Description
<T extends E> T	get(T object) Returns an object equals to the specified object, if present.
static <E> CanonicalSet<E>	newInstance(Class<E> type) Constructs a CanonicalSet for elements of the specified type.
<T extends E> T	unique(T object) Returns an object equals to object if such an object already exist in this CanonicalSet.
void	uniques(E... objects) Iteratively call unique(Object) for an array of objects.

Methods inherited from class WeakHashSet

add, clear, contains, getElementType, iterator, remove, size, toArray

Methods inherited from class AbstractSet

equals, hashCode, removeAll

Methods inherited from class AbstractCollection

addAll, containsAll, isEmpty, retainAll, toArray, toString

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface Collection

addAll, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray

Methods inherited from interface Iterable

forEach

Methods inherited from interface Set

addAll, containsAll, isEmpty, retainAll, spliterator, toArray

Constructor Detail

CanonicalSet

protected CanonicalSet(Class<E> type)

Constructs a CanonicalSet for elements of the specified type.

Parameters:

type - The type of elements in the set.

Since:

2.5

Method Detail

newInstance

public static <E> CanonicalSet<E> newInstance(Class<E> type)

Constructs a CanonicalSet for elements of the specified type.

Type Parameters:

E - The type of elements in the set.

Parameters:

type - The type of elements in the set.

Returns:

An initially empty set for elements of the given type.

Since:

2.5

get

public <T extends E> T get(T object)

Returns an object equals to the specified object, if present. If this set doesn't contains any object equals to object, then this method returns null.

Type Parameters:

T - The type of the element to get.

Parameters:

object - The element to get.

Returns:

An element equals to the given one if already presents in the set, or null otherwise.

See Also:

unique(Object)

unique

public <T extends E> T unique(T object)

Returns an object equals to object if such an object already exist in this CanonicalSet. Otherwise, adds object to this CanonicalSet. This method is equivalents to the following code:

 if (object != null) {
     Object current = get(object);
     if (current != null) {
         return current;
     } else {
         add(object);
     }
 }
 return object;
 

Type Parameters:

T - The type of the element to get.

Parameters:

object - The element to get or to add in the set if not already presents.

Returns:

An element equals to the given one if already presents in the set, or the given object otherwise.

uniques

@SafeVarargs
public final void uniques(E... objects)

Iteratively call unique(Object) for an array of objects. This method is equivalents to the following code:

 for (int i=0; i<objects.length; i++) {
     objects[i] = unique(objects[i]);
 }
 

Parameters:

objects - On input, the objects to add to this set if not already present. On output, elements that are equal, but where every reference to an instance already presents in this set has been replaced by a reference to the existing instance.