org.geotools.util
Class CanonicalSet<E>

Object
  extended by AbstractCollection<E>
      extended by AbstractSet<E>
          extended by WeakHashSet<E>
              extended by 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
  CanonicalSet()
          Deprecated. Use newInstance(java.lang.Class) instead.
protected CanonicalSet(Class<E> type)
          Constructs a CanonicalSet for elements of the specified type.
 
Method Summary
<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, removeAll, retainAll, toArray
 
Methods inherited from interface Set
addAll, containsAll, isEmpty, retainAll, toArray
 

Constructor Detail

CanonicalSet

public CanonicalSet()
Deprecated. Use newInstance(java.lang.Class) instead.

Constructs a CanonicalSet.


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

public 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.


Copyright © 1996-2014 Geotools. All Rights Reserved.