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

All Superinterfaces:

AnyReadMap<K,V>, java.io.Serializable

All Known Subinterfaces:

ListMap<K,V>, Map<K,V>, MultiMap<K,V>

All Known Implementing Classes:

AbstractBiMap, AbstractHashMap, AdapterFromJDKMap, BiMap, BiMapListToList, BiMapListToMany, BiMapManyToList, BiMapManyToMany, BiMapManyToOne, BiMapOneToMany, BiMapOneToOne, DefaultFactoryMap, DefaultFunctionMap, InlineListHashMap, InlineMultiHashMap, LockFreeHashMap, LockFreeInlineListHashMap, LockFreeInlineMultiHashMap, LockFreeLinkedHashMap, LockFreeLinkedInlineListHashMap, LockFreeLinkedInlineMultiHashMap, NestedSetListMap, NestedSetMap, NestedSetMultiMap, ScalarHashMap, SerialHashMap, SerialInlineListHashMap, SerialInlineMultiHashMap, SerialLinkedHashMap, SerialLinkedInlineListHashMap, SerialLinkedInlineMultiHashMap, SynchronizedArbitraryMap, SynchronizedListMap, SynchronizedMap, SynchronizedMultiMap

public interface AnyMap<K,V>
extends AnyReadMap<K,V>

This interface is the common ancestor of all modifiable Jjoost maps. The methods declared here make no assumptions about the number of occurrences of a given key or key->value pair.

WARNING: Note that in a MultiMap and ListMap the keys() method returns a MultiSet and as such an Iterator over this will yield each duplicate key the number of times it occurs in the map. For unique keys, call keys().unique()

Also note that an Iterator returned by concurrent implementors of this class is permitted to return values more times than they actually ever occurred if a valid sequence of deletes and inserts happens to cause the Iterator to see the values multiple times. See the javadoc of the implementing classes to determine their behaviour in this case.

Author:

b.elliottsmith

Method Summary

boolean	add(K key, V value) Attempt to add the pair to the map, returning false if it could not be added, and true otherwise.
int	clear() Clears the map, returning the number of elements removed from it.
java.util.Iterator<java.util.Map.Entry<K,V>>	clearAndReturn() Clears the map, returning the entries removed from it.
AnyMap<K,V>	copy() Returns a copy of the map.
AnySet<java.util.Map.Entry<K,V>>	entries() Returns a set representing all the key->value pairs in this map.
AnyMap<V,K>	inverse() Returns a map representing the inverse function of this map.
AnySet<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 at least once; depending on the underlying implementation this may remove any existing key->value pairs where the key is equal to the one provided (Map), the key and value are both equal (MultiMap), or simply append this key to all existing maplets regardless of their equality (ListMap).
V	putIfAbsent(K key, V val) Attempts to bind the provided key to the provided value.
int	remove(K key) Removes all occurrences of the provided key from domain of the map, returning an integer representing the total number of items removed
int	remove(K key, V val) Removes all occurrences of the provided key->value pair from the map, returning an integer representing the total number of items removed
java.lang.Iterable<java.util.Map.Entry<K,V>>	removeAndReturn(K key) Removes all occurrences of the provided key from domain of the map, returning the entries removed
java.lang.Iterable<java.util.Map.Entry<K,V>>	removeAndReturn(K key, V val) Removes all occurrences of the provided key->value pair from the map, returning the entries removed
V	removeAndReturnFirst(K key) Removes all occurrences of the provided key from domain of the map, returning the first such value removed, or null if none
void	shrink() Attempts to make the map use less memory, if possible.
AnySet<V>	values() Returns a set representing the range of the map.
AnySet<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.AnyReadMap

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

Method Detail

add

boolean add(K key,
            V value)

Attempt to add the pair to the map, returning false if it could not be added, and true otherwise. In a ListMap the return value will always be true; however in a MultiMap it will be false, and hence the map remain unmodified, if a pair whose key and value are both equal to the ones provided (as determined by the map's definitions of equality) is already present; and in a Map it will be false if a pair whose key is equal to the one provided is already present. When the value of the pair is inequal to null, this is equivalent to put(key, value) == null

Parameters:

key - key to insert

value - value to insert

Returns:

true if the map was modified, false otherwise

put

V put(K key,
      V val)

Ensures that the provided key binds to the provided value at least once; depending on the underlying implementation this may remove any existing key->value pairs where the key is equal to the one provided (Map), the key and value are both equal (MultiMap), or simply append this key to all existing maplets regardless of their equality (ListMap). If any pair is removed as a result of this action, the value of that pair is returned.

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 does not occur in the map then the value will be associated with it and null returned. If the key occurs in the map and is bound to a different value then a Map will return this value, whereas both MultiMap and ListMap will insert the new pair and return null. If the key->value pair is present in the map then all maps will return a value already associated with the key (in both Map and MultiMap there will be precisely one such value)

Parameters:

key - the key

val - the val

Returns:

implementation dependent

values

AnySet<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 AnyReadMap<K,V>

Returns:

the set of values mapped to by provided key

remove

int remove(K key)

Removes all occurrences of the provided key from domain of the map, returning an integer representing the total number of items removed

Parameters:

key - remove

Returns:

the number removed

remove

int remove(K key,
           V val)

Removes all occurrences of the provided key->value pair from the map, returning an integer representing the total number of items removed

Parameters:

key - the key

val - the val

Returns:

the number removed

removeAndReturn

java.lang.Iterable<java.util.Map.Entry<K,V>> removeAndReturn(K key)

Removes all occurrences of the provided key from domain of the map, returning the entries removed

Parameters:

key - key to remove

Returns:

entries removed

removeAndReturn

java.lang.Iterable<java.util.Map.Entry<K,V>> removeAndReturn(K key,
                                                             V val)

Removes all occurrences of the provided key->value pair from the map, returning the entries removed

Parameters:

key - key to remove

val - value to remove

Returns:

entries removed

removeAndReturnFirst

V removeAndReturnFirst(K key)

Removes all occurrences of the provided key from domain of the map, returning the first such value removed, or null if none

Parameters:

key - the key to remove

Returns:

the value associated with the first key removed, or null if none

keys

AnySet<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 AnyReadMap<K,V>

Returns:

the key set< k>

entries

AnySet<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 AnyReadMap<K,V>

Returns:

the entry set< k>

clear

int clear()

Clears the map, returning the number of elements removed from it. In a concurrent map, whilst there is no guarantee that the map will be empty when this method returns if it is being concurrently modified, the number will accurately convey the number of items removed.

Returns:

the int

clearAndReturn

java.util.Iterator<java.util.Map.Entry<K,V>> clearAndReturn()

Clears the map, returning the entries removed from it. In a concurrent map the Iterator will accurately represent the elements that are removed from the map; however the Iterator must be exhausted for the clear operation to be guaranteed to have completed.

Returns:

the iterator< entry< k, v>>

shrink

void shrink()

Attempts to make the map use less memory, if possible.

copy

AnyMap<K,V> copy()

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.

Returns:

the any map< k, v>

inverse

AnyMap<V,K> inverse()

Returns a map representing the inverse function of this map. This operation will typically be expensive unless the map is a BiMap in which case the action is trivial. The method may not return a map of the same type as the one it is called on (although typically this will be the case, and should happen wherever possible).

Returns:

the inverse map/function of the one called upon

values

AnySet<V> values()

Returns a set representing the range of the map. Operations on this set will typically be expensive (O(n) where n is the size of the map).

Specified by:

values in interface AnyReadMap<K,V>

Returns:

the range of the map