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

   1 /*
   2  * This file is part of the LibreOffice project.
   3  *
   4  * This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   7  *
   8  * This file incorporates work covered by the following license notice:
   9  *
  10  *   Licensed to the Apache Software Foundation (ASF) under one or more
  11  *   contributor license agreements. See the NOTICE file distributed
  12  *   with this work for additional information regarding copyright
  13  *   ownership. The ASF licenses this file to you under the Apache
  14  *   License, Version 2.0 (the "License"); you may not use this file
  15  *   except in compliance with the License. You may obtain a copy of
  16  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  17  */
  18
  19 package com.sun.star.lib.util;
  20
  21 import java.lang.ref.ReferenceQueue;
  22 import java.lang.ref.WeakReference;
  23 import java.util.Collection;
  24 import java.util.HashMap;
  25 import java.util.Iterator;
  26 import java.util.Map;
  27 import java.util.Set;
  28
  29 /**
  30  * A hash map that holds values of type <code>WeakReference</code>.
  31  *
  32  * <p>Like <code>HashMap</code>, this implementation provides all of the
  33  * optional map operations, and permits the <code>null</code> key.</p>
  34  *
  35  * <p>Also like <code>HashMap</code>, this implementation is not synchronized.
  36  * If multiple threads share an instance, and at least one of them executes any
  37  * modifying operations on the <code>WeakMap</code>, they have to use external
  38  * synchronization.</p>
  39  *
  40  * <p>Unlike other map implementations, <code>WeakMap</code> is asymmetric in
  41  * that <code>put</code> expects the given value to be a plain object that is
  42  * then wrapped in a <code>WeakReference</code>, while the occurrences of values
  43  * in all other methods (<code>containsValue</code>, <code>entrySet</code>,
  44  * <code>equals</code>, <code>get</code>, <code>hashCode</code>,
  45  * <code>remove</code>, <code>values</code>, and also the return value of
  46  * <code>put</code>) expect already wrapped instances of
  47  * <code>WeakReference</code>.  That is, after <code>weakMap.put("key",
  48  * o)</code>, <code>weakMap.get("key").equals(o)</code> does not work as
  49  * na&iuml;vely expected; neither does
  50  * <code>weakMap1.putAll(weakMap2)</code>.</p>
  51  *
  52  * <p>At an arbitrary time after the <code>WeakReference</code> value of an
  53  * entry has been cleared by the garbage collector, the entry is automatically
  54  * removed from the map.</p>
  55  *
  56  * <p>Values placed into a <code>WeakMap</code> may optionally support the
  57  * <code>DisposeNotifier</code> interface.  For those that do, the associated
  58  * <code>WeakReference</code> wrappers are automatically cleared as soon as the
  59  * values are disposed.</p>
  60  *
  61  * Note that this class does not actually implement the Map interface properly,
  62  * the type of the return value of the entrySet and values methods is wrong,
  63  * but the "implements Map" is retained for backward compatibility.
  64  */
  65 public final class WeakMap<K,V> implements Map {
  66
  67     /**
  68      * Declare the map as WeakReference instead of Entry because it makes the return
  69      * type signatures of values() and keySet() cleaner.
  70      */
  71     private final HashMap<K, WeakReference<V>> map = new HashMap<K, WeakReference<V>>();
  72     private final ReferenceQueue<V> queue = new ReferenceQueue<V>();
  73
  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<K,V> 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(/*K*/ 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 /*WeakReference<V>*/ 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 WeakReference<V> get(/*K*/ 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 which 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 /*WeakReference<V>*/ put(/*K*/ Object key, /*V*/ Object value) {
 169         cleanUp();
 170         return map.put((K) key, new Entry<K,V>((K) key, (V) 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 /*WeakReference<V>*/ remove(/*K*/ 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/*<K,V>*/ m) {
 197         cleanUp();
 198         for (Iterator<Map.Entry<K,V>> i = m.entrySet().iterator(); i.hasNext();) {
 199             Map.Entry<K,V> e = i.next();
 200             K k = e.getKey();
 201             map.put(k, new Entry<K,V>(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<K> 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<WeakReference<V>> 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/*<Map.Entry<K,WeakReference<V>>>*/ entrySet() {
 245         return map.entrySet();
 246     }
 247
 248     @Override
 249     public boolean equals(Object o) {
 250         return map.equals(o);
 251     }
 252
 253     @Override
 254     public int hashCode() {
 255         return map.hashCode();
 256     }
 257
 258     /**
 259      * Returns the referent of a <code>WeakReference</code>, silently handling a
 260      * <code>null</code> argument.
 261      *
 262      * <p>This static method is useful to wrap around the return values of
 263      * methods like <code>get</code>.</p>
 264      *
 265      * @param ref must be either an instance of <code>WeakReference</code> or
 266      * <code>null</code>
 267      * @return the referent of the specified <code>WeakReference</code>, or
 268      * <code>null</code> if <code>ref</code> is <code>null</code>
 269      */
 270     public static <T> T getValue(Object /*WeakReference<T>*/ ref) {
 271         return ref == null ? null : ((WeakReference<T>) ref).get();
 272     }
 273
 274     /**
 275      * cleanUp() must only be called from within modifying methods.  Otherwise,
 276      * the implementations of entrySet, keySet and values would break
 277      * (Specifically, iterating over the collections returned by those
 278      * methods), as non-modifying methods might modify the underlying map.
 279      **/
 280     private void cleanUp() {
 281         for (;;) {
 282             Entry<K,V> e = (Entry<K,V>) queue.poll();
 283             if (e == null) {
 284                 break;
 285             }
 286             // It is possible that an Entry e1 becomes weakly reachable, then
 287             // another Entry e2 is added to the map for the same key, and only
 288             // then e1 is enqueued.  To not erroneously remove the new e2 in
 289             // that case, check whether the map still contains e1:
 290             Object k = e.key;
 291             if (e == map.get(k)) {
 292                 map.remove(k);
 293             }
 294         }
 295     }
 296
 297     private static final class Entry<K,V> extends WeakReference<V>
 298         implements DisposeListener
 299     {
 300         private final K key;
 301
 302         private Entry(K key, V value, ReferenceQueue<V> queue) {
 303             super(value, queue);
 304             this.key = key;
 305             if (value instanceof DisposeNotifier) {
 306                 ((DisposeNotifier) value).addDisposeListener(this);
 307             }
 308         }
 309
 310         /**
 311          * @see DisposeListener#notifyDispose(DisposeNotifier)
 312          */
 313         public void notifyDispose(DisposeNotifier source) {
 314             clear();
 315             enqueue();
 316         }
 317     }
 318
 319 }