FastMap (Javolution Core (Java) 6.0.0 API)

java.lang.Object
- javolution.util.FastMap<K,V>

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

Direct Known Subclasses:: FastSortedMap

@Realtime
public class FastMap<K,V>
extends Object
implements Map<K,V>, ConcurrentMap<K,V>, Serializable

A high-performance hash map with real-time behavior. Related to FastCollection, fast map supports various views.

atomic() - Thread-safe view for which all reads are mutex-free and map updates (e.g. putAll) are atomic.
shared() - View allowing concurrent modifications.
parallel() - A view allowing parallel processing including updates.
sequential() - View disallowing parallel processing.
unmodifiable() - View which does not allow any modifications.
entrySet() - FastSet view over the map entries allowing entries to be added/removed.
keySet() - FastSet view over the map keys allowing keys to be added (map entry with null value).
values() - FastCollection view over the map values (add not supported).

The iteration order over the map keys, values or entries is deterministic (unlike HashMap). It is either the insertion order (default) or the key order for the FastSortedMap subclass. This class permits null keys.

Fast maps can advantageously replace any of the standard java.util maps.

  FastMap<Foo, Bar> hashMap = new FastMap<Foo, Bar>(); 
  FastMap<Foo, Bar> concurrentHashMap = new FastMap<Foo, Bar>().shared(); // FastMap implements ConcurrentMap interface.
  FastMap<Foo, Bar> linkedHashMap = new FastMap<Foo, Bar>(); // Deterministic iteration order (insertion order).
  FastMap<Foo, Bar> treeMap = new FastSortedMap<Foo, Bar>(); 
  FastMap<Foo, Bar> concurrentSkipListMap = new FastSortedMap<Foo, Bar>().shared();
  FastMap<Foo, Bar> identityHashMap = new FastMap<Foo, Bar>(Equalities.IDENTITY);

and adds more ...

  FastMap<Foo, Bar> atomicMap = new FastMap<Foo, Bar>().atomic(); // Mutex-free access,  all updates (e.g. putAll) atomics (unlike ConcurrentHashMap).
  FastMap<Foo, Bar> atomicTree = new FastSortedMap<Foo, Bar>().atomic(); // Mutex-free access,  all updates (e.g. putAll) atomics.
  FastMap<Foo, Bar> parallelMap = new FastMap<Foo, Bar>().parallel(); // Map actions (perform/update) performed concurrently.
  FastMap<Foo, Bar> linkedConcurrentHashMap = new FastMap<Foo, Bar>().shared(); // No equivalent in java.util !
  FastMap<String, Bar> lexicalHashMap = new FastMap<String, Bar>(Equalities.LEXICAL);  // Allows for value retrieval using any CharSequence key.
  FastMap<String, Bar> fastStringHashMap = new FastMap<String, Bar>(Equalities.LEXICAL_FAST);  // Same with faster hashcode calculations.
  ...

Of course all views (entry, key, values) over a fast map are fast collections and allow parallel processing.

 Consumer<Collection<String>> removeNull = new Consumer<Collection<String>>() {  
     public void accept(Collection<String> view) {
          Iterator<String> it = view.iterator();
          while (it.hasNext()) {
             if (it.next() == null) it.remove();
         }
     }
 };
 FastMap<Person, String> names = ...
 names.values().update(removeNull); // Remove all entries with null values.
 names.atomic().values().update(removeNull); // Same but performed atomically.
 names.parallel().values().update(removeNull); // Same but performed in parallel.

Version:: 6.0, July 21, 2013
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
Modifier	Constructor and Description
	`FastMap()` Creates an empty fast map.
	`FastMap(Equality<? super K> keyEquality)` Creates an empty fast map using the specified comparator for keys equality.
	`FastMap(Equality<? super K> keyEquality, Equality<? super V> valueEquality)` Creates an empty fast map using the specified comparators for keys equality and values equality.
`protected`	`FastMap(MapService<K,V> service)` Creates a map backed up by the specified service implementation.

Method Summary

Methods
Modifier and Type	Method and Description
`FastMap<K,V>`	`atomic()` Returns an atomic view over this map.
`void`	`clear()` Removes all this map's entries.
`boolean`	`containsKey(Object key)` Indicates if this map contains the specified key.
`boolean`	`containsValue(Object value)` Indicates if this map contains the specified value.
`FastSet<Map.Entry<K,V>>`	`entrySet()` Returns a set view of the mappings contained in this map.
`V`	`get(Object key)` Returns the value for the specified key.
`boolean`	`isEmpty()` Indicates if this map is empty
`FastSet<K>`	`keySet()` Returns a set view of the keys contained in this map.
`FastMap<K,V>`	`parallel()` Returns a parallel map.
`void`	`perform(Consumer<? extends Map<K,V>> action)` Executes the specified read-only action on this map.
`V`	`put(K key, V value)` Associates the specified value with the specified key.
`FastMap<K,V>`	`putAll(FastMap<? extends K,? extends V> that)` Returns this map with the specified map's entries added.
`void`	`putAll(Map<? extends K,? extends V> map)` Adds the specified map entries to this map.
`V`	`putIfAbsent(K key, V value)` Associates the specified value with the specified key only if the specified key has no current mapping.
`V`	`remove(Object key)` Removes the entry for the specified key.
`boolean`	`remove(Object key, Object value)` Removes the entry for a key only if currently mapped to a given value.
`V`	`replace(K key, V value)` Replaces the entry for a key only if currently mapped to some value.
`boolean`	`replace(K key, V oldValue, V newValue)` Replaces the entry for a key only if currently mapped to a given value.
`FastMap<K,V>`	`sequential()` Returns a sequential view of this collection.
`protected MapService<K,V>`	`service()` Returns this map service implementation.
`FastMap<K,V>`	`shared()` Returns a thread-safe view over this map.
`int`	`size()` Returns the number of entries/keys/values in this map.
`<T extends Map<K,V>> Immutable<T>`	`toImmutable()` Returns an immutable reference over this map.
`String`	`toString()` Returns the string representation of this map entries.
`FastMap<K,V>`	`unmodifiable()` Returns an unmodifiable view over this map.
`void`	`update(Consumer<? extends Map<K,V>> action)` Executes the specified update action on this map.
`FastCollection<V>`	`values()` Returns a collection view of the values contained in this map.

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

- Constructor Detail
  - FastMap
```
public FastMap()
```
    Creates an empty fast map.
  - FastMap
```
public FastMap(Equality<? super K> keyEquality)
```
    Creates an empty fast map using the specified comparator for keys equality.
  - FastMap
```
public FastMap(Equality<? super K> keyEquality,
       Equality<? super V> valueEquality)
```
    Creates an empty fast map using the specified comparators for keys equality and values equality.
  - FastMap
```
protected FastMap(MapService<K,V> service)
```
    Creates a map backed up by the specified service implementation.
- Method Detail
  - atomic
```
@Parallelizable(mutexFree=true,
                comment="Except for write operations, all read operations are mutex-free.")
public FastMap<K,V> atomic()
```
    Returns an atomic view over this map. All operations that write or access multiple elements in the map (such as putAll(), keySet().retainAll(), ...) are atomic. Iterators on atomic collections are thread-safe (no ConcurrentModificationException possible).
  - shared
```
@Parallelizable(mutexFree=false,
                comment="Use multiple-readers/single-writer lock.")
public FastMap<K,V> shared()
```
    Returns a thread-safe view over this map. The shared view allows for concurrent read as long as there is no writer. The default implementation is based on readers-writers locks giving priority to writers. Iterators on shared collections are thread-safe (no ConcurrentModificationException possible).
  - parallel
```
public FastMap<K,V> parallel()
```
    Returns a parallel map. Parallel maps affect closure-based operations over the map or any of its views (entry, key, values, etc.), all others operations behaving the same. Parallel maps do not require this map to be thread-safe (internal synchronization).
    
    See Also:
    perform(Consumer), update(Consumer), FastCollection.parallel()
  - sequential
```
public FastMap<K,V> sequential()
```
    Returns a sequential view of this collection. Using this view, all closure-based iterations are performed sequentially.
  - unmodifiable
```
public FastMap<K,V> unmodifiable()
```
    Returns an unmodifiable view over this map. Any attempt to modify the map through this view will result into a UnsupportedOperationException being raised.
  - keySet
```
public FastSet<K> keySet()
```
    Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set supports adding new keys for which the corresponding entry value is always null.
    
    Specified by:
    
    keySet in interface Map<K,V>
  - values
```
public FastCollection<V> values()
```
    Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports removing values (hence entries) but not adding new values.
    
    Specified by:
    
    values in interface Map<K,V>
  - entrySet
```
public FastSet<Map.Entry<K,V>> entrySet()
```
    Returns a set view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set support adding/removing entries. As far as the set is concerned, two entries are considered equals if they have the same keys regardless of their values.
    
    Specified by:
    
    entrySet in interface Map<K,V>
  - perform
```
@Realtime(limit=LINEAR)
public void perform(Consumer<? extends Map<K,V>> action)
```
    Executes the specified read-only action on this map. That logic may be performed concurrently on sub-maps if this map is parallel.
    
    Parameters:
    action - the read-only action.
    
    Throws:
    
    UnsupportedOperationException - if the action tries to update this map.
    
    ClassCastException - if the action type is not compatible with this map (e.g. action on sorted map and this is a hash map).
    See Also:
    update(Consumer)
  - update
```
@Realtime(limit=LINEAR)
public void update(Consumer<? extends Map<K,V>> action)
```
    Executes the specified update action on this map. That logic may be performed concurrently on sub-maps if this map is parallel. For atomic maps the update is atomic (either concurrent readers see the full result of the action or nothing).
    
    Parameters:
    action - the update action.
    
    Throws:
    
    ClassCastException - if the action type is not compatible with this map (e.g. action on sorted map and this is a hash map).
    See Also:
    perform(Consumer)
  - size
```
@Realtime(limit=CONSTANT)
public int size()
```
    Returns the number of entries/keys/values in this map.
    
    Specified by:
    
    size in interface Map<K,V>
  - isEmpty
```
@Realtime(limit=CONSTANT)
public boolean isEmpty()
```
    Indicates if this map is empty
    
    Specified by:
    
    isEmpty in interface Map<K,V>
  - containsKey
```
@Realtime(limit=CONSTANT)
public boolean containsKey(Object key)
```
    Indicates if this map contains the specified key.
    
    Specified by:
    
    containsKey in interface Map<K,V>
  - containsValue
```
@Realtime(limit=LINEAR)
public boolean containsValue(Object value)
```
    Indicates if this map contains the specified value.
    
    Specified by:
    
    containsValue in interface Map<K,V>
  - get
```
@Realtime(limit=CONSTANT)
public V get(Object key)
```
    Returns the value for the specified key.
    
    Specified by:
    
    get in interface Map<K,V>
  - put
```
@Realtime(limit=CONSTANT)
public V put(K key,
                          V value)
```
    Associates the specified value with the specified key.
    
    Specified by:
    
    put in interface Map<K,V>
  - putAll
```
@Realtime(limit=LINEAR)
public void putAll(Map<? extends K,? extends V> map)
```
    Adds the specified map entries to this map.
    
    Specified by:
    
    putAll in interface Map<K,V>
  - remove
```
@Realtime(limit=CONSTANT)
public V remove(Object key)
```
    Removes the entry for the specified key.
    
    Specified by:
    
    remove in interface Map<K,V>
  - clear
```
@Realtime(limit=CONSTANT)
public void clear()
```
    Removes all this map's entries.
    
    Specified by:
    
    clear in interface Map<K,V>
  - putIfAbsent
```
@Realtime(limit=CONSTANT)
public V putIfAbsent(K key,
                                  V value)
```
    Associates the specified value with the specified key only if the specified key has no current mapping.
    
    Specified by:
    
    putIfAbsent in interface ConcurrentMap<K,V>
  - remove
```
@Realtime(limit=CONSTANT)
public boolean remove(Object key,
                                   Object value)
```
    Removes the entry for a key only if currently mapped to a given value.
    
    Specified by:
    
    remove in interface ConcurrentMap<K,V>
  - replace
```
@Realtime(limit=CONSTANT)
public boolean replace(K key,
                                    V oldValue,
                                    V newValue)
```
    Replaces the entry for a key only if currently mapped to a given value.
    
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
  - replace
```
@Realtime(limit=CONSTANT)
public V replace(K key,
                              V value)
```
    Replaces the entry for a key only if currently mapped to some value.
    
    Specified by:
    
    replace in interface ConcurrentMap<K,V>
  - putAll
```
public FastMap<K,V> putAll(FastMap<? extends K,? extends V> that)
```
    Returns this map with the specified map's entries added.
  - toImmutable
```
public <T extends Map<K,V>> Immutable<T> toImmutable()
```
    Returns an immutable reference over this map. The immutable value is an unmodifiable view of this map for which the caller guarantees that no change will ever be made (e.g. there is no reference left to the original map).
  - toString
```
@Realtime(limit=LINEAR)
public String toString()
```
    Returns the string representation of this map entries.
    
    Overrides:
    
    toString in class Object
  - service
```
protected MapService<K,V> service()
```
    Returns this map service implementation.

Class FastMap<K,V>

Nested Class Summary

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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Constructor Detail

FastMap

FastMap

FastMap

FastMap

Method Detail

atomic

shared

parallel

sequential

unmodifiable

keySet

values

entrySet

perform

update

size

isEmpty

containsKey

containsValue

get

put

putAll

remove

clear

putIfAbsent

remove

replace

replace

putAll

toImmutable

toString

service