ridljar/com/sun/star/lib/util/WeakMap.java

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: WeakMap.java,v $
  10  * $Revision: 1.4 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 package com.sun.star.lib.util;
  32
  33 import java.lang.ref.ReferenceQueue;
  34 import java.lang.ref.WeakReference;
  35 import java.util.Collection;
  36 import java.util.HashMap;
  37 import java.util.Iterator;
  38 import java.util.Map;
  39 import java.util.Set;
  40
  41 /**
  42  * A hash map that holds values of type <code>WeakReference</code>.
  43  *
  44  * <p>Like <code>HashMap</code>, this implementation provides all of the
  45  * optional map operations, and permits the <code>null</code> key.</p>
  46  *
  47  * <p>Also like <code>HashMap</code>, this implementation is not synchronized.
  48  * If multiple threads share an instance, and at least one of them executes any
  49  * modifying operations on the <code>WeakMap</code>, they have to use external
  50  * synchronization.</p>
  51  *
  52  * <p>Unlike other map implementations, <code>WeakMap</code> is asymmetric in
  53  * that <code>put</code> expects the given value to be a plain object that is
  54  * then wrapped in a <code>WeakReference</code>, while the occurences of values
  55  * in all other methods (<code>containsValue</code>, <code>entrySet</code>,
  56  * <code>equals</code>, <code>get</code>, <code>hashCode</code>,
  57  * <code>remove</code>, <code>values</code>, and also the return value of
  58  * <code>put</code>) expect already wrapped instances of
  59  * <code>WeakReference</code>.  That is, after <code>weakMap.put("key",
  60  * o)</code>, <code>weakMap.get("key").equals(o)</code> does not work as
  61  * na&iuml;vely expected; neither does
  62  * <code>weakMap1.putAll(weakMap2)</code>.</p>
  63  *
  64  * <p>At an arbitrary time after the <code>WeakReference</code> value of an
  65  * entry has been cleared by the garbage collector, the entry is automatically
  66  * removed from the map.</p>
  67  *
  68  * <p>Values placed into a <code>WeakMap</code> may optionally support the
  69  * <code>DisposeNotifier</code> interface.  For those that do, the associated
  70  * <code>WeakReference</code> wrappers are automatically cleared as soon as the
  71  * values are disposed.</p>
  72  */
  73 public final class WeakMap implements Map {
  74     /**
  75      * Constructs an empty <code>WeakMap</code>.
  76      */
  77     public WeakMap() {}
  78
  79     /**
  80      * Constructs a new <code>WeakMap</code> with the same mappings as the
  81      * specified <code>Map</code>.
  82      *
  83      * @param m the map whose mappings are to be placed in this map
  84      */
  85     public WeakMap(Map m) {
  86         putAll(m);
  87     }
  88
  89     /**
  90      * Returns the number of key&ndash;value mappings in this map.
  91      *
  92      * <p>This is a non-modifying operation.</p>
  93      *
  94      * @return the number of key&ndash;value mappings in this map
  95      */
  96     public int size() {
  97         return map.size();
  98     }
  99
 100     /**
 101      * Returns <code>true</code> if this map contains no key&ndash;value
 102      * mappings.
 103      *
 104      * <p>This is a non-modifying operation.</p>
 105      *
 106      * @return <code>true</code> if this map contains no key&ndash;value
 107      * mappings
 108      */
 109     public boolean isEmpty() {
 110         return map.isEmpty();
 111     }
 112
 113     /**
 114      * Returns <code>true</code> if this map contains a mapping for the
 115      * specified key.
 116      *
 117      * <p>This is a non-modifying operation.</p>
 118      *
 119      * @param key the key whose presence in this map is to be tested
 120      * @return <code>true</code> if this map contains a mapping for the
 121      * specified key
 122      */
 123     public boolean containsKey(Object key) {
 124         return map.containsKey(key);
 125     }
 126
 127     /**
 128      * Returns <code>true</code> if this map maps one or more keys to the
 129      * specified value.
 130      *
 131      * <p>This is a non-modifying operation.</p>
 132      *
 133      * @param value the value whose presence in this map is to be tested
 134      * @return <code>true</code> if this map maps one or more keys to the
 135      * specified value
 136      */
 137     public boolean containsValue(Object value) {
 138         return map.containsValue(value);
 139     }
 140
 141     /**
 142      * Returns the value to which the specified key is mapped in this map, or
 143      * <code>null</code> if the map contains no mapping for this key.
 144      *
 145      * <p>This is a non-modifying operation.</p>
 146      *
 147      * @param key the key whose associated value is to be returned
 148      *
 149      * @return the value to which this map maps the specified key, or
 150      * <code>null</code> if the map contains no mapping for this key
 151      */
 152     public Object get(Object key) {
 153         return map.get(key);
 154     }
 155
 156     /**
 157      * Associates the specified value with the specified key in this map.
 158      *
 159      * <p>This is a modifying operation.</p>
 160      *
 161      * @param key the key with witch the specified value is to be associated
 162      * @param value the value to be associated with the specified key.  This
 163      * must be a plain object, which is then wrapped in a
 164      * <code>WeakReference</code>.
 165      * @return previous value associated with the specified key, or
 166      * <code>null</code> if there was no mapping for the key
 167      */
 168     public Object put(Object key, Object value) {
 169         cleanUp();
 170         return map.put(key, new Entry(key, value, queue));
 171     }
 172
 173     /**
 174      * Removes the mapping for this key from this map if present.
 175      *
 176      * <p>This is a modifying operation.</p>
 177      *
 178      * @param key the key whose mapping is to be removed from the map
 179      * @return previous value associated with the specified key, or
 180      * <code>null</code> if there was no mapping for the key
 181      */
 182     public Object remove(Object key) {
 183         cleanUp();
 184         return map.remove(key);
 185     }
 186
 187     /**
 188      * Copies all of the mappings from the specified map to this map.
 189      *
 190      * <p>This is a modifying operation.</p>
 191      *
 192      * @param m mappings to be stored in this map.  The values of those mappings
 193      * must be plain objects, which are then wrapped in instances of
 194      * <code>WeakReference</code>.
 195      */
 196     public void putAll(Map t) {
 197         cleanUp();
 198         for (Iterator i = t.entrySet().iterator(); i.hasNext();) {
 199             Map.Entry e = (Map.Entry) i.next();
 200             Object k = e.getKey();
 201             map.put(k, new Entry(k, e.getValue(), queue));
 202         }
 203     }
 204
 205     /**
 206      * Removes all mappings from this map.
 207      *
 208      * <p>This is a modifying operation.</p>
 209      */
 210     public void clear() {
 211         cleanUp();
 212         map.clear();
 213     }
 214
 215     /**
 216      * Returns a view of the keys contained in this map.
 217      *
 218      * <p>This is a non-modifying operation.</p>
 219      *
 220      * @return a set view of the keys contained in this map
 221      */
 222     public Set keySet() {
 223         return map.keySet();
 224     }
 225
 226     /**
 227      * Returns a collection view of the values contained in this map.
 228      *
 229      * <p>This is a non-modifying operation.</p>
 230      *
 231      * @return a collection view of the values contained in this map
 232      */
 233     public Collection values() {
 234         return map.values();
 235     }
 236
 237     /**
 238      * Returns a collection view of the mappings contained in this map.
 239      *
 240      * <p>This is a non-modifying operation.</p>
 241      *
 242      * @return a collection view of the mappings contained in this map
 243      */
 244     public Set entrySet() {
 245         return map.entrySet();
 246     }
 247
 248     public boolean equals(Object o) {
 249         return map.equals(o);
 250     }
 251
 252     public int hashCode() {
 253         return map.hashCode();
 254     }
 255
 256     /**
 257      * Returns the referent of a <code>WeakReference</code>, silently handling a
 258      * <code>null</code> argument.
 259      *
 260      * <p>This static method is useful to wrap around the return values of
 261      * methods like <code>get</code>.</p>
 262      *
 263      * @param ref must be either an instance of <code>WeakReference</code> or
 264      * <code>null</code>
 265      * @return the referent of the specified <code>WeakReference</code>, or
 266      * <code>null</code> if <code>ref</code> is <code>null</code>
 267      */
 268     public static Object getValue(Object ref) {
 269         return ref == null ? null : ((WeakReference) ref).get();
 270     }
 271
 272     // cleanUp must only be called from within modifying methods.  Otherwise,
 273     // the implementations of entrySet, keySet and values would break
 274     // (specificially, iterating over the collections returned by those
 275     // methods), as non-modifying methods might modify the underlying map.
 276     private void cleanUp() {
 277         for (;;) {
 278             Entry e = (Entry) queue.poll();
 279             if (e == null) {
 280                 break;
 281             }
 282             // It is possible that an Entry e1 becomes weakly reachable, then
 283             // another Entry e2 is added to the map for the same key, and only
 284             // then e1 is enqueued.  To not erroneously remove the new e2 in
 285             // that case, check whether the map still contains e1:
 286             Object k = e.key;
 287             if (e == map.get(k)) {
 288                 map.remove(k);
 289             }
 290         }
 291     }
 292
 293     private static final class Entry extends WeakReference
 294         implements DisposeListener
 295     {
 296         public void notifyDispose(DisposeNotifier source) {
 297             Entry.this.clear(); // qualification needed for Java 1.3
 298             enqueue();
 299         }
 300
 301         private Entry(Object key, Object value, ReferenceQueue queue) {
 302             super(value, queue);
 303             this.key = key;
 304             if (value instanceof DisposeNotifier) {
 305                 ((DisposeNotifier) value).addDisposeListener(this);
 306             }
 307         }
 308
 309         private final Object key;
 310     }
 311
 312     private final HashMap map = new HashMap();
 313     private final ReferenceQueue queue = new ReferenceQueue();
 314 }