Source for java.util.WeakHashMap

   1: /* WeakHashMap -- a hashtable that keeps only weak references
   2:    to its keys, allowing the virtual machine to reclaim them
   3:    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
   4: 
   5: This file is part of GNU Classpath.
   6: 
   7: GNU Classpath is free software; you can redistribute it and/or modify
   8: it under the terms of the GNU General Public License as published by
   9: the Free Software Foundation; either version 2, or (at your option)
  10: any later version.
  11: 
  12: GNU Classpath is distributed in the hope that it will be useful, but
  13: WITHOUT ANY WARRANTY; without even the implied warranty of
  14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15: General Public License for more details.
  16: 
  17: You should have received a copy of the GNU General Public License
  18: along with GNU Classpath; see the file COPYING.  If not, write to the
  19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 USA.
  21: 
  22: Linking this library statically or dynamically with other modules is
  23: making a combined work based on this library.  Thus, the terms and
  24: conditions of the GNU General Public License cover the whole
  25: combination.
  26: 
  27: As a special exception, the copyright holders of this library give you
  28: permission to link this library with independent modules to produce an
  29: executable, regardless of the license terms of these independent
  30: modules, and to copy and distribute the resulting executable under
  31: terms of your choice, provided that you also meet, for each linked
  32: independent module, the terms and conditions of the license of that
  33: module.  An independent module is a module which is not derived from
  34: or based on this library.  If you modify this library, you may extend
  35: this exception to your version of the library, but you are not
  36: obligated to do so.  If you do not wish to do so, delete this
  37: exception statement from your version. */
  38: 
  39: 
  40: package java.util;
  41: 
  42: import java.lang.ref.ReferenceQueue;
  43: import java.lang.ref.WeakReference;
  44: 
  45: /**
  46:  * A weak hash map has only weak references to the key. This means that it
  47:  * allows the key to be garbage collected if it is not used otherwise. If
  48:  * this happens, the entry will eventually disappear from the map,
  49:  * asynchronously.
  50:  *
  51:  * <p>A weak hash map makes most sense when the keys doesn't override the
  52:  * <code>equals</code> method: If there is no other reference to the
  53:  * key nobody can ever look up the key in this table and so the entry
  54:  * can be removed.  This table also works when the <code>equals</code>
  55:  * method is overloaded, such as String keys, but you should be prepared
  56:  * to deal with some entries disappearing spontaneously.
  57:  *
  58:  * <p>Other strange behaviors to be aware of: The size of this map may
  59:  * spontaneously shrink (even if you use a synchronized map and synchronize
  60:  * it); it behaves as if another thread removes entries from this table
  61:  * without synchronization.  The entry set returned by <code>entrySet</code>
  62:  * has similar phenomenons: The size may spontaneously shrink, or an
  63:  * entry, that was in the set before, suddenly disappears.
  64:  *
  65:  * <p>A weak hash map is not meant for caches; use a normal map, with
  66:  * soft references as values instead, or try {@link LinkedHashMap}.
  67:  *
  68:  * <p>The weak hash map supports null values and null keys.  The null key
  69:  * is never deleted from the map (except explictly of course). The
  70:  * performance of the methods are similar to that of a hash map.
  71:  *
  72:  * <p>The value objects are strongly referenced by this table.  So if a
  73:  * value object maintains a strong reference to the key (either direct
  74:  * or indirect) the key will never be removed from this map.  According
  75:  * to Sun, this problem may be fixed in a future release.  It is not
  76:  * possible to do it with the jdk 1.2 reference model, though.
  77:  *
  78:  * @author Jochen Hoenicke
  79:  * @author Eric Blake (ebb9@email.byu.edu)
  80:  *
  81:  * @see HashMap
  82:  * @see WeakReference
  83:  * @see LinkedHashMap
  84:  * @since 1.2
  85:  * @status updated to 1.4
  86:  */
  87: public class WeakHashMap extends AbstractMap implements Map
  88: {
  89:   // WARNING: WeakHashMap is a CORE class in the bootstrap cycle. See the
  90:   // comments in vm/reference/java/lang/Runtime for implications of this fact.
  91: 
  92:   /**
  93:    * The default capacity for an instance of HashMap.
  94:    * Sun's documentation mildly suggests that this (11) is the correct
  95:    * value.
  96:    */
  97:   private static final int DEFAULT_CAPACITY = 11;
  98: 
  99:   /**
 100:    * The default load factor of a HashMap.
 101:    */
 102:   private static final float DEFAULT_LOAD_FACTOR = 0.75F;
 103: 
 104:   /**
 105:    * This is used instead of the key value <i>null</i>.  It is needed
 106:    * to distinguish between an null key and a removed key.
 107:    */
 108:   // Package visible for use by nested classes.
 109:   static final Object NULL_KEY = new Object()
 110:   {
 111:     /**
 112:      * Sets the hashCode to 0, since that's what null would map to.
 113:      * @return the hash code 0
 114:      */
 115:     public int hashCode()
 116:     {
 117:       return 0;
 118:     }
 119: 
 120:     /**
 121:      * Compares this key to the given object. Normally, an object should
 122:      * NEVER compare equal to null, but since we don't publicize NULL_VALUE,
 123:      * it saves bytecode to do so here.
 124:      * @return true iff o is this or null
 125:      */
 126:     public boolean equals(Object o)
 127:     {
 128:       return null == o || this == o;
 129:     }
 130:   };
 131: 
 132:   /**
 133:    * The reference queue where our buckets (which are WeakReferences) are
 134:    * registered to.
 135:    */
 136:   private final ReferenceQueue queue;
 137: 
 138:   /**
 139:    * The number of entries in this hash map.
 140:    */
 141:   // Package visible for use by nested classes.
 142:   int size;
 143: 
 144:   /**
 145:    * The load factor of this WeakHashMap.  This is the maximum ratio of
 146:    * size versus number of buckets.  If size grows the number of buckets
 147:    * must grow, too.
 148:    */
 149:   private float loadFactor;
 150: 
 151:   /**
 152:    * The rounded product of the capacity (i.e. number of buckets) and
 153:    * the load factor. When the number of elements exceeds the
 154:    * threshold, the HashMap calls <code>rehash()</code>.
 155:    */
 156:   private int threshold;
 157: 
 158:   /**
 159:    * The number of structural modifications.  This is used by
 160:    * iterators, to see if they should fail.  This doesn't count
 161:    * the silent key removals, when a weak reference is cleared
 162:    * by the garbage collection.  Instead the iterators must make
 163:    * sure to have strong references to the entries they rely on.
 164:    */
 165:   // Package visible for use by nested classes.
 166:   int modCount;
 167: 
 168:   /**
 169:    * The entry set.  There is only one instance per hashmap, namely
 170:    * theEntrySet.  Note that the entry set may silently shrink, just
 171:    * like the WeakHashMap.
 172:    */
 173:   private final class WeakEntrySet extends AbstractSet
 174:   {
 175:     /**
 176:      * Non-private constructor to reduce bytecode emitted.
 177:      */
 178:     WeakEntrySet()
 179:     {
 180:     }
 181: 
 182:     /**
 183:      * Returns the size of this set.
 184:      *
 185:      * @return the set size
 186:      */
 187:     public int size()
 188:     {
 189:       return size;
 190:     }
 191: 
 192:     /**
 193:      * Returns an iterator for all entries.
 194:      *
 195:      * @return an Entry iterator
 196:      */
 197:     public Iterator iterator()
 198:     {
 199:       return new Iterator()
 200:       {
 201:         /**
 202:          * The entry that was returned by the last
 203:          * <code>next()</code> call.  This is also the entry whose
 204:          * bucket should be removed by the <code>remove</code> call. <br>
 205:          *
 206:          * It is null, if the <code>next</code> method wasn't
 207:          * called yet, or if the entry was already removed.  <br>
 208:          *
 209:          * Remembering this entry here will also prevent it from
 210:          * being removed under us, since the entry strongly refers
 211:          * to the key.
 212:          */
 213:         WeakBucket.WeakEntry lastEntry;
 214: 
 215:         /**
 216:          * The entry that will be returned by the next
 217:          * <code>next()</code> call.  It is <code>null</code> if there
 218:          * is no further entry. <br>
 219:          *
 220:          * Remembering this entry here will also prevent it from
 221:          * being removed under us, since the entry strongly refers
 222:          * to the key.
 223:          */
 224:         WeakBucket.WeakEntry nextEntry = findNext(null);
 225: 
 226:         /**
 227:          * The known number of modification to the list, if it differs
 228:          * from the real number, we throw an exception.
 229:          */
 230:         int knownMod = modCount;
 231: 
 232:         /**
 233:          * Check the known number of modification to the number of
 234:          * modifications of the table.  If it differs from the real
 235:          * number, we throw an exception.
 236:          * @throws ConcurrentModificationException if the number
 237:          *         of modifications doesn't match.
 238:          */
 239:         private void checkMod()
 240:         {
 241:           // This method will get inlined.
 242:           cleanQueue();
 243:           if (knownMod != modCount)
 244:             throw new ConcurrentModificationException();
 245:         }
 246: 
 247:         /**
 248:          * Get a strong reference to the next entry after
 249:          * lastBucket.
 250:          * @param lastEntry the previous bucket, or null if we should
 251:          * get the first entry.
 252:          * @return the next entry.
 253:          */
 254:         private WeakBucket.WeakEntry findNext(WeakBucket.WeakEntry lastEntry)
 255:         {
 256:           int slot;
 257:           WeakBucket nextBucket;
 258:           if (lastEntry != null)
 259:             {
 260:               nextBucket = lastEntry.getBucket().next;
 261:               slot = lastEntry.getBucket().slot;
 262:             }
 263:           else
 264:             {
 265:               nextBucket = buckets[0];
 266:               slot = 0;
 267:             }
 268: 
 269:           while (true)
 270:             {
 271:               while (nextBucket != null)
 272:                 {
 273:                   WeakBucket.WeakEntry entry = nextBucket.getEntry();
 274:                   if (entry != null)
 275:                     // This is the next entry.
 276:                     return entry;
 277: 
 278:                   // Entry was cleared, try next.
 279:                   nextBucket = nextBucket.next;
 280:                 }
 281: 
 282:               slot++;
 283:               if (slot == buckets.length)
 284:                 // No more buckets, we are through.
 285:                 return null;
 286: 
 287:               nextBucket = buckets[slot];
 288:             }
 289:         }
 290: 
 291:         /**
 292:          * Checks if there are more entries.
 293:          * @return true, iff there are more elements.
 294:          * @throws ConcurrentModificationException if the hash map was
 295:          *         modified.
 296:          */
 297:         public boolean hasNext()
 298:         {
 299:           checkMod();
 300:           return nextEntry != null;
 301:         }
 302: 
 303:         /**
 304:          * Returns the next entry.
 305:          * @return the next entry.
 306:          * @throws ConcurrentModificationException if the hash map was
 307:          *         modified.
 308:          * @throws NoSuchElementException if there is no entry.
 309:          */
 310:         public Object next()
 311:         {
 312:           checkMod();
 313:           if (nextEntry == null)
 314:             throw new NoSuchElementException();
 315:           lastEntry = nextEntry;
 316:           nextEntry = findNext(lastEntry);
 317:           return lastEntry;
 318:         }
 319: 
 320:         /**
 321:          * Removes the last returned entry from this set.  This will
 322:          * also remove the bucket of the underlying weak hash map.
 323:          * @throws ConcurrentModificationException if the hash map was
 324:          *         modified.
 325:          * @throws IllegalStateException if <code>next()</code> was
 326:          *         never called or the element was already removed.
 327:          */
 328:         public void remove()
 329:         {
 330:           checkMod();
 331:           if (lastEntry == null)
 332:             throw new IllegalStateException();
 333:           modCount++;
 334:           internalRemove(lastEntry.getBucket());
 335:           lastEntry = null;
 336:           knownMod++;
 337:         }
 338:       };
 339:     }
 340:   }
 341: 
 342:   /**
 343:    * A bucket is a weak reference to the key, that contains a strong
 344:    * reference to the value, a pointer to the next bucket and its slot
 345:    * number. <br>
 346:    *
 347:    * It would be cleaner to have a WeakReference as field, instead of
 348:    * extending it, but if a weak reference gets cleared, we only get
 349:    * the weak reference (by queue.poll) and wouldn't know where to
 350:    * look for this reference in the hashtable, to remove that entry.
 351:    *
 352:    * @author Jochen Hoenicke
 353:    */
 354:   private static class WeakBucket extends WeakReference
 355:   {
 356:     /**
 357:      * The value of this entry.  The key is stored in the weak
 358:      * reference that we extend.
 359:      */
 360:     Object value;
 361: 
 362:     /**
 363:      * The next bucket describing another entry that uses the same
 364:      * slot.
 365:      */
 366:     WeakBucket next;
 367: 
 368:     /**
 369:      * The slot of this entry. This should be
 370:      * <code>Math.abs(key.hashCode() % buckets.length)</code>.
 371:      *
 372:      * But since the key may be silently removed we have to remember
 373:      * the slot number.
 374:      *
 375:      * If this bucket was removed the slot is -1.  This marker will
 376:      * prevent the bucket from being removed twice.
 377:      */
 378:     int slot;
 379: 
 380:     /**
 381:      * Creates a new bucket for the given key/value pair and the specified
 382:      * slot.
 383:      * @param key the key
 384:      * @param queue the queue the weak reference belongs to
 385:      * @param value the value
 386:      * @param slot the slot.  This must match the slot where this bucket
 387:      *        will be enqueued.
 388:      */
 389:     public WeakBucket(Object key, ReferenceQueue queue, Object value,
 390:                       int slot)
 391:     {
 392:       super(key, queue);
 393:       this.value = value;
 394:       this.slot = slot;
 395:     }
 396: 
 397:     /**
 398:      * This class gives the <code>Entry</code> representation of the
 399:      * current bucket.  It also keeps a strong reference to the
 400:      * key; bad things may happen otherwise.
 401:      */
 402:     class WeakEntry implements Map.Entry
 403:     {
 404:       /**
 405:        * The strong ref to the key.
 406:        */
 407:       Object key;
 408: 
 409:       /**
 410:        * Creates a new entry for the key.
 411:        * @param key the key
 412:        */
 413:       public WeakEntry(Object key)
 414:       {
 415:         this.key = key;
 416:       }
 417: 
 418:       /**
 419:        * Returns the underlying bucket.
 420:        * @return the owning bucket
 421:        */
 422:       public WeakBucket getBucket()
 423:       {
 424:         return WeakBucket.this;
 425:       }
 426: 
 427:       /**
 428:        * Returns the key.
 429:        * @return the key
 430:        */
 431:       public Object getKey()
 432:       {
 433:         return key == NULL_KEY ? null : key;
 434:       }
 435: 
 436:       /**
 437:        * Returns the value.
 438:        * @return the value
 439:        */
 440:       public Object getValue()
 441:       {
 442:         return value;
 443:       }
 444: 
 445:       /**
 446:        * This changes the value.  This change takes place in
 447:        * the underlying hash map.
 448:        * @param newVal the new value
 449:        * @return the old value
 450:        */
 451:       public Object setValue(Object newVal)
 452:       {
 453:         Object oldVal = value;
 454:         value = newVal;
 455:         return oldVal;
 456:       }
 457: 
 458:       /**
 459:        * The hashCode as specified in the Entry interface.
 460:        * @return the hash code
 461:        */
 462:       public int hashCode()
 463:       {
 464:         return key.hashCode() ^ WeakHashMap.hashCode(value);
 465:       }
 466: 
 467:       /**
 468:        * The equals method as specified in the Entry interface.
 469:        * @param o the object to compare to
 470:        * @return true iff o represents the same key/value pair
 471:        */
 472:       public boolean equals(Object o)
 473:       {
 474:         if (o instanceof Map.Entry)
 475:           {
 476:             Map.Entry e = (Map.Entry) o;
 477:             return key.equals(e.getKey())
 478:               && WeakHashMap.equals(value, e.getValue());
 479:           }
 480:         return false;
 481:       }
 482: 
 483:       public String toString()
 484:       {
 485:         return key + "=" + value;
 486:       }
 487:     }
 488: 
 489:     /**
 490:      * This returns the entry stored in this bucket, or null, if the
 491:      * bucket got cleared in the mean time.
 492:      * @return the Entry for this bucket, if it exists
 493:      */
 494:     WeakEntry getEntry()
 495:     {
 496:       final Object key = this.get();
 497:       if (key == null)
 498:         return null;
 499:       return new WeakEntry(key);
 500:     }
 501:   }
 502: 
 503:   /**
 504:    * The entry set returned by <code>entrySet()</code>.
 505:    */
 506:   private final WeakEntrySet theEntrySet;
 507: 
 508:   /**
 509:    * The hash buckets.  These are linked lists. Package visible for use in
 510:    * nested classes.
 511:    */
 512:   WeakBucket[] buckets;
 513: 
 514:   /**
 515:    * Creates a new weak hash map with default load factor and default
 516:    * capacity.
 517:    */
 518:   public WeakHashMap()
 519:   {
 520:     this(DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR);
 521:   }
 522: 
 523:   /**
 524:    * Creates a new weak hash map with default load factor and the given
 525:    * capacity.
 526:    * @param initialCapacity the initial capacity
 527:    * @throws IllegalArgumentException if initialCapacity is negative
 528:    */
 529:   public WeakHashMap(int initialCapacity)
 530:   {
 531:     this(initialCapacity, DEFAULT_LOAD_FACTOR);
 532:   }
 533: 
 534:   /**
 535:    * Creates a new weak hash map with the given initial capacity and
 536:    * load factor.
 537:    * @param initialCapacity the initial capacity.
 538:    * @param loadFactor the load factor (see class description of HashMap).
 539:    * @throws IllegalArgumentException if initialCapacity is negative, or
 540:    *         loadFactor is non-positive
 541:    */
 542:   public WeakHashMap(int initialCapacity, float loadFactor)
 543:   {
 544:     // Check loadFactor for NaN as well.
 545:     if (initialCapacity < 0 || ! (loadFactor > 0))
 546:       throw new IllegalArgumentException();
 547:     if (initialCapacity == 0)
 548:       initialCapacity = 1;
 549:     this.loadFactor = loadFactor;
 550:     threshold = (int) (initialCapacity * loadFactor);
 551:     theEntrySet = new WeakEntrySet();
 552:     queue = new ReferenceQueue();
 553:     buckets = new WeakBucket[initialCapacity];
 554:   }
 555: 
 556:   /**
 557:    * Construct a new WeakHashMap with the same mappings as the given map.
 558:    * The WeakHashMap has a default load factor of 0.75.
 559:    *
 560:    * @param m the map to copy
 561:    * @throws NullPointerException if m is null
 562:    * @since 1.3
 563:    */
 564:   public WeakHashMap(Map m)
 565:   {
 566:     this(m.size(), DEFAULT_LOAD_FACTOR);
 567:     putAll(m);
 568:   }
 569: 
 570:   /**
 571:    * Simply hashes a non-null Object to its array index.
 572:    * @param key the key to hash
 573:    * @return its slot number
 574:    */
 575:   private int hash(Object key)
 576:   {
 577:     return Math.abs(key.hashCode() % buckets.length);
 578:   }
 579: 
 580:   /**
 581:    * Cleans the reference queue.  This will poll all references (which
 582:    * are WeakBuckets) from the queue and remove them from this map.
 583:    * This will not change modCount, even if it modifies the map.  The
 584:    * iterators have to make sure that nothing bad happens.  <br>
 585:    *
 586:    * Currently the iterator maintains a strong reference to the key, so
 587:    * that is no problem.
 588:    */
 589:   // Package visible for use by nested classes.
 590:   void cleanQueue()
 591:   {
 592:     Object bucket = queue.poll();
 593:     while (bucket != null)
 594:       {
 595:         internalRemove((WeakBucket) bucket);
 596:         bucket = queue.poll();
 597:       }
 598:   }
 599: 
 600:   /**
 601:    * Rehashes this hashtable.  This will be called by the
 602:    * <code>add()</code> method if the size grows beyond the threshold.
 603:    * It will grow the bucket size at least by factor two and allocates
 604:    * new buckets.
 605:    */
 606:   private void rehash()
 607:   {
 608:     WeakBucket[] oldBuckets = buckets;
 609:     int newsize = buckets.length * 2 + 1; // XXX should be prime.
 610:     threshold = (int) (newsize * loadFactor);
 611:     buckets = new WeakBucket[newsize];
 612: 
 613:     // Now we have to insert the buckets again.
 614:     for (int i = 0; i < oldBuckets.length; i++)
 615:       {
 616:         WeakBucket bucket = oldBuckets[i];
 617:         WeakBucket nextBucket;
 618:         while (bucket != null)
 619:           {
 620:             nextBucket = bucket.next;
 621: 
 622:             Object key = bucket.get();
 623:             if (key == null)
 624:               {
 625:                 // This bucket should be removed; it is probably
 626:                 // already on the reference queue.  We don't insert it
 627:                 // at all, and mark it as cleared.
 628:                 bucket.slot = -1;
 629:                 size--;
 630:               }
 631:             else
 632:               {
 633:                 // Add this bucket to its new slot.
 634:                 int slot = hash(key);
 635:                 bucket.slot = slot;
 636:                 bucket.next = buckets[slot];
 637:                 buckets[slot] = bucket;
 638:               }
 639:             bucket = nextBucket;
 640:           }
 641:       }
 642:   }
 643: 
 644:   /**
 645:    * Finds the entry corresponding to key.  Since it returns an Entry
 646:    * it will also prevent the key from being removed under us.
 647:    * @param key the key, may be null
 648:    * @return The WeakBucket.WeakEntry or null, if the key wasn't found.
 649:    */
 650:   private WeakBucket.WeakEntry internalGet(Object key)
 651:   {
 652:     if (key == null)
 653:       key = NULL_KEY;
 654:     int slot = hash(key);
 655:     WeakBucket bucket = buckets[slot];
 656:     while (bucket != null)
 657:       {
 658:         WeakBucket.WeakEntry entry = bucket.getEntry();
 659:         if (entry != null && key.equals(entry.key))
 660:           return entry;
 661: 
 662:         bucket = bucket.next;
 663:       }
 664:     return null;
 665:   }
 666: 
 667:   /**
 668:    * Adds a new key/value pair to the hash map.
 669:    * @param key the key. This mustn't exists in the map. It may be null.
 670:    * @param value the value.
 671:    */
 672:   private void internalAdd(Object key, Object value)
 673:   {
 674:     if (key == null)
 675:       key = NULL_KEY;
 676:     int slot = hash(key);
 677:     WeakBucket bucket = new WeakBucket(key, queue, value, slot);
 678:     bucket.next = buckets[slot];
 679:     buckets[slot] = bucket;
 680:     size++;
 681:   }
 682: 
 683:   /**
 684:    * Removes a bucket from this hash map, if it wasn't removed before
 685:    * (e.g. one time through rehashing and one time through reference queue).
 686:    * Package visible for use in nested classes.
 687:    *
 688:    * @param bucket the bucket to remove.
 689:    */
 690:   void internalRemove(WeakBucket bucket)
 691:   {
 692:     int slot = bucket.slot;
 693:     if (slot == -1)
 694:       // This bucket was already removed.
 695:       return;
 696: 
 697:     // Mark the bucket as removed.  This is necessary, since the
 698:     // bucket may be enqueued later by the garbage collection, and
 699:     // internalRemove will be called a second time.
 700:     bucket.slot = -1;
 701:     if (buckets[slot] == bucket)
 702:       buckets[slot] = bucket.next;
 703:     else
 704:       {
 705:         WeakBucket prev = buckets[slot];
 706:         /* This may throw a NullPointerException.  It shouldn't but if
 707:          * a race condition occurred (two threads removing the same
 708:          * bucket at the same time) it may happen.  <br>
 709:          * But with race condition many much worse things may happen
 710:          * anyway.
 711:          */
 712:         while (prev.next != bucket)
 713:           prev = prev.next;
 714:         prev.next = bucket.next;
 715:       }
 716:     size--;
 717:   }
 718: 
 719:   /**
 720:    * Returns the size of this hash map.  Note that the size() may shrink
 721:    * spontaneously, if the some of the keys were only weakly reachable.
 722:    * @return the number of entries in this hash map.
 723:    */
 724:   public int size()
 725:   {
 726:     cleanQueue();
 727:     return size;
 728:   }
 729: 
 730:   /**
 731:    * Tells if the map is empty.  Note that the result may change
 732:    * spontanously, if all of the keys were only weakly reachable.
 733:    * @return true, iff the map is empty.
 734:    */
 735:   public boolean isEmpty()
 736:   {
 737:     cleanQueue();
 738:     return size == 0;
 739:   }
 740: 
 741:   /**
 742:    * Tells if the map contains the given key.  Note that the result
 743:    * may change spontanously, if the key was only weakly
 744:    * reachable.
 745:    * @param key the key to look for
 746:    * @return true, iff the map contains an entry for the given key.
 747:    */
 748:   public boolean containsKey(Object key)
 749:   {
 750:     cleanQueue();
 751:     return internalGet(key) != null;
 752:   }
 753: 
 754:   /**
 755:    * Gets the value the key is mapped to.
 756:    * @return the value the key was mapped to.  It returns null if
 757:    *         the key wasn't in this map, or if the mapped value was
 758:    *         explicitly set to null.
 759:    */
 760:   public Object get(Object key)
 761:   {
 762:     cleanQueue();
 763:     WeakBucket.WeakEntry entry = internalGet(key);
 764:     return entry == null ? null : entry.getValue();
 765:   }
 766: 
 767:   /**
 768:    * Adds a new key/value mapping to this map.
 769:    * @param key the key, may be null
 770:    * @param value the value, may be null
 771:    * @return the value the key was mapped to previously.  It returns
 772:    *         null if the key wasn't in this map, or if the mapped value
 773:    *         was explicitly set to null.
 774:    */
 775:   public Object put(Object key, Object value)
 776:   {
 777:     cleanQueue();
 778:     WeakBucket.WeakEntry entry = internalGet(key);
 779:     if (entry != null)
 780:       return entry.setValue(value);
 781: 
 782:     modCount++;
 783:     if (size >= threshold)
 784:       rehash();
 785: 
 786:     internalAdd(key, value);
 787:     return null;
 788:   }
 789: 
 790:   /**
 791:    * Removes the key and the corresponding value from this map.
 792:    * @param key the key. This may be null.
 793:    * @return the value the key was mapped to previously.  It returns
 794:    *         null if the key wasn't in this map, or if the mapped value was
 795:    *         explicitly set to null.
 796:    */
 797:   public Object remove(Object key)
 798:   {
 799:     cleanQueue();
 800:     WeakBucket.WeakEntry entry = internalGet(key);
 801:     if (entry == null)
 802:       return null;
 803: 
 804:     modCount++;
 805:     internalRemove(entry.getBucket());
 806:     return entry.getValue();
 807:   }
 808: 
 809:   /**
 810:    * Returns a set representation of the entries in this map.  This
 811:    * set will not have strong references to the keys, so they can be
 812:    * silently removed.  The returned set has therefore the same
 813:    * strange behaviour (shrinking size(), disappearing entries) as
 814:    * this weak hash map.
 815:    * @return a set representation of the entries.
 816:    */
 817:   public Set entrySet()
 818:   {
 819:     cleanQueue();
 820:     return theEntrySet;
 821:   }
 822: 
 823:   /**
 824:    * Clears all entries from this map.
 825:    */
 826:   public void clear()
 827:   {
 828:     super.clear();
 829:   }
 830: 
 831:   /**
 832:    * Returns true if the map contains at least one key which points to
 833:    * the specified object as a value.  Note that the result
 834:    * may change spontanously, if its key was only weakly reachable.
 835:    * @param value the value to search for
 836:    * @return true if it is found in the set.
 837:    */
 838:   public boolean containsValue(Object value)
 839:   {
 840:     cleanQueue();
 841:     return super.containsValue(value);
 842:   }
 843: 
 844:   /**
 845:    * Returns a set representation of the keys in this map.  This
 846:    * set will not have strong references to the keys, so they can be
 847:    * silently removed.  The returned set has therefore the same
 848:    * strange behaviour (shrinking size(), disappearing entries) as
 849:    * this weak hash map.
 850:    * @return a set representation of the keys.
 851:    */
 852:   public Set keySet()
 853:   {
 854:     cleanQueue();
 855:     return super.keySet();
 856:   }
 857: 
 858:   /**
 859:    * Puts all of the mappings from the given map into this one. If the
 860:    * key already exists in this map, its value is replaced.
 861:    * @param m the map to copy in
 862:    */
 863:   public void putAll(Map m)
 864:   {
 865:     super.putAll(m);
 866:   }
 867: 
 868:   /**
 869:    * Returns a collection representation of the values in this map.  This
 870:    * collection will not have strong references to the keys, so mappings
 871:    * can be silently removed.  The returned collection has therefore the same
 872:    * strange behaviour (shrinking size(), disappearing entries) as
 873:    * this weak hash map.
 874:    * @return a collection representation of the values.
 875:    */
 876:   public Collection values()
 877:   {
 878:     cleanQueue();
 879:     return super.values();
 880:   }
 881: } // class WeakHashMap