Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.hd.d.pg2k.svrCore.collections
Class SoftReferenceMap<K,V>

java.lang.Object
  extended by org.hd.d.pg2k.svrCore.collections.SoftReferenceMap<K,V>
All Implemented Interfaces:
java.util.Map<K,V>, MemoryTools.CacheMiniMap<K,V>, MemoryTools.Compactable
public final class SoftReferenceMap<K,V>
extends java.lang.Object
implements MemoryTools.CacheMiniMap<K,V>, java.util.Map<K,V>, MemoryTools.Compactable

Soft cache as highly-threadable (thread-safe) Map which holds each value via a SoftReference and discards mapping when the values are GCed. Similar to a WeakHashMap in its automatic trimming of expired values, and in that presence in this map does not prevent the values being GCed.

When values are GCed they will appear to vanish from the map asynchronously.

It is possible to safely iterate over the content with an iterator over the keySet which will return elements reflecting the state of the keys in the Map at some point at or since the creation of the iterator. It does not throw ConcurrentModificationException. However, iterators are designed to be used by only one thread at a time.

Permits neither null keys nor null values.

Not all operations (ie on the value or entry sets) are be supported.

Nested Class Summary
private static class SoftReferenceMap.SRCMSoftReference<K,V>
          Enqueueable SoftReference for SoftReferenceConcurrentMap.
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Field Summary
private  java.lang.ref.ReferenceQueue<V> _deadRefQueue
          Queue of dead SoftReference entries; never null.
private  boolean clearWhenStressed
          True iff we clear() on memory stress during compact().
private  java.util.concurrent.ConcurrentMap<K,SoftReferenceMap.SRCMSoftReference<K,V>> m
          The internal map; never null.
private  java.lang.String name
          Optional name for diagnostics; can be null.
 
Constructor Summary
private SoftReferenceMap(int capacity, boolean clearWhenStressed, java.lang.String name)
          Create an empty map with the specified initial capacity.
private SoftReferenceMap(java.lang.String name)
          Create an empty map with default characteristics.
 
Method Summary
private  void _clearDeadEntries()
          Expunges any dead entries.
 void clear()
          Clear the map.
 void compact()
          Compacts the representation of this collection if possible.
 boolean containsKey(java.lang.Object key)
           
 boolean containsValue(java.lang.Object value)
           
static
<K,V> SoftReferenceMap<K,V>
create(int capacity, boolean clearWhenStressed, java.lang.String name)
          Create an empty map with the specified initial capacity.
static
<K,V> SoftReferenceMap<K,V>
create(java.lang.String name)
          Create an empty map with default characteristics.
 java.util.Set<java.util.Map.Entry<K,V>> entrySet()
           
 V get(java.lang.Object key)
          Get an entry from the map; null if no such element.
 java.lang.String getCompactableInstanceName()
          Get name of this Compactable instance for tracking purposes, or null if none.
 boolean isEmpty()
          True if the map is non-empty.
 java.util.Set<K> keySet()
           
 V put(K key, V value)
          Put an entry in the map, returning previous value if any.
 void putAll(java.util.Map<? extends K,? extends V> newValues)
           
 V remove(java.lang.Object key)
          Remove an entry from the map and return the removed value, if any, else null.
 int size()
          Return the number of entries in the map; non-negative.
 java.lang.String toString()
          Provide a human-readable summary of status.
 java.util.Collection<V> values()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Field Detail

m

private final java.util.concurrent.ConcurrentMap<K,SoftReferenceMap.SRCMSoftReference<K,V>> m
The internal map; never null.

_deadRefQueue

private final java.lang.ref.ReferenceQueue<V> _deadRefQueue
Queue of dead SoftReference entries; never null.

clearWhenStressed

private final boolean clearWhenStressed
True iff we clear() on memory stress during compact().

name

private final java.lang.String name
Optional name for diagnostics; can be null.

Constructor Detail

SoftReferenceMap

private SoftReferenceMap(java.lang.String name)
Create an empty map with default characteristics. Marked private to force use via factory method.

Parameters:
name - name of this instance for tracking purposes or null if none

SoftReferenceMap

private SoftReferenceMap(int capacity,
                         boolean clearWhenStressed,
                         java.lang.String name)
Create an empty map with the specified initial capacity. Marked private to force use via factory method.

Parameters:
capacity - initial capacity; strictly positive
clearWhenStressed - if true then empty the map on compact() if memory system is stressed
name - name of this instance for tracking purposes or null if none
Method Detail

getCompactableInstanceName

public java.lang.String getCompactableInstanceName()
Get name of this Compactable instance for tracking purposes, or null if none.

Specified by:
getCompactableInstanceName in interface MemoryTools.Compactable

compact

public void compact()
Compacts the representation of this collection if possible.

Specified by:
compact in interface MemoryTools.Compactable

toString

public java.lang.String toString()
Provide a human-readable summary of status. Useful for debugging/tuning, for example.

Overrides:
toString in class java.lang.Object

_clearDeadEntries

private void _clearDeadEntries()
Expunges any dead entries. This avoids races with replacement of values for keys just expired.

This should be called from enough places and/or otherwise often enough to remove expired entries in a timely manner.

create

public static <K,V> SoftReferenceMap<K,V> create(java.lang.String name)
Create an empty map with default characteristics.

Parameters:
name - name of this instance for tracking purposes or null if none

create

public static <K,V> SoftReferenceMap<K,V> create(int capacity,
                                                 boolean clearWhenStressed,
                                                 java.lang.String name)
Create an empty map with the specified initial capacity.

Parameters:
capacity - initial capacity; strictly positive
clearWhenStressed - if true then empty the map on compact() if memory system is stressed
name - name of this instance for tracking purposes or null if none

clear

public void clear()
Description copied from interface: MemoryTools.CacheMiniMap
Clear the map.

Specified by:
clear in interface java.util.Map<K,V>
Specified by:
clear in interface MemoryTools.CacheMiniMap<K,V>

containsKey

public boolean containsKey(java.lang.Object key)
Specified by:
containsKey in interface java.util.Map<K,V>

size

public int size()
Description copied from interface: MemoryTools.CacheMiniMap
Return the number of entries in the map; non-negative.

Specified by:
size in interface java.util.Map<K,V>
Specified by:
size in interface MemoryTools.CacheMiniMap<K,V>

isEmpty

public boolean isEmpty()
Description copied from interface: MemoryTools.CacheMiniMap
True if the map is non-empty. Equivalent to (size() == 0) but may be faster for some implementations.

Specified by:
isEmpty in interface java.util.Map<K,V>
Specified by:
isEmpty in interface MemoryTools.CacheMiniMap<K,V>

keySet

public java.util.Set<K> keySet()
Specified by:
keySet in interface java.util.Map<K,V>

get

public V get(java.lang.Object key)
Description copied from interface: MemoryTools.CacheMiniMap
Get an entry from the map; null if no such element.

Specified by:
get in interface java.util.Map<K,V>
Specified by:
get in interface MemoryTools.CacheMiniMap<K,V>

put

public V put(K key,
             V value)
Description copied from interface: MemoryTools.CacheMiniMap
Put an entry in the map, returning previous value if any.

Specified by:
put in interface java.util.Map<K,V>
Specified by:
put in interface MemoryTools.CacheMiniMap<K,V>

putAll

public void putAll(java.util.Map<? extends K,? extends V> newValues)
Specified by:
putAll in interface java.util.Map<K,V>

remove

public V remove(java.lang.Object key)
Description copied from interface: MemoryTools.CacheMiniMap
Remove an entry from the map and return the removed value, if any, else null.

Specified by:
remove in interface java.util.Map<K,V>
Specified by:
remove in interface MemoryTools.CacheMiniMap<K,V>

containsValue

public boolean containsValue(java.lang.Object value)
Specified by:
containsValue in interface java.util.Map<K,V>

values

public java.util.Collection<V> values()
Specified by:
values in interface java.util.Map<K,V>

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()
Specified by:
entrySet in interface java.util.Map<K,V>
Overview  Package   Class  Tree  Deprecated  Index  Help 
DHD Multimedia Gallery V1.60.69
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright (c) 1996-2012, Damon Hart-Davis. All rights reserved.