A SoftCache object uses soft references to implement a memory-sensitive hash map. If the garbage collector determines at a certain point in time that a value object in a SoftCache entry is no longer strongly reachable, then it may remove that entry in order to release the memory occupied by the value object. All SoftCache objects are guaranteed to be completely cleared before the virtual machine will throw an OutOfMemoryError. Because of this automatic clearing feature, the behavior of this class is somewhat different from that of other Map implementations.

Both null values and the null key are supported. This class has the same performance characteristics as the HashMap class, and has the same efficiency parameters of initial capacity and load factor.

Like most collection classes, this class is not synchronized. A synchronized SoftCache may be constructed using the Collections.synchronizedMap method.

In typical usage this class will be subclassed and the fill method will be overridden. When the get method is invoked on a key for which there is no mapping in the cache, it will in turn invoke the fill method on that key in an attempt to construct a corresponding value. If the fill method returns such a value then the cache will be updated and the new value will be returned. Thus, for example, a simple URL-content cache can be constructed as follows:

    public class URLCache extends SoftCache {
        protected Object fill(Object key) {
            return ((URL)key).getContent();
        }
    }

The behavior of the SoftCache class depends in part upon the actions of the garbage collector, so several familiar (though not required) Map invariants do not hold for this class.

Because entries are removed from a SoftCache in response to dynamic advice from the garbage collector, a SoftCache may behave as though an unknown thread is silently removing entries. In particular, even if you synchronize on a SoftCache instance and invoke none of its mutator methods, it is possible for the size method to return smaller values over time, for the isEmpty method to return false and then true, for the containsKey method to return true and later false for a given key, for the get method to return a value for a given key but later return null, for the put method to return null and the remove method to return false for a key that previously appeared to be in the map, and for successive examinations of the key set, the value set, and the entry set to yield successively smaller numbers of elements.