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.google.common.collect
Class MapMaker

    java.lang.Object
      com.google.common.collect.MapMaker

    public final class MapMaker

extends Object

A `ConcurrentMap` builder, providing any combination of these features: soft or weak keys, soft or weak values, timed expiration, and on-demand computation of values. Usage example:

     ConcurrentMap<Key, Graph> graphs = new MapMaker()
           .concurrencyLevel(32)
           .softKeys()
           .weakValues()
           .expiration(30, TimeUnit.MINUTES)
           .makeComputingMap(
               new Function<Key, Graph>() {
                 public Graph apply(Key key) {
                   return createExpensiveGraph(key);
                 }
               });

These features are all optional; `new MapMaker().makeMap()` returns a valid concurrent map that behaves exactly like a `ConcurrentHashMap`. The returned map is implemented as a hash table with similar performance characteristics to `ConcurrentHashMap`. It supports all optional operations of the `ConcurrentMap` interface. It does not permit null keys or values. It is serializable; however, serializing a map that uses soft or weak references can give unpredictable results.

Note: by default, the returned map uses equality comparisons (the `equals` method) to determine equality for keys or values. However, if `weakKeys()` or `softKeys()` was specified, the map uses identity (`==`) comparisons instead for keys. Likewise, if `weakValues()` or `softValues()` was specified, the map uses identity comparisons for values.

The returned map has weakly consistent iteration: an iterator over one of the map's view collections may reflect some, all or none of the changes made to the map after the iterator was created.

An entry whose key or value is reclaimed by the garbage collector immediately disappears from the map. (If the default settings of strong keys and strong values are used, this will never happen.) The client can never observe a partially-reclaimed entry. Any `Map.Entry` instance retrieved from the map's entry set is snapshot of that entry's state at the time of retrieval.

`new MapMaker().weakKeys().makeMap()` can almost always be used as a drop-in replacement for `WeakHashMap`, adding concurrency, asynchronous cleanup, identity-based equality for keys, and great flexibility.

Author:
  Bob Lee, Kevin Bourrillion

Constructor Summary
`MapMaker()` Constructs a new `MapMaker` instance with default settings, including strong keys, strong values, and no automatic expiration.

Method Summary
`MapMaker` | `concurrencyLevel(int concurrencyLevel)` Guides the allowed concurrency among update operations.
`MapMaker` | `expiration(long duration, TimeUnit unit)` Specifies that each entry should be automatically removed from the map once a fixed duration has passed since the entry's creation.
`MapMaker` | `initialCapacity(int initialCapacity)` Sets a custom initial capacity (defaults to 16).
`
`<K,V> ConcurrentMap<K,V>`
` | `makeComputingMap(Function<? super K,? extends V> computingFunction)` Builds a map that supports atomic, on-demand computation of values.
`
`<K,V> ConcurrentMap<K,V>`
` | `makeMap()` Builds the final map, without on-demand computation of values.
`MapMaker` | `softKeys()` Specifies that each key (not value) stored in the map should be wrapped in a `SoftReference` (by default, strong references are used).
`MapMaker` | `softValues()` Specifies that each value (not key) stored in the map should be wrapped in a `SoftReference` (by default, strong references are used).
`MapMaker` | `weakKeys()` Specifies that each key (not value) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).
`MapMaker` | `weakValues()` Specifies that each value (not key) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).

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

Constructor Detail

### MapMaker

    public MapMaker()

  Constructs a new `MapMaker` instance with default settings, including strong keys, strong values, and no automatic expiration.

Method Detail

### initialCapacity

    public MapMaker initialCapacity(int initialCapacity)

  Sets a custom initial capacity (defaults to 16). Resizing this or any other kind of hash table is a relatively slow operation, so, when possible, it is a good idea to provide estimates of expected table sizes.

  Throws:
    `IllegalArgumentException` - if `initialCapacity` is negative
    `IllegalStateException` - if an initial capacity was already set

### concurrencyLevel

    public MapMaker concurrencyLevel(int concurrencyLevel)

  Guides the allowed concurrency among update operations. Used as a hint for internal sizing. The table is internally partitioned to try to permit the indicated number of concurrent updates without contention. Because placement in hash tables is essentially random, the actual concurrency will vary. Ideally, you should choose a value to accommodate as many threads as will ever concurrently modify the table. Using a significantly higher value than you need can waste space and time, and a significantly lower value can lead to thread contention. But overestimates and underestimates within an order of magnitude do not usually have much noticeable impact. A value of one is appropriate when it is known that only one thread will modify and all others will only read. Defaults to 16.

  Throws:
    `IllegalArgumentException` - if `concurrencyLevel` is nonpositive
    `IllegalStateException` - if a concurrency level was already set

### weakKeys

    public MapMaker weakKeys()

  Specifies that each key (not value) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).

  Note: the map will use identity (`==`) comparison to determine equality of weak keys, which may not behave as you expect. For example, storing a key in the map and then attempting a lookup using a different but `equals`-equivalent key will always fail.

  Throws:
    `IllegalStateException` - if the key strength was already set
  See Also:
    `WeakReference`

### softKeys

    public MapMaker softKeys()

  Specifies that each key (not value) stored in the map should be wrapped in a `SoftReference` (by default, strong references are used).

  Note: the map will use identity (`==`) comparison to determine equality of soft keys, which may not behave as you expect. For example, storing a key in the map and then attempting a lookup using a different but `equals`-equivalent key will always fail.

  Throws:
    `IllegalStateException` - if the key strength was already set
  See Also:
    `SoftReference`

### weakValues

    public MapMaker weakValues()

  Specifies that each value (not key) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).

  Weak values will be garbage collected once they are weakly reachable. This makes them a poor candidate for caching; consider `softValues()` instead.

  Note: the map will use identity (`==`) comparison to determine equality of weak values. This will notably impact the behavior of `containsValue`, `remove(Object, Object)`, and `replace(K, V, V)`.

  Throws:
    `IllegalStateException` - if the key strength was already set
  See Also:
    `WeakReference`

### softValues

    public MapMaker softValues()

  Specifies that each value (not key) stored in the map should be wrapped in a `SoftReference` (by default, strong references are used).

  Soft values will be garbage collected in response to memory demand, and in a least-recently-used manner. This makes them a good candidate for caching.

  Note: the map will use identity (`==`) comparison to determine equality of soft values. This will notably impact the behavior of `containsValue`, `remove(Object, Object)`, and `replace(K, V, V)`.

  Throws:
    `IllegalStateException` - if the value strength was already set
  See Also:
    `SoftReference`

### expiration

    public MapMaker expiration(long duration,
                               TimeUnit unit)

  Specifies that each entry should be automatically removed from the map once a fixed duration has passed since the entry's creation.

  Parameters:
    `duration` - the length of time after an entry is created that it should be automatically removed
    `unit` - the unit that `duration` is expressed in
  Throws:
    `IllegalArgumentException` - if `duration` is not positive
    `IllegalStateException` - if the expiration time was already set

### makeMap

    public <K,V> ConcurrentMap<K,V> makeMap()

  Builds the final map, without on-demand computation of values. This method does not alter the state of this `MapMaker` instance, so it can be invoked again to create multiple independent maps.

  Type Parameters:
    `K` - the type of keys to be stored in the returned map
    `V` - the type of values to be stored in the returned map
  Returns:
    a concurrent map having the requested features

### makeComputingMap

    public <K,V> ConcurrentMap<K,V> makeComputingMap(Function<? super K,? extends V> computingFunction)

  Builds a map that supports atomic, on-demand computation of values. `Map.get(java.lang.Object)` either returns an already-computed value for the given key, atomically computes it using the supplied function, or, if another thread is currently computing the value for this key, simply waits for that thread to finish and returns its computed value. Note that the function may be executed concurrently by multiple threads, but only for distinct keys.

  If an entry's value has not finished computing yet, query methods besides `get` return immediately as if an entry doesn't exist. In other words, an entry isn't externally visible until the value's computation completes.

  `Map.get(java.lang.Object)` on the returned map will never return `null`. It may throw:

  - `NullPointerException` if the key is null or the computing function returns null
  - `ComputationException` if an exception was thrown by the computing function. If that exception is already of type `ComputationException`, it is propagated directly; otherwise it is wrapped.

  Note: Callers of `get` must ensure that the key argument is of type `K`. The `get` method accepts `Object`, so the key type is not checked at compile time. Passing an object of a type other than `K` can result in that object being unsafely passed to the computing function as type `K`, and unsafely stored in the map.

  If `Map.put(K, V)` is called before a computation completes, other threads waiting on the computation will wake up and return the stored value. When the computation completes, its new result will overwrite the value that was put in the map manually.

  This method does not alter the state of this `MapMaker` instance, so it can be invoked again to create multiple independent maps.

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