org.codehaus.plexus.util

## Class FastMap<K,V>

- java.lang.Object
- - org.codehaus.plexus.util.FastMap<K,V>

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

    public class FastMap<K,V>
    extends Object
    implements Map<K,V>, Cloneable, Serializable

This class represents a `Map` collection with real-time behavior. Unless the map's size exceeds its current capacity, no dynamic memory allocation is ever performed and response time is extremely fast and consistent.

Our benchmark indicates that `FastMap.put(key, value)` is up to 5x faster than `java.util.HashMap.put(key, value)`. This difference is mostly due to the cost of the `Map.Entry` allocations that `FastMap` avoids by recycling its entries (see note below).

`FastMap` has a predictable iteration order, which is the order in which keys were inserted into the map (similar to `java.util.LinkedHashMap` collection class).

Applications may change the resizing policy of `FastMap` by overriding the `sizeChanged()` method. For example, to improve predictability, automatic resizing can be disabled.

This implementation is not synchronized. Multiple threads accessing or modifying the collection must be synchronized externally.

Note: To avoid dynamic memory allocations, `FastMap` maintains an internal pool of `Map.Entry` objects. The size of the pool is determined by the map's capacity. When an entry is removed from the map, it is automatically restored to the pool.

This class is public domain (not copyrighted).

Version:
  5.3, October 31 2003
Author:
  Jean-Marie Dautelle
See Also:
  Serialized Form

### Nested Class Summary

### Nested classes/interfaces inherited from interface java.util.Map

`Map.Entry<K,V>`

### Constructor Summary

Constructors
Constructor and Description
`FastMap()` Creates a `FastMap` with a capacity of `256` entries.
`FastMap(int capacity)` Creates a `FastMap` with the specified capacity.
`FastMap(Map map)` Creates a `FastMap`, copy of the specified `Map`.

### Method Summary

All Methods Instance Methods Concrete Methods
`int` `capacity()` Returns the capacity of this `FastMap`.
`void` `clear()` Removes all mappings from this `FastMap`.
`Object` `clone()` Returns a shallow copy of this `FastMap`.
`boolean` `containsKey(Object key)` Indicates if this `FastMap` contains a mapping for the specified key.
`boolean` `containsValue(Object value)` Indicates if this `FastMap` maps one or more keys to the specified value.
`Set` `entrySet()` Returns a collection view of the mappings contained in this `FastMap`.
`boolean` `equals(Object obj)` Compares the specified object with this `FastMap` for equality.
`V` `get(Object key)` Returns the value to which this `FastMap` maps the specified key.
`Map.Entry` `getEntry(Object key)` Returns the entry with the specified key.
`int` `hashCode()` Returns the hash code value for this `FastMap`.
`boolean` `isEmpty()` Indicates if this `FastMap` contains no key-value mappings.
`Set` `keySet()` Returns a set view of the keys contained in this `FastMap`.
`Object` `put(Object key, Object value)` Associates the specified value with the specified key in this `FastMap`.
`void` `putAll(Map<? extends K,? extends V> map)` Copies all of the mappings from the specified map to this `FastMap`.
`V` `remove(Object key)` Removes the mapping for this key from this `FastMap` if present.
`void` `setCapacity(int newCapacity)` Changes the current capacity of this `FastMap`.
`int` `size()` Returns the number of key-value mappings in this `FastMap`.
`protected void` `sizeChanged()` This methods is being called when the size of this `FastMap` has changed.
`String` `toString()` Returns a `String` representation of this `FastMap`.
`Collection` `values()` Returns a collection view of the values contained in this `FastMap`.

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.util.Map

`compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

### Constructor Detail

#### FastMap

    public FastMap()

Creates a `FastMap` with a capacity of `256` entries.

#### FastMap

    public FastMap(Map map)

Creates a `FastMap`, copy of the specified `Map`. If the specified map is not an instance of `FastMap`, the newly created map has a capacity set to the specified map's size. The copy has the same order as the original, regardless of the original map's implementation:

         TreeMap dictionary = ...;
         FastMap dictionaryLookup = new FastMap(dictionary);

Parameters:
  `map` - the map whose mappings are to be placed in this map.

#### FastMap

    public FastMap(int capacity)

Creates a `FastMap` with the specified capacity. Unless the capacity is exceeded, operations on this map do not allocate entries. For optimum performance, the capacity should be of the same order of magnitude or larger than the expected map's size.

Parameters:
  `capacity` - the number of buckets in the hash table; it also defines the number of pre-allocated entries.

### Method Detail

#### size

    public int size()

Returns the number of key-value mappings in this `FastMap`.

Specified by:
  `size` in interface `Map<K,V>`
Returns:
  this map's size.

#### capacity

    public int capacity()

Returns the capacity of this `FastMap`. The capacity defines the number of buckets in the hash table, as well as the maximum number of entries the map may contain without allocating memory.

Returns:
  this map's capacity.

#### isEmpty

    public boolean isEmpty()

Indicates if this `FastMap` contains no key-value mappings.

Specified by:
  `isEmpty` in interface `Map<K,V>`
Returns:
  `true` if this map contains no key-value mappings; `false` otherwise.

#### containsKey

    public boolean containsKey(Object key)

Indicates if this `FastMap` contains a mapping for the specified key.

Specified by:
  `containsKey` in interface `Map<K,V>`
Parameters:
  `key` - the key whose presence in this map is to be tested.
Returns:
  `true` if this map contains a mapping for the specified key; `false` otherwise.
Throws:
  `NullPointerException` - if the key is `null`.

#### containsValue

    public boolean containsValue(Object value)

Indicates if this `FastMap` maps one or more keys to the specified value.

Specified by:
  `containsValue` in interface `Map<K,V>`
Parameters:
  `value` - the value whose presence in this map is to be tested.
Returns:
  `true` if this map maps one or more keys to the specified value.
Throws:
  `NullPointerException` - if the key is `null`.

#### get

    public V get(Object key)

Returns the value to which this `FastMap` maps the specified key.

Specified by:
  `get` in interface `Map<K,V>`
Parameters:
  `key` - the key whose associated value is to be returned.
Returns:
  the value to which this map maps the specified key, or `null` if there is no mapping for the key.
Throws:
  `NullPointerException` - if key is `null`.

#### getEntry

    public Map.Entry getEntry(Object key)

Returns the entry with the specified key.

Parameters:
  `key` - the key whose associated entry is to be returned.
Returns:
  the entry for the specified key or `null` if none.

#### put

    public Object put(Object key,
                      Object value)

Associates the specified value with the specified key in this `FastMap`. If the `FastMap` previously contained a mapping for this key, the old value is replaced.

Specified by:
  `put` in interface `Map<K,V>`
Parameters:
  `key` - the key with which the specified value is to be associated.
  `value` - the value to be associated with the specified key.
Returns:
  the previous value associated with specified key, or `null` if there was no mapping for key. A `null` return can also indicate that the map previously associated `null` with the specified key.
Throws:
  `NullPointerException` - if the key is `null`.

#### putAll

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

Copies all of the mappings from the specified map to this `FastMap`.

Specified by:
  `putAll` in interface `Map<K,V>`
Parameters:
  `map` - the mappings to be stored in this map.
Throws:
  `NullPointerException` - the specified map is `null`, or the specified map contains `null` keys.

#### remove

    public V remove(Object key)

Removes the mapping for this key from this `FastMap` if present.

Specified by:
  `remove` in interface `Map<K,V>`
Parameters:
  `key` - the key whose mapping is to be removed from the map.
Returns:
  previous value associated with specified key, or `null` if there was no mapping for key. A `null` return can also indicate that the map previously associated `null` with the specified key.
Throws:
  `NullPointerException` - if the key is `null`.

#### clear

    public void clear()

Removes all mappings from this `FastMap`.

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

#### setCapacity

    public void setCapacity(int newCapacity)

Changes the current capacity of this `FastMap`. If the capacity is increased, new entries are allocated and added to the pool. If the capacity is decreased, entries from the pool are deallocated (and are eventually garbage collected). The capacity also determined the number of buckets for the hash table.

Parameters:
  `newCapacity` - the new capacity of this map.

#### clone

    public Object clone()

Returns a shallow copy of this `FastMap`. The keys and the values themselves are not cloned.

Overrides:
  `clone` in class `Object`
Returns:
  a shallow copy of this map.

#### equals

    public boolean equals(Object obj)

Compares the specified object with this `FastMap` for equality. Returns `true` if the given object is also a map and the two maps represent the same mappings (regardless of collection iteration order).

Specified by:
  `equals` in interface `Map<K,V>`
Overrides:
  `equals` in class `Object`
Parameters:
  `obj` - the object to be compared for equality with this map.
Returns:
  `true` if the specified object is equal to this map; `false` otherwise.

#### hashCode

    public int hashCode()

Returns the hash code value for this `FastMap`.

Specified by:
  `hashCode` in interface `Map<K,V>`
Overrides:
  `hashCode` in class `Object`
Returns:
  the hash code value for this map.

#### toString

    public String toString()

Returns a `String` representation of this `FastMap`.

Overrides:
  `toString` in class `Object`
Returns:
  `this.entrySet().toString();`

#### values

    public Collection values()

Returns a collection view of the values contained in this `FastMap`. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the `Iterator.remove`, `Collection.remove`, `removeAll`, `retainAll`, and `clear` operations. It does not support the `add` or `addAll` operations.

Specified by:
  `values` in interface `Map<K,V>`
Returns:
  a collection view of the values contained in this map.

#### entrySet

    public Set entrySet()

Returns a collection view of the mappings contained in this `FastMap`. Each element in the returned collection is a `Map.Entry`. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the `Iterator.remove`, `Collection.remove`, `removeAll`, `retainAll`, and `clear` operations. It does not support the `add` or `addAll` operations.

Specified by:
  `entrySet` in interface `Map<K,V>`
Returns:
  a collection view of the mappings contained in this map.

#### keySet

    public Set keySet()

Returns a set view of the keys contained in this `FastMap`. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set supports element removal, which removes the corresponding mapping from this map, via the `Iterator.remove`, `Collection.remove`, `removeAll`, `retainAll`, and `clear` operations. It does not support the `add` or `addAll` operations.

Specified by:
  `keySet` in interface `Map<K,V>`
Returns:
  a set view of the keys contained in this map.

#### sizeChanged

    protected void sizeChanged()

This methods is being called when the size of this `FastMap` has changed. The default behavior is to double the map's capacity when the map's size reaches the current map's capacity. Sub-class may override this method to implement custom resizing policies or to disable automatic resizing. For example:

         Map fixedCapacityMap = new FastMap(256) {
               protected sizeChanged() {
                   // Do nothing, automatic resizing disabled.
               }
         };

See Also:
  `setCapacity(int)`