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

## com.opensymphony.xwork2.inject.util
Class ReferenceMap<K,V>

    java.lang.Object
      com.opensymphony.xwork2.inject.util.ReferenceMap<K,V>

All Implemented Interfaces:
  Serializable, Map<K,V>

Direct Known Subclasses:
  ReferenceCache

    public class ReferenceMap<K,V>

extends Object
implements Map<K,V>, Serializable

Concurrent hash map that wraps keys and/or values in soft or weak references. Does not support null keys or values. Uses identity equality for weak and soft keys.

The concurrent semantics of `ConcurrentHashMap` combined with the fact that the garbage collector can asynchronously reclaim and clean up after keys and values at any time can lead to some racy semantics. For example, `size()` returns an upper bound on the size, i.e. the actual size may be smaller in cases where the key or value has been reclaimed but the map entry has not been cleaned up yet.

Another example: If `get(Object)` cannot find an existing entry for a key, it will try to create one. This operation is not atomic. One thread could `put(Object, Object)` a value between the time another thread running `get()` checks for an entry and decides to create one. In this case, the newly created value will replace the put value in the map. Also, two threads running `get()` concurrently can potentially create duplicate values for a given key.

In other words, this class is great for caching but not atomicity.

Author:
  crazybob@google.com (Bob Lee)
See Also:
  Serialized Form

Nested Class Summary
`(package private) class` | `ReferenceMap.Entry`
`(package private) static interface` | `ReferenceMap.InternalReference` Marker interface to differentiate external and internal references.
`(package private) static class` | `ReferenceMap.KeyReferenceAwareWrapper` Used for keys.
`private static class` | `ReferenceMap.PutStrategy`
`(package private) static class` | `ReferenceMap.ReferenceAwareWrapper` Big hack.
`(package private) class` | `ReferenceMap.SoftKeyReference`
`(package private) class` | `ReferenceMap.SoftValueReference`
`protected static interface` | `ReferenceMap.Strategy`
`(package private) class` | `ReferenceMap.WeakKeyReference`
`(package private) class` | `ReferenceMap.WeakValueReference`

Field Summary
`private static ReferenceMap.PutStrategy` | `defaultPutStrategy`
`(package private) ConcurrentMap<Object,Object>` | `delegate`
`(package private) ReferenceType` | `keyReferenceType`
`private static long` | `serialVersionUID`
`(package private) ReferenceType` | `valueReferenceType`

Constructor Summary
`ReferenceMap(ReferenceType keyReferenceType, ReferenceType valueReferenceType)` Concurrent hash map that wraps keys and/or values based on specified reference types.

Method Summary
`void` | `clear()`
`boolean` | `containsKey(Object key)`
`boolean` | `containsValue(Object value)`
`(package private) Object` | `dereference(ReferenceType referenceType, Object reference)` Returns the refererent for reference given its reference type.
`(package private)
`<T extends Collection<Object>> T`
` | `dereferenceCollection(ReferenceType referenceType, T in, T out)` Dereferences elements in `in` using `referenceType` and puts them in `out`.
`(package private) ReferenceMap.Entry` | `dereferenceEntry(Map.Entry<Object,Object> entry)` Dereferences an entry.
`(package private) K` | `dereferenceKey(Object o)` Converts a reference to a key.
`(package private) Set<K>` | `dereferenceKeySet(Set keyReferences)` Dereferences a set of key references.
`(package private) V` | `dereferenceValue(Object o)` Converts a reference to a value.
`(package private) Collection<V>` | `dereferenceValues(Collection valueReferences)` Dereferences a collection of value references.
`(package private) static void` | `ensureNotNull(Object... array)`
`(package private) static void` | `ensureNotNull(Object o)`
`Set<Map.Entry<K,V>>` | `entrySet()` Returns an unmodifiable set view of the entries in this map.
`(package private) V` | `execute(ReferenceMap.Strategy strategy, K key, V value)`
`V` | `get(Object key)`
`protected ReferenceMap.PutStrategy` | `getPutStrategy()`
`(package private) V` | `internalGet(K key)`
`boolean` | `isEmpty()`
`(package private) static int` | `keyHashCode(Object key)`
`Set<K>` | `keySet()` Returns an unmodifiable set view of the keys in this map.
`(package private) Object` | `makeKeyReferenceAware(Object o)` Wraps key so it can be compared to a referenced key for equality.
`(package private) Object` | `makeValueReferenceAware(Object o)` Wraps value so it can be compared to a referenced value for equality.
`V` | `put(K key, V value)`
`void` | `putAll(Map<? extends K,? extends V> t)`
`V` | `putIfAbsent(K key, V value)`
`protected ReferenceMap.Strategy` | `putIfAbsentStrategy()`
`protected ReferenceMap.Strategy` | `putStrategy()`
`private void` | `readObject(ObjectInputStream in)`
`(package private) static boolean` | `referenceEquals(Reference r, Object o)` Tests weak and soft references for identity equality.
`(package private) Object` | `referenceKey(K key)` Creates a reference for a key.
`(package private) Object` | `referenceValue(Object keyReference, Object value)` Creates a reference for a value.
`V` | `remove(Object key)`
`boolean` | `remove(Object key, Object value)`
`V` | `replace(K key, V value)`
`boolean` | `replace(K key, V oldValue, V newValue)`
`protected ReferenceMap.Strategy` | `replaceStrategy()`
`int` | `size()`
`Collection<V>` | `values()` Returns an unmodifiable set view of the values in this map.
`private void` | `writeObject(ObjectOutputStream out)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface java.util.Map
`equals, hashCode`

Field Detail

### serialVersionUID

    private static final long serialVersionUID

See Also:
  Constant Field Values

### delegate

    transient ConcurrentMap<Object,Object> delegate

### keyReferenceType

    final ReferenceType keyReferenceType

### valueReferenceType

    final ReferenceType valueReferenceType

### defaultPutStrategy

    private static ReferenceMap.PutStrategy defaultPutStrategy

Constructor Detail

### ReferenceMap

    public ReferenceMap(ReferenceType keyReferenceType,
                        ReferenceType valueReferenceType)

  Concurrent hash map that wraps keys and/or values based on specified reference types.

  Parameters:
    `keyReferenceType` - key reference type
    `valueReferenceType` - value reference type

Method Detail

### internalGet

    V internalGet(K key)

### get

    public V get(Object key)

  Specified by:
    `get` in interface `Map<K,V>`

### execute

    V execute(ReferenceMap.Strategy strategy,
              K key,
              V value)

### put

    public V put(K key,
                 V value)

  Specified by:
    `put` in interface `Map<K,V>`

### remove

    public V remove(Object key)

  Specified by:
    `remove` in interface `Map<K,V>`

### size

    public int size()

  Specified by:
    `size` in interface `Map<K,V>`

### isEmpty

    public boolean isEmpty()

  Specified by:
    `isEmpty` in interface `Map<K,V>`

### containsKey

    public boolean containsKey(Object key)

  Specified by:
    `containsKey` in interface `Map<K,V>`

### containsValue

    public boolean containsValue(Object value)

  Specified by:
    `containsValue` in interface `Map<K,V>`

### putAll

    public void putAll(Map<? extends K,? extends V> t)

  Specified by:
    `putAll` in interface `Map<K,V>`

### clear

    public void clear()

  Specified by:
    `clear` in interface `Map<K,V>`

### keySet

    public Set<K> keySet()

  Returns an unmodifiable set view of the keys in this map. As this method creates a defensive copy, the performance is O(n).

  Specified by:
    `keySet` in interface `Map<K,V>`

### values

    public Collection<V> values()

  Returns an unmodifiable set view of the values in this map. As this method creates a defensive copy, the performance is O(n).

  Specified by:
    `values` in interface `Map<K,V>`

### putIfAbsent

    public V putIfAbsent(K key,
                         V value)

### remove

    public boolean remove(Object key,
                          Object value)

### replace

    public boolean replace(K key,
                           V oldValue,
                           V newValue)

### replace

    public V replace(K key,
                     V value)

### entrySet

    public Set<Map.Entry<K,V>> entrySet()

  Returns an unmodifiable set view of the entries in this map. As this method creates a defensive copy, the performance is O(n).

  Specified by:
    `entrySet` in interface `Map<K,V>`

### dereferenceEntry

    ReferenceMap.Entry dereferenceEntry(Map.Entry<Object,Object> entry)

  Dereferences an entry. Returns null if the key or value has been gc'ed.

### referenceKey

    Object referenceKey(K key)

  Creates a reference for a key.

### dereferenceKey

    K dereferenceKey(Object o)

  Converts a reference to a key.

### dereferenceValue

    V dereferenceValue(Object o)

  Converts a reference to a value.

### dereference

    Object dereference(ReferenceType referenceType,
                       Object reference)

  Returns the refererent for reference given its reference type.

### referenceValue

    Object referenceValue(Object keyReference,
                          Object value)

  Creates a reference for a value.

### dereferenceKeySet

    Set<K> dereferenceKeySet(Set keyReferences)

  Dereferences a set of key references.

### dereferenceValues

    Collection<V> dereferenceValues(Collection valueReferences)

  Dereferences a collection of value references.

### makeKeyReferenceAware

    Object makeKeyReferenceAware(Object o)

  Wraps key so it can be compared to a referenced key for equality.

### makeValueReferenceAware

    Object makeValueReferenceAware(Object o)

  Wraps value so it can be compared to a referenced value for equality.

### dereferenceCollection

    <T extends Collection<Object>> T dereferenceCollection(ReferenceType referenceType,
                                                           T in,
                                                           T out)

  Dereferences elements in `in` using `referenceType` and puts them in `out`. Returns `out`.

### keyHashCode

    static int keyHashCode(Object key)

### referenceEquals

    static boolean referenceEquals(Reference r,
                                   Object o)

  Tests weak and soft references for identity equality. Compares references to other references and wrappers. If o is a reference, this returns true if r == o or if r and o reference the same non null object. If o is a wrapper, this returns true if r's referent is identical to the wrapped object.

### putStrategy

    protected ReferenceMap.Strategy putStrategy()

### putIfAbsentStrategy

    protected ReferenceMap.Strategy putIfAbsentStrategy()

### replaceStrategy

    protected ReferenceMap.Strategy replaceStrategy()

### getPutStrategy

    protected ReferenceMap.PutStrategy getPutStrategy()

### ensureNotNull

    static void ensureNotNull(Object o)

### ensureNotNull

    static void ensureNotNull(Object... array)

### writeObject

    private void writeObject(ObjectOutputStream out)
                      throws IOException

  Throws:
    `IOException`

### readObject

    private void readObject(ObjectInputStream in)
                     throws IOException,
                            ClassNotFoundException

  Throws:
    `IOException`
    `ClassNotFoundException`

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

Copyright © 2000-2007 Apache Software Foundation. All Rights Reserved.