com.triactive.jdo.util
Class WeakHashSet

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractSet
          com.triactive.jdo.util.WeakHashSet

All Implemented Interfaces:

java.util.Collection, java.util.Set

public class WeakHashSet

extends java.util.AbstractSet

implements java.util.Set

A Set implementation with weak elements. This class implements the Set interface, backed by a hash table with weak keys (actually a WeakHashMap instance). An element in a WeakHashSet will automatically be removed when it is no longer in ordinary use. More precisely, the presence of an element will not prevent it from being discarded by the garbage collector, that is, made finalizable, finalized, and then reclaimed. When a element has been discarded it is effectively removed from the set, so this class behaves somewhat differently than other Set implementations.

The null element is supported. This class has performance characteristics similar to those of the HashSet class, and has the same efficiency parameters of initial capacity and load factor.

Like most collection classes, this class is not synchronized. A synchronized WeakHashSet may be constructed using the Collections.synchronizedSet method.

This class is intended primarily for use with objects whose equals methods test for object identity using the == operator. Once such an object is discarded it can never be recreated, so it is impossible to do a lookup of that key in a WeakHashSet at some later time and be surprised that its entry has been removed. This class will work perfectly well with objects whose equals methods are not based upon object identity, such as String instances. With such recreatable objects however, the automatic removal of WeakHashSet elements that have been discarded may prove to be confusing.

The behavior of the WeakHashSet class depends in part upon the actions of the garbage collector, so several familiar (though not required) Set invariants do not hold for this class. Because the garbage collector may discard elements at any time, a WeakHashSet may behave as though an unknown thread is silently removing elements. In particular, even if you synchronize on a WeakHashSet instance and invoke none of its mutator methods, it is possible for the size method to return smaller values over time, for the isEmpty method to return false and then true, for the contains method to return true and later false for a given object, for the add method to return true and the remove method to return false for an element that previously appeared to be in the set, and for successive examinations of the set to yield successively smaller numbers of elements.

Each element in a WeakHashSet is stored indirectly as the referent of a weak reference. Therefore an element will automatically be removed only after the weak references to it, both inside and outside of the set, have been cleared by the garbage collector.

The iterators returned by this class are fail-fast: if the set is structurally modified at any time after the iterator is created, in any way except through the iterator's own remove or add methods, the iterator will throw a ConcurrentModificationException. Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

Note that the fail-fast behavior of an iterator cannot be guaranteed as it is, generally speaking, impossible to make any hard guarantees in the presence of unsynchronized concurrent modification. Fail-fast iterators throw ConcurrentModificationException on a best-effort basis. Therefore, it would be wrong to write a program that depended on this exception for its correctness: the fail-fast behavior of iterators should be used only to detect bugs.

Author:

Mike Martin (borrowing liberally from java.util.HashSet)

Constructor Summary

WeakHashSet()
Constructs a new, empty set; the backing WeakHashMap instance has default initial capacity (16) and load factor (0.75).

WeakHashSet(java.util.Collection c)
Constructs a new set containing the elements in the specified collection.

WeakHashSet(int initialCapacity)
Constructs a new, empty set; the backing WeakHashMap instance has the specified initial capacity and default load factor, which is 0.75.

WeakHashSet(int initialCapacity, float loadFactor)
Constructs a new, empty set; the backing WeakHashMap instance has the specified initial capacity and the specified load factor.

Method Summary

boolean	add(java.lang.Object o) Adds the specified element to the set if it is not already present.
void	clear() Removes all of the elements from the set.
boolean	contains(java.lang.Object o) Indicates whether the set contains the specified element.
boolean	isEmpty() Indicates whether the set is empty.
java.util.Iterator	iterator() Returns an iterator over the elements in this set.
boolean	remove(java.lang.Object o) Removes the specified element from the set if it is present.
int	size() Returns the number of elements in this set (its cardinality).

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Set

addAll, containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray

Constructor Detail

WeakHashSet

public WeakHashSet()

Constructs a new, empty set; the backing WeakHashMap instance has default initial capacity (16) and load factor (0.75).

WeakHashSet

public WeakHashSet(java.util.Collection c)

Constructs a new set containing the elements in the specified collection. The WeakHashMap is created with default load factor (0.75) and an initial capacity sufficient to contain the elements in the specified collection.

Parameters:

c - the collection whose elements are to be placed into this set.

Throws:

java.lang.NullPointerException - if the specified collection is null.

WeakHashSet

public WeakHashSet(int initialCapacity,
                   float loadFactor)

Constructs a new, empty set; the backing WeakHashMap instance has the specified initial capacity and the specified load factor.

Parameters:

initialCapacity - the initial capacity of the hash map.

loadFactor - the load factor of the hash map.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than zero, or if the load factor is nonpositive.

WeakHashSet

public WeakHashSet(int initialCapacity)

Constructs a new, empty set; the backing WeakHashMap instance has the specified initial capacity and default load factor, which is 0.75.

Parameters:

initialCapacity - the initial capacity of the hash table.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than zero.

Method Detail

iterator

public java.util.Iterator iterator()

Returns an iterator over the elements in this set. The elements are returned in no particular order.

Specified by:

iterator in interface java.util.Set

Returns:

an Iterator over the elements in this set.

See Also:

"java.util.ConcurrentModificationException"

size

public int size()

Returns the number of elements in this set (its cardinality).

Specified by:

size in interface java.util.Set

Returns:

the number of elements.

isEmpty

public boolean isEmpty()

Indicates whether the set is empty.

Specified by:

isEmpty in interface java.util.Set

Returns:

true if the set contains no elements.

contains

public boolean contains(java.lang.Object o)

Indicates whether the set contains the specified element.

Specified by:

contains in interface java.util.Set

Parameters:

o - the element to specify.

Returns:

true if the set contains the specified element.

add

public boolean add(java.lang.Object o)

Adds the specified element to the set if it is not already present.

Specified by:

add in interface java.util.Set

Parameters:

o - the element to be added.

Returns:

true if the set did not already contain the specified element.

remove

public boolean remove(java.lang.Object o)

Removes the specified element from the set if it is present.

Specified by:

remove in interface java.util.Set

Parameters:

o - the element to be removed.

Returns:

true if the set contained the specified element.

clear

public void clear()

Removes all of the elements from the set.

Specified by:

clear in interface java.util.Set