gumbo.util
Interface GroupBimap

All Superinterfaces:
Bimap, java.util.Map
All Known Implementing Classes:
AbstractGroupBimap

public interface GroupBimap
extends Bimap

A bimap whose values are maintained in groups associated with the keys. Efficiently maps a key (Object) to a group (Group) of one or more values (Object), and a value to a set (Set) of one or more keys. The identity (equals(), hashCode()) of a bimap is that of its key-to-value map store, plus an instanceof test for Bimap. Unlike a Map, all views are immutable unless otherwise noted by a given implementation.

Todo: Refactor so that entrySet() works according to Map, null keys and values are allowed, and groups can be a Set or List.

Version:
$Revision: 1.3 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary
 
Nested classes inherited from class java.util.Map
java.util.Map.Entry
 
Method Summary
 void addAll(java.util.Collection keys, int index, java.util.Collection values)
          Adds all the values to the groups associated with all the keys.
 void addAll(java.util.Map map)
          Adds all the entries in the map to this one.
 void addAllKeys(java.util.Collection keys, int index, java.lang.Object value)
          Adds a value to the groups associated with all the keys.
 void addAllValues(java.lang.Object key, int index, java.util.Collection values)
          Adds all the values to the group associated with a key.
 void addValue(java.lang.Object key, int index, java.lang.Object value)
          Adds a value to the group associated with a key.
 java.util.Set entrySet()
          Gets an immutable view of the key-value entries (Map.Entry) in this bimap.
 java.lang.Object get(java.lang.Object key)
          If the value group storage is a list, gets the value at the head of the list associated with the key.
 GroupBimap getGroupBimap()
          Gets a singleton immutable view of this group bimap.
 Group getValues(java.lang.Object key)
          Gets an immutable snapshot of the values (Object) associated with a key.
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          If the value group storage is a list, adds the value to the head of the list associated with the key.
 void putAll(java.util.Map t)
          If the value group storage is a list, adds a map value to the head of the list associated with a key.
 java.lang.Object remove(java.lang.Object key)
          Removes the values associated with a key.
 void removeAll(java.util.Collection keys, java.util.Collection values)
          Removes all the values from the groups associated with all the keys.
 void removeAllKeys(java.util.Collection keys, java.lang.Object value)
          Removes a value from the groups associated with all the keys.
 void removeAllValues(java.lang.Object key, java.util.Collection values)
          Removes all the values from the group associated with a key.
 void removeValue(java.lang.Object key, java.lang.Object value)
          Removes a value from the group associated with a key.
 java.util.Collection values()
          If the value group storage is a list, gets the values at the head of the lists associated with the keys.
 
Methods inherited from interface gumbo.util.Bimap
getBimap, getKeys, keySet, removeAllKeys, removeAllValues, removeKey, removeValue, valueSet
 
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, equals, hashCode, isEmpty, size
 

Method Detail

addValue

public void addValue(java.lang.Object key,
                     int index,
                     java.lang.Object value)
Adds a value to the group associated with a key. Some stores (such as SetList) may throw an exception when attempting to add a duplicate member.

Parameters:
key - Value group key. Never null.
index - List index. If not backed by a list, < 0. If backed by a list, <= group size, with < 0 being the end of the list.
value - Value to be added. Ignored if null.
Throws:
java.lang.UnsupportedOperationException - If the group store is not a List and index >= 0.

addAllValues

public void addAllValues(java.lang.Object key,
                         int index,
                         java.util.Collection values)
Adds all the values to the group associated with a key.


addAllKeys

public void addAllKeys(java.util.Collection keys,
                       int index,
                       java.lang.Object value)
Adds a value to the groups associated with all the keys.


addAll

public void addAll(java.util.Collection keys,
                   int index,
                   java.util.Collection values)
Adds all the values to the groups associated with all the keys.


addAll

public void addAll(java.util.Map map)
Adds all the entries in the map to this one. If the map is a GroupBimap, its group values will be added.


removeValue

public void removeValue(java.lang.Object key,
                        java.lang.Object value)
Removes a value from the group associated with a key. If the group is not backed by a set, only the first instance is removed (see List.remove()).

Parameters:
key - Value group key. Never null.
value - Value to be removed. Ignored if null or missing.

removeAllValues

public void removeAllValues(java.lang.Object key,
                            java.util.Collection values)
Removes all the values from the group associated with a key.


removeAllKeys

public void removeAllKeys(java.util.Collection keys,
                          java.lang.Object value)
Removes a value from the groups associated with all the keys.


removeAll

public void removeAll(java.util.Collection keys,
                      java.util.Collection values)
Removes all the values from the groups associated with all the keys.


getValues

public Group getValues(java.lang.Object key)
Gets an immutable snapshot of the values (Object) associated with a key. Similar to get(Object).


getGroupBimap

public GroupBimap getGroupBimap()
Gets a singleton immutable view of this group bimap. To avoid unnecessary lazy builds, if possible, use other accessors instead of this view.

Returns:
The view. Never null.

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
If the value group storage is a list, adds the value to the head of the list associated with the key. A list is required so that put() and get() work as expected. TODO: Refactor to allow list or set store.

Specified by:
put in interface java.util.Map
Returns:
The value previously returned by get(key). Null if none.
Throws:
java.lang.UnsupportedOperationException - Value group storage is not a list. Use addValue().

putAll

public void putAll(java.util.Map t)
If the value group storage is a list, adds a map value to the head of the list associated with a key. A list is required so that put() and get() work as expected.

Specified by:
putAll in interface java.util.Map
Throws:
java.lang.UnsupportedOperationException - Value group storage is not a list. Use addAll().

get

public java.lang.Object get(java.lang.Object key)
If the value group storage is a list, gets the value at the head of the list associated with the key. A list is required so that put() and get() work as expected. TODO: Refactor to allow list or set store.

Specified by:
get in interface java.util.Map
Returns:
The value. Null if none.
Throws:
java.lang.UnsupportedOperationException - Value group storage is not a list. Use getValues().

remove

public java.lang.Object remove(java.lang.Object key)
Removes the values associated with a key. If the value group storage is a list, returns the value at the head of the list associated with the key; otherwise, returns the discarded value group.

Specified by:
remove in interface java.util.Map
Returns:
The value. Null if none.

values

public java.util.Collection values()
If the value group storage is a list, gets the values at the head of the lists associated with the keys. A list is required so that put() and get() work as expected. TODO: Refactor to allow list or set store.

Specified by:
values in interface Bimap
Returns:
An immutable snapshot in key iterator order. Never null.
Throws:
java.lang.UnsupportedOperationException - Value group storage is not a list. Use valueSet().

entrySet

public java.util.Set entrySet()
Description copied from interface: Bimap
Gets an immutable view of the key-value entries (Map.Entry) in this bimap.

Specified by:
entrySet in interface Bimap
Throws:
java.lang.UnsupportedOperationException - Map entry values are private groups. Public access is not allowed."