Implement a HashSet where the objects given are stored in weak references in Java

// w w  w  .  j a va 2  s.co  m
/*
 *     file: WeakHashSet.java
 *  package: oreilly.hcj.references
 *
 * This software is granted under the terms of the Common Public License,
 * CPL, which may be found at the following URL:
 * http://www-124.ibm.com/developerworks/oss/CPLv1.0.htm
 *
 * Copyright(c) 2003-2005 by the authors indicated in the @author tags.
 * All Rights are Reserved by the various authors.
 *
########## DO NOT EDIT ABOVE THIS LINE ########## */


import java.util.AbstractSet;
import java.util.Collection;
import java.util.Iterator;
import java.util.Set;
import java.util.WeakHashMap;

/**  
 * Implements a HashSet where the objects given are stored in weak references.
 * 
 * <p>
 * Uses the WeakHashMap class as a backing store to implement a set of objects that are
 * stored as weak references. All information concerning using keys in the WeakHashMap
 * class pertain to this class and it is reccomended that the user of this class review
 * that material before using the class.
 * </p>
 * 
 * <p>
 * Because this set contains only weak references, it is not serializable. If one tried
 * to serialize a weak reference, the results would be highly unpredictable as the
 * object could likely vanish from memory before the proces was even completed. Users of
 * this class must use transient when the containing class uses this set.
 * </p>
 * 
 * <p>
 * Because of the semantics of the weak references, the value null is not allowed in this
 * set.
 * </p>
 * 
 * <p>
 * This collection is not identity based but equality based. This can cause some
 * confusion as you cannot put in two objects whose <tt>equals()</tt> methods return
 * true. It also means that an object being held is not necessarily the same one that
 * the user is holding. For example, you could have a String with the value 'fred' at
 * memory location X and ther could be another String with the value 'fred' at memory
 * location Y. The first instance is in the set but the second isn't.
 * </p>
 *
 * @author <a href="mailto:worderisor@yahoo.com">Robert Simmons jr.</a>
 * @version $Revision: 1.8 $
 *
 * @see java.lang.util.WeakHashMap
 * @see java.lang.ref.WeakReference
 */
public class WeakHashSet extends AbstractSet implements Set {
  /** Dummy value used as a value object. */
  private static final Object DUMMY = new String("DUMMY");  //$NON-NLS-1$

  /** Holds the backing store. */
  WeakHashMap backingStore = new WeakHashMap();

  /** 
   * Constructs a new empty WeakHashSet with default values passed the the backing
   * store.
   *
   * @see java.util.WeakHashMap#WeakHashMap()
   */
  public WeakHashSet() {
    backingStore = new WeakHashMap();
  }

  /** 
   * Constructs a new WeakHashSet with default values passed the the backing store and
   * fills it with the given collection. Note that duplicates in the collection will
   * merely be overwritten
   *
   * @see java.util.WeakHashMap#WeakHashMap(Collection)
   */
  public WeakHashSet(final Collection c) {
    backingStore = new WeakHashMap(Math.max((int)(c.size() / .75f) + 1, 16));
    addAll(c);
  }

  /** 
   * Constructs a new WeakHashSet with the values given passed the the backing store.
   *
   * @see java.util.WeakHashMap#WeakHashMap(int, float)
   */
  public WeakHashSet(final int initialCapacity, final float loadFactor) {
    backingStore = new WeakHashMap(initialCapacity, loadFactor);
  }

  /** 
   * Constructs a new WeakHashSet with the values given passed the the backing store.
   *
   * @see java.util.WeakHashMap#WeakHashMap(int)
   */
  public WeakHashSet(final int initialCapacity) {
    backingStore = new WeakHashMap(initialCapacity);
  }

  /** 
   * {@inheritDoc}
   */
  public boolean isEmpty() {
    return backingStore.keySet()
                       .isEmpty();
  }

  /** 
   * {@inheritDoc}
   *
   * @throws NullPointerException If the user tries to add null to the set.
   */
  public boolean add(final Object o) {
    if (o == null) {
      throw new NullPointerException();
    }

    return backingStore.put(o, DUMMY) == null;
  }

  /** 
   * {@inheritDoc}
   *
   * @see #add(Object)
   */
  public boolean addAll(final Collection c) {
    boolean changed = false;
    Iterator iter = c.iterator();

    while (iter.hasNext()) {
      changed = (changed | (backingStore.put(iter.next(), DUMMY) != DUMMY));
    }

    return changed;
  }

  /** 
   * {@inheritDoc}
   */
  public void clear() {
    backingStore.clear();
  }

  /** 
   * {@inheritDoc}
   */
  public boolean contains(final Object o) {
    return backingStore.containsKey(o);
  }

  /** 
   * {@inheritDoc}
   */
  public boolean containsAll(final Collection c) {
    return backingStore.keySet()
                       .containsAll(c);
  }

  /** 
   * {@inheritDoc}
   */
  public boolean equals(final Object o) {
    return backingStore.equals(o);
  }

  /** 
   * Returns the hash code value for this set.
   * 
   * <p>
   * Gives back the hashCode for the backing store key set. The user should be aware,
   * however, that this hash code can change without user intervention as the objects
   * in the collection can easily be collected microseconds after completetion of the
   * method. It is not reccomended that the user rely on this hash code for
   * consistency
   * </p>
   *
   * @return The hashcode for this object.
   */
  public int hashCode() {
    return backingStore.keySet()
                       .hashCode();
  }

  /** 
   * Returns an iterator over the elements contained in this collection.
   * 
   * <p>
   * Note that this iterator is extremely volatile because the user may iterate over an
   * element in the set and find seconds later that it has been removed. This is
   * because of the semantics of weak references which act like a second thread is
   * silently modifying the collection. For this reason, it is advisable that if the
   * user wants to do something with the set that they maintain a strong reference to
   * the object and not rely on it being in the collection for them.
   * </p>
   * 
   * <p>
   * This iterator is fail fast and WeakReference transparrent. By this we mean that
   * the iterator simply ignores objects pending in the reference queue for cleanup.
   * </p>
   *
   * @return The iterator.
   */
  public Iterator iterator() {
    return backingStore.keySet()
                       .iterator();
  }

  /** 
   * {@inheritDoc}
   */
  public boolean remove(final Object o) {
    return backingStore.keySet()
                       .remove(o);
  }

  /** 
   * {@inheritDoc}
   */
  public boolean removeAll(final Collection c) {
    return backingStore.keySet()
                       .removeAll(c);
  }

  /** 
   * {@inheritDoc}
   */
  public boolean retainAll(final Collection c) {
    return backingStore.keySet()
                       .retainAll(c);
  }

  /** 
   * {@inheritDoc}
   */
  public int size() {
    return backingStore.keySet()
                       .size();
  }

  /** 
   * {@inheritDoc}
   */
  public Object[] toArray() {
    return backingStore.keySet()
                       .toArray();
  }

  /** 
   * {@inheritDoc}
   */
  public Object[] toArray(final Object[] a) {
    return backingStore.keySet()
                       .toArray(a);
  }

  /** 
   * {@inheritDoc}
   */
  public String toString() {
    return backingStore.keySet()
                       .toString();
  }

  /** 
   * {@inheritDoc}
   */
  protected Object clone() throws CloneNotSupportedException {
    throw new CloneNotSupportedException();
  }
}

/* ########## End of File ########## */