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."