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     @SuppressWarnings("unchecked")
 169     public Object /*WeakReference<V>*/ put(/*K*/ Object key, /*V*/ Object value) {
 170         cleanUp();
 171         return map.put((K) key, new Entry<K,V>((K) key, (V) value, queue));
 172     }
 173
 174     /**
 175      * Removes the mapping for this key from this map if present.
 176      *
 177      * <p>This is a modifying operation.</p>
 178      *
 179      * @param key the key whose mapping is to be removed from the map
 180      * @return previous value associated with the specified key, or
 181      * <code>null</code> if there was no mapping for the key
 182      */
 183     public Object /*WeakReference<V>*/ remove(/*K*/ Object key) {
 184         cleanUp();
 185         return map.remove(key);
 186     }
 187
 188     /**
 189      * Copies all of the mappings from the specified map to this map.
 190      *
 191      * <p>This is a modifying operation.</p>
 192      *
 193      * @param m mappings to be stored in this map.  The values of those mappings
 194      * must be plain objects, which are then wrapped in instances of
 195      * <code>WeakReference</code>.
 196      */
 197     @SuppressWarnings("unchecked")
 198     public void putAll(Map/*<K,V>*/ m) {
 199         cleanUp();
 200         for (Iterator<Map.Entry<K,V>> i = m.entrySet().iterator(); i.hasNext();) {
 201             Map.Entry<K,V> e = i.next();
 202             K k = e.getKey();
 203             map.put(k, new Entry<K,V>(k, e.getValue(), queue));
 204         }
 205     }
 206
 207     /**
 208      * Removes all mappings from this map.
 209      *
 210      * <p>This is a modifying operation.</p>
 211      */
 212     public void clear() {
 213         cleanUp();
 214         map.clear();
 215     }
 216
 217     /**
 218      * Returns a view of the keys contained in this map.
 219      *
 220      * <p>This is a non-modifying operation.</p>
 221      *
 222      * @return a set view of the keys contained in this map
 223      */
 224     public Set<K> keySet() {
 225         return map.keySet();
 226     }
 227
 228     /**
 229      * Returns a collection view of the values contained in this map.
 230      *
 231      * <p>This is a non-modifying operation.</p>
 232      *
 233      * @return a collection view of the values contained in this map
 234      */
 235     public Collection<WeakReference<V>> values() {
 236         return map.values();
 237     }
 238
 239     /**
 240      * Returns a collection view of the mappings contained in this map.
 241      *
 242      * <p>This is a non-modifying operation.</p>
 243      *
 244      * @return a collection view of the mappings contained in this map
 245      */
 246     public Set/*<Map.Entry<K,WeakReference<V>>>*/ entrySet() {
 247         return map.entrySet();
 248     }
 249
 250     @Override
 251     public boolean equals(Object o) {
 252         return map.equals(o);
 253     }
 254
 255     @Override
 256     public int hashCode() {
 257         return map.hashCode();
 258     }
 259
 260     /**
 261      * Returns the referent of a <code>WeakReference</code>, silently handling a
 262      * <code>null</code> argument.
 263      *
 264      * <p>This static method is useful to wrap around the return values of
 265      * methods like <code>get</code>.</p>
 266      *
 267      * @param ref must be either an instance of <code>WeakReference</code> or
 268      * <code>null</code>
 269      * @return the referent of the specified <code>WeakReference</code>, or
 270      * <code>null</code> if <code>ref</code> is <code>null</code>
 271      */
 272     @SuppressWarnings("unchecked")
 273     public static <T> T getValue(Object /*WeakReference<T>*/ ref) {
 274         return ref == null ? null : ((WeakReference<T>) ref).get();
 275     }
 276
 277     /**
 278      * cleanUp() must only be called from within modifying methods.  Otherwise,
 279      * the implementations of entrySet, keySet and values would break
 280      * (Specifically, iterating over the collections returned by those
 281      * methods), as non-modifying methods might modify the underlying map.
 282      **/
 283     @SuppressWarnings("unchecked")
 284     private void cleanUp() {
 285         for (;;) {
 286             Entry<K,V> e = (Entry<K,V>) queue.poll();
 287             if (e == null) {
 288                 break;
 289             }
 290             // It is possible that an Entry e1 becomes weakly reachable, then
 291             // another Entry e2 is added to the map for the same key, and only
 292             // then e1 is enqueued.  To not erroneously remove the new e2 in
 293             // that case, check whether the map still contains e1:
 294             Object k = e.key;
 295             if (e == map.get(k)) {
 296                 map.remove(k);
 297             }
 298         }
 299     }
 300
 301     private static final class Entry<K,V> extends WeakReference<V>
 302         implements DisposeListener
 303     {
 304         private final K key;
 305
 306         private Entry(K key, V value, ReferenceQueue<V> queue) {
 307             super(value, queue);
 308             this.key = key;
 309             if (value instanceof DisposeNotifier) {
 310                 ((DisposeNotifier) value).addDisposeListener(this);
 311             }
 312         }
 313
 314         /**
 315          * @see DisposeListener#notifyDispose(DisposeNotifier)
 316          */
 317         public void notifyDispose(DisposeNotifier source) {
 318             clear();
 319             enqueue();
 320         }
 321     }
 322
 323 }