Class 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 Description
      protected CanonicalSet​(Class<E> type)
      Constructs a CanonicalSet for elements of the specified type.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 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

        parallelStream, removeIf, 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.