Package org.apache.sis.util.collection

## Class WeakHashSet<E>

- Object
- - AbstractCollection<E>
  - - AbstractSet<E>
    - - WeakHashSet<E>

- Type Parameters:
    `E` - the type of elements in the set.
  All Implemented Interfaces:
    `Iterable<E>`, `Collection<E>`, `Set<E>`, `CheckedContainer<E>`

      public class WeakHashSet<E>
      extends AbstractSet<E>
      implements CheckedContainer<E>

  A set of objects hold by weak references. An entry in a `WeakHashSet` will automatically be removed when it is no longer in ordinary use. More precisely, the presence of an entry will not prevent the entry from being discarded by the garbage collector, that is, made finalizable, finalized, and then reclaimed. When an entry has been discarded it is effectively removed from the set, so this class behaves somewhat differently than other `Set` implementations.

  If the elements stored in this set are arrays like `int[]`, `float[]` or `Object[]`, then the hash code computations and the comparisons are performed using the static `hashCode(a)` and `equals(a1, a2)` methods defined in the `Arrays` class.

  Optimizing memory use in factory implementations
  The `WeakHashSet` class has a `get(Object)` 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(Object)` method combines a `get` followed by a `add` operation if the specified object was not in the set. This is similar in spirit to the `String​.intern()` method. The following example shows a convenient way to use `WeakHashSet` as an internal pool of immutable objects:

  >     private final WeakHashSet<Foo> pool = new WeakHashSet<Foo>(Foo.class);

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

  Thus, `WeakHashSet` can be used inside a factory to prevent creating duplicate immutable objects.
  Thread safety
  The same `WeakHashSet` instance can be safely used by many threads without synchronization on the part of the caller. But if a sequence of two or more method calls need to appear atomic from other threads perspective, then the caller can synchronize on `this`.
  Since:
    0.3
  See Also:
    `WeakHashMap`

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `WeakHashSet​(Class<E> type)` | Creates a `WeakHashSet` for elements of the specified type.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `add​(E element)` | Adds the specified element to this set if it is not already present.
    `void` | `clear()` | Removes all of the elements from this set.
    `boolean` | `contains​(Object element)` | Returns `true` if this set contains the specified element.
    `E` | `get​(Object element)` | Returns an object equals to the specified object, if present.
    `Class<E>` | `getElementType()` | Returns the type of elements in this set.
    `Iterator<E>` | `iterator()` | Returns an iterator over the elements contained in this collection.
    `boolean` | `remove​(Object element)` | Removes a single instance of the specified element from this set, if it is present Null values are considered never present.
    `int` | `size()` | Returns the count of element in this set.
    `E[]` | `toArray()` | Returns a view of this set as an array.
    `<T extends E> T` | `unique​(T element)` | Returns an object equals to `element` if such an object already exist in this `WeakHashSet`.

    - ### 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

    - #### WeakHashSet

          public WeakHashSet​(Class<E> type)

      Creates a `WeakHashSet` for elements of the specified type.
      Parameters:
        `type` - the type of the element to be included in this set.

  - ### Method Detail

    - #### getElementType

          public Class<E> getElementType()

      Returns the type of elements in this set.
      Specified by:
        `getElementType` in interface `CheckedContainer<E>`
      Returns:
        the element type.

    - #### size

          public int size()

      Returns the count of element in this set.
      Specified by:
        `size` in interface `Collection<E>`
      Specified by:
        `size` in interface `Set<E>`
      Specified by:
        `size` in class `AbstractCollection<E>`
      Returns:
        number of elements in this set.

    - #### add

          public boolean add​(E element)
                      throws NullArgumentException

      Adds the specified element to this set if it is not already present. If this set already contains the specified element, the call leaves this set unchanged and returns `false`.
      Specified by:
        `add` in interface `Collection<E>`
      Specified by:
        `add` in interface `Set<E>`
      Overrides:
        `add` in class `AbstractCollection<E>`
      Parameters:
        `element` - element to be added to this set.
      Returns:
        `true` if this set did not already contain the specified element.
      Throws:
        `NullArgumentException` - if the given object is `null`.

    - #### remove

          public boolean remove​(Object element)

      Removes a single instance of the specified element from this set, if it is present Null values are considered never present.
      Specified by:
        `remove` in interface `Collection<E>`
      Specified by:
        `remove` in interface `Set<E>`
      Overrides:
        `remove` in class `AbstractCollection<E>`
      Parameters:
        `element` - element to be removed from this set, if present. Can be `null`.
      Returns:
        `true` if the set contained the specified element.

    - #### get

          public E get​(Object element)

      Returns an object equals to the specified object, if present. If this set doesn't contain any object equals to `element`, then this method returns `null`. Null values are considered never present.
      Parameters:
        `element` - 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)`

    - #### contains

          public boolean contains​(Object element)

      Returns `true` if this set contains the specified element. Null values are considered never present.
      Specified by:
        `contains` in interface `Collection<E>`
      Specified by:
        `contains` in interface `Set<E>`
      Overrides:
        `contains` in class `AbstractCollection<E>`
      Parameters:
        `element` - object to be checked for containment in this set. Can be `null`.
      Returns:
        `true` if this set contains the specified element.

    - #### unique

          public <T extends E> T unique​(T element)

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

      >     if (element != null) {
      >         T current = get(element);
      >         if (current != null) {
      >             return current;
      >         } else {
      >             add(element);
      >         }
      >     }
      >     return element;

      Type Parameters:
        `T` - the type of the element to get. Can be `null`.
      Parameters:
        `element` - the element to get or to add in the set if not already presents, or `null` if the given element was null.
      Returns:
        an element equals to the given one if already presents in the set, or the given `object` otherwise.

    - #### clear

          public void clear()

      Removes all of the elements from this set.
      Specified by:
        `clear` in interface `Collection<E>`
      Specified by:
        `clear` in interface `Set<E>`
      Overrides:
        `clear` in class `AbstractCollection<E>`

    - #### toArray

          public E[] toArray()

      Returns a view of this set as an array. Elements will be in an arbitrary order. Note that this array contains strong references. Consequently, no object reclamation will occur as long as a reference to this array is hold.
      Specified by:
        `toArray` in interface `Collection<E>`
      Specified by:
        `toArray` in interface `Set<E>`
      Overrides:
        `toArray` in class `AbstractCollection<E>`
      Returns:
        all elements in this set.

    - #### iterator

          public Iterator<E> iterator()

      Returns an iterator over the elements contained in this collection. No element from this set will be garbage collected as long as a reference to the iterator is hold.
      Specified by:
        `iterator` in interface `Collection<E>`
      Specified by:
        `iterator` in interface `Iterable<E>`
      Specified by:
        `iterator` in interface `Set<E>`
      Specified by:
        `iterator` in class `AbstractCollection<E>`
      Returns:
        an iterator over all elements in this set.