KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > oreilly > hcj > references > WeakHashSet


1 /*
2  * file: WeakHashSet.java
3  * package: oreilly.hcj.references
4  *
5  * This software is granted under the terms of the Common Public License,
6  * CPL, which may be found at the following URL:
7  * http://www-124.ibm.com/developerworks/oss/CPLv1.0.htm
8  *
9  * Copyright(c) 2003-2005 by the authors indicated in the @author tags.
10  * All Rights are Reserved by the various authors.
11  *
12 ########## DO NOT EDIT ABOVE THIS LINE ########## */
13
14 package oreilly.hcj.references;
15
16 import java.util.AbstractSet JavaDoc;
17 import java.util.Collection JavaDoc;
18 import java.util.Iterator JavaDoc;
19 import java.util.Set JavaDoc;
20 import java.util.WeakHashMap JavaDoc;
21
22 /**
23  * Implements a HashSet where the objects given are stored in weak references.
24  *
25  * <p>
26  * Uses the WeakHashMap class as a backing store to implement a set of objects that are
27  * stored as weak references. All information concerning using keys in the WeakHashMap
28  * class pertain to this class and it is reccomended that the user of this class review
29  * that material before using the class.
30  * </p>
31  *
32  * <p>
33  * Because this set contains only weak references, it is not serializable. If one tried
34  * to serialize a weak reference, the results would be highly unpredictable as the
35  * object could likely vanish from memory before the proces was even completed. Users of
36  * this class must use transient when the containing class uses this set.
37  * </p>
38  *
39  * <p>
40  * Because of the semantics of the weak references, the value null is not allowed in this
41  * set.
42  * </p>
43  *
44  * <p>
45  * This collection is not identity based but equality based. This can cause some
46  * confusion as you cannot put in two objects whose <tt>equals()</tt> methods return
47  * true. It also means that an object being held is not necessarily the same one that
48  * the user is holding. For example, you could have a String with the value 'fred' at
49  * memory location X and ther could be another String with the value 'fred' at memory
50  * location Y. The first instance is in the set but the second isn't.
51  * </p>
52  *
53  * @author <a HREF="mailto:worderisor@yahoo.com">Robert Simmons jr.</a>
54  * @version $Revision: 1.1 $
55  *
56  * @see java.lang.util.WeakHashMap
57  * @see java.lang.ref.WeakReference
58  */
59 public class WeakHashSet extends AbstractSet JavaDoc implements Set JavaDoc {
60     /** Dummy value used as a value object. */
61     private static final Object JavaDoc DUMMY = new String JavaDoc("DUMMY"); //$NON-NLS-1$
62
63     /** Holds the backing store. */
64     WeakHashMap JavaDoc backingStore = new WeakHashMap JavaDoc();
65
66     /**
67      * Constructs a new empty WeakHashSet with default values passed the the backing
68      * store.
69      *
70      * @see java.util.WeakHashMap#WeakHashMap()
71      */
72     public WeakHashSet() {
73         backingStore = new WeakHashMap JavaDoc();
74     }
75
76     /**
77      * Constructs a new WeakHashSet with default values passed the the backing store and
78      * fills it with the given collection. Note that duplicates in the collection will
79      * merely be overwritten
80      *
81      * @see java.util.WeakHashMap#WeakHashMap(Collection)
82      */
83     public WeakHashSet(final Collection JavaDoc c) {
84         backingStore = new WeakHashMap JavaDoc(Math.max((int)(c.size() / .75f) + 1, 16));
85         addAll(c);
86     }
87
88     /**
89      * Constructs a new WeakHashSet with the values given passed the the backing store.
90      *
91      * @see java.util.WeakHashMap#WeakHashMap(int, float)
92      */
93     public WeakHashSet(final int initialCapacity, final float loadFactor) {
94         backingStore = new WeakHashMap JavaDoc(initialCapacity, loadFactor);
95     }
96
97     /**
98      * Constructs a new WeakHashSet with the values given passed the the backing store.
99      *
100      * @see java.util.WeakHashMap#WeakHashMap(int)
101      */
102     public WeakHashSet(final int initialCapacity) {
103         backingStore = new WeakHashMap JavaDoc(initialCapacity);
104     }
105
106     /**
107      * {@inheritDoc}
108      */
109     public boolean isEmpty() {
110         return backingStore.keySet()
111                            .isEmpty();
112     }
113
114     /**
115      * {@inheritDoc}
116      *
117      * @throws NullPointerException If the user tries to add null to the set.
118      */
119     public boolean add(final Object JavaDoc o) {
120         if (o == null) {
121             throw new NullPointerException JavaDoc();
122         }
123
124         return backingStore.put(o, DUMMY) == null;
125     }
126
127     /**
128      * {@inheritDoc}
129      *
130      * @see #add(Object)
131      */
132     public boolean addAll(final Collection JavaDoc c) {
133         boolean changed = false;
134         Iterator JavaDoc iter = c.iterator();
135
136         while (iter.hasNext()) {
137             changed = (changed | (backingStore.put(iter.next(), DUMMY) != DUMMY));
138         }
139
140         return changed;
141     }
142
143     /**
144      * {@inheritDoc}
145      */
146     public void clear() {
147         backingStore.clear();
148     }
149
150     /**
151      * {@inheritDoc}
152      */
153     public boolean contains(final Object JavaDoc o) {
154         return backingStore.containsKey(o);
155     }
156
157     /**
158      * {@inheritDoc}
159      */
160     public boolean containsAll(final Collection JavaDoc c) {
161         return backingStore.keySet()
162                            .containsAll(c);
163     }
164
165     /**
166      * {@inheritDoc}
167      */
168     public boolean equals(final Object JavaDoc o) {
169         return backingStore.equals(o);
170     }
171
172     /**
173      * Returns the hash code value for this set.
174      *
175      * <p>
176      * Gives back the hashCode for the backing store key set. The user should be aware,
177      * however, that this hash code can change without user intervention as the objects
178      * in the collection can easily be collected microseconds after completetion of the
179      * method. It is not reccomended that the user rely on this hash code for
180      * consistency
181      * </p>
182      *
183      * @return The hashcode for this object.
184      */
185     public int hashCode() {
186         return backingStore.keySet()
187                            .hashCode();
188     }
189
190     /**
191      * Returns an iterator over the elements contained in this collection.
192      *
193      * <p>
194      * Note that this iterator is extremely volatile because the user may iterate over an
195      * element in the set and find seconds later that it has been removed. This is
196      * because of the semantics of weak references which act like a second thread is
197      * silently modifying the collection. For this reason, it is advisable that if the
198      * user wants to do something with the set that they maintain a strong reference to
199      * the object and not rely on it being in the collection for them.
200      * </p>
201      *
202      * <p>
203      * This iterator is fail fast and WeakReference transparrent. By this we mean that
204      * the iterator simply ignores objects pending in the reference queue for cleanup.
205      * </p>
206      *
207      * @return The iterator.
208      */
209     public Iterator JavaDoc iterator() {
210         return backingStore.keySet()
211                            .iterator();
212     }
213
214     /**
215      * {@inheritDoc}
216      */
217     public boolean remove(final Object JavaDoc o) {
218         return backingStore.keySet()
219                            .remove(o);
220     }
221
222     /**
223      * {@inheritDoc}
224      */
225     public boolean removeAll(final Collection JavaDoc c) {
226         return backingStore.keySet()
227                            .removeAll(c);
228     }
229
230     /**
231      * {@inheritDoc}
232      */
233     public boolean retainAll(final Collection JavaDoc c) {
234         return backingStore.keySet()
235                            .retainAll(c);
236     }
237
238     /**
239      * {@inheritDoc}
240      */
241     public int size() {
242         return backingStore.keySet()
243                            .size();
244     }
245
246     /**
247      * {@inheritDoc}
248      */
249     public Object JavaDoc[] toArray() {
250         return backingStore.keySet()
251                            .toArray();
252     }
253
254     /**
255      * {@inheritDoc}
256      */
257     public Object JavaDoc[] toArray(final Object JavaDoc[] a) {
258         return backingStore.keySet()
259                            .toArray(a);
260     }
261
262     /**
263      * {@inheritDoc}
264      */
265     public String JavaDoc toString() {
266         return backingStore.keySet()
267                            .toString();
268     }
269
270     /**
271      * {@inheritDoc}
272      */
273     protected Object JavaDoc clone() throws CloneNotSupportedException JavaDoc {
274         throw new CloneNotSupportedException JavaDoc();
275     }
276 }
277
278 /* ########## End of File ########## */
279
Popular Tags