org.jjoost.collections
Interface MultiMap<K,V>

All Superinterfaces:

AnyMap<K,V>, AnyReadMap<K,V>, Function<K,java.lang.Iterable<V>>, java.io.Serializable

All Known Implementing Classes:

BiMapManyToList, BiMapManyToMany, BiMapManyToOne, InlineMultiHashMap, LockFreeInlineMultiHashMap, LockFreeLinkedInlineMultiHashMap, NestedSetMultiMap, SerialInlineMultiHashMap, SerialLinkedInlineMultiHashMap, SynchronizedMultiMap

public interface MultiMap<K,V>
extends AnyMap<K,V>, Function<K,java.lang.Iterable<V>>

This interface declares a map that permits duplicate keys, but no duplicate key->value pairs, i.e. a key can map to an arbitrary set of values wherein no value occurs more than once

Method Summary

MultiMap<K,V>	copy() Returns a copy of the map.
Set<java.util.Map.Entry<K,V>>	entries() Returns a set representing all the key->value pairs in this map.
MultiSet<K>	keys() Returns a set representing all the keys in the domain of this map.
V	put(K key, V val) Ensures that the provided key binds to the provided value, removing any existing key->value pair where the key is equal to the one provided.
V	putIfAbsent(K key, V val) Attempts to bind the provided key to the provided value.
Set<V>	values(K key) Returns a set representing the values associated with the provided key in this map.

Methods inherited from interface org.jjoost.collections.AnyMap

add, clear, clearAndReturn, inverse, remove, remove, removeAndReturn, removeAndReturn, removeAndReturnFirst, shrink, values

Methods inherited from interface org.jjoost.collections.AnyReadMap

contains, contains, count, count, entries, first, isEmpty, list, permitsDuplicateKeys, totalCount, uniqueKeyCount

Methods inherited from interface org.jjoost.util.Function

apply

Method Detail

put

V put(K key,
      V val)

Ensures that the provided key binds to the provided value, removing any existing key->value pair where the key is equal to the one provided. If any pair is removed as a result of this action, the value of that pair is returned.

Specified by:

put in interface AnyMap<K,V>

Parameters:

key - the key

val - the val

Returns:

the value of any maplet removed as a result of this action

putIfAbsent

V putIfAbsent(K key,
              V val)

Attempts to bind the provided key to the provided value. If the key->value pair already occurs in the map then the value of this pair is returned and the map is not modified, otherwise the provided pair is inserted and null returned

Specified by:

putIfAbsent in interface AnyMap<K,V>

Parameters:

key - the key

val - the val

Returns:

the value of any maplet removed as a result of this action

values

Set<V> values(K key)

Description copied from interface: AnyReadMap

Returns a set representing the values associated with the provided key in this map. This set should always reflect changes to the map, and changes to the set should be reflected in the map also. Otherwise, this set should behave exactly as a regular set does.

Note that in a regular (scalar) map the set returned will be a UnitarySet, which contains at most one value. put() operations on such a set will override any existing value regardless of if it is equal to the one already present.

Specified by:

values in interface AnyMap<K,V>

Specified by:

values in interface AnyReadMap<K,V>

Returns:

the set of values mapped to by provided key

keys

MultiSet<K> keys()

Description copied from interface: AnyReadMap

Returns a set representing all the keys in the domain of this map. In a MultiMap or ListMap this will be a MultiSet. This set should always reflect changes to the map, and changes to the set should be reflected in the map also. Otherwise, this set should behave exactly as a regular set does. The key equality used by this map can be obtained from this set.

Depending on the implementation of map, this key set may contain every occurrence of equal keys provided to the map, or may contain a subset thereof with repetitions to bring the number of occurrences in line with the number provided.

Note that the put() methods on this set will always fail, because no value can be provided to update the map with.

Specified by:

keys in interface AnyMap<K,V>

Specified by:

keys in interface AnyReadMap<K,V>

Returns:

the key set< k>

entries

Set<java.util.Map.Entry<K,V>> entries()

Description copied from interface: AnyReadMap

Returns a set representing all the key->value pairs in this map. In a ListMap this will be a MultiSet. This set should always reflect changes to the map, and changes to the set should be reflected in the map also. Otherwise, this set should behave exactly as a regular set does.

Specified by:

entries in interface AnyMap<K,V>

Specified by:

entries in interface AnyReadMap<K,V>

Returns:

the entry set< k>

copy

MultiMap<K,V> copy()

Description copied from interface: AnyMap

Returns a copy of the map. Note that this method may not necessarily return an object of the same class as the one it is called upon, but will return one indistinguishable from it with respect to all method calls.

Specified by:

copy in interface AnyMap<K,V>

Returns:

the any map< k, v>