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

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

AnyMap<K,V>, 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 AnyReadMap<K,V>
extends java.io.Serializable

This interface is the common ancestor of all Jjoost maps.

The methods declared here make no assumptions about the number of occurences of a given key or key->value pair, and declare no actions that may modify the map, so is the most general form of map. No concrete class should implement this interface directly.

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	contains(K key) Returns true iff a key occurs in the map which is equal to the parameter, as determined by the map's definition of equality.
boolean	contains(K key, V val) Returns true iff a (key,value) pair occurs in the map that is equal to those provided, as determined by the map's definition(s) of equality.
int	count(K key) Returns the number of occurrences of keys present in the map that are equal to the one provided, as determined by the map's definition of equality.
int	count(K key, V val) Returns the number of occurrences of (key, value) pairs present in the map that are equal to the one provided, as determined by the map's definition(s) of equality.
AnyReadSet<? extends java.util.Map.Entry<K,V>>	entries() Returns a set representing all the key->value pairs in this map.
java.lang.Iterable<java.util.Map.Entry<K,V>>	entries(K key) Returns an Iterable over all key->value maplets in the map whose key is equal to the one provided, as determined by the map's definition of equality.
V	first(K key) Returns the value associated with the first key that is equal to the one provided, as determined by the map's definition of equality.
boolean	isEmpty() Returns true iff the map is empty
AnyReadSet<K>	keys() Returns a set representing all the keys in the domain of this map.
java.util.List<V>	list(K key) Returns a List of all values in the map which are mapped to by the provided key, as determined by the map's definition of equality.
boolean	permitsDuplicateKeys() Returns true if a key can map to more than one value
int	totalCount() Return an integer representing the total number of maplets (i.e.
int	uniqueKeyCount() Return an integer representing the number of unique keys in the domain of the map
AnyReadSet<V>	values() Returns a set representing the range of the map.
AnyReadSet<V>	values(K key) Returns a set representing the values associated with the provided key in this map.

Method Detail

contains

boolean contains(K key)

Returns true iff a key occurs in the map which is equal to the parameter, as determined by the map's definition of equality.

Parameters:

key - find

Returns:

true, if present

contains

boolean contains(K key,
                 V val)

Returns true iff a (key,value) pair occurs in the map that is equal to those provided, as determined by the map's definition(s) of equality.

Parameters:

key - the key

val - the val

Returns:

true, if present

count

int count(K key)

Returns the number of occurrences of keys present in the map that are equal to the one provided, as determined by the map's definition of equality.

Parameters:

key - the key

Returns:

number of occurrences

count

int count(K key,
          V val)

Returns the number of occurrences of (key, value) pairs present in the map that are equal to the one provided, as determined by the map's definition(s) of equality.

Parameters:

key - the key

val - the val

Returns:

number of occurrences

first

V first(K key)

Returns the value associated with the first key that is equal to the one provided, as determined by the map's definition of equality. Returns null if no matching key is found.

Parameters:

key - the key

Returns:

the value associated with the first matching key

values

AnyReadSet<V> values(K key)

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.

Returns:

the set of values mapped to by provided key

list

java.util.List<V> list(K key)

Returns a List of all values in the map which are mapped to by the provided key, as determined by the map's definition of equality. This list should be constructed "eagerly" and should be a consistent snapshot of the values valid at some point between the method being called and it returning.

Parameters:

key - the key

Returns:

the list< v>

keys

AnyReadSet<K> keys()

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.

Returns:

the key set< k>

entries

AnyReadSet<? extends java.util.Map.Entry<K,V>> entries()

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.

Returns:

the entry set< k>

values

AnyReadSet<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). The value equality used by this map can be obtained from this set.

Returns:

the range of the map

entries

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

Returns an Iterable over all key->value maplets in the map whose key is equal to the one provided, as determined by the map's definition of equality.

Parameters:

key - find

Returns:

maplets with the provided key

totalCount

int totalCount()

Return an integer representing the total number of maplets (i.e. counting all occurrences of each key) in the map

Returns:

the total number of maplets

uniqueKeyCount

int uniqueKeyCount()

Return an integer representing the number of unique keys in the domain of the map

Returns:

number of unique keys

isEmpty

boolean isEmpty()

Returns true iff the map is empty

Returns:

true, if empty

permitsDuplicateKeys

boolean permitsDuplicateKeys()

Returns true if a key can map to more than one value

Returns:

true, if keys can map to more than one value