bb.util
Class BidirectionalMap

java.lang.Object
  extended by bb.util.BidirectionalMap

public class BidirectionalMap
extends Object

An object that provides a way to associate pairs of Objects.

Ordinary Maps provide a one-way association: key-->value. This class provides a stronger two-way association: object1<-->object2. In other words, there is no distinction between keys and values: once an association has been established between 2 Objects, either one may be used as a key to retrieve the other. A side effect of this strong association is that a given Object may only be associated with at most one other Object at a given time in a given BidirectionalMap instance. (In contrast, with ordinary Maps, keys must be unique but values need not be.)

This class offers the obvious methods: put, contains, get, remove, removeIfPresent.

The capacity of the internal data structures of this class will always grow (up to memory limits) to accomodate any number of associations.

This class is not multithread safe.

Author:
Brent Boyer

Nested Class Summary
static class BidirectionalMap.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
protected static int capacityInitial_default
           
protected static float loadFactor_default
           
private  Map<Object,Object> map
           
 
Constructor Summary
BidirectionalMap()
          Constructs a new BidirectionalMap instance; simply calls this(capacityInitial_default).
BidirectionalMap(int initialCapacity)
          Constructs a new BidirectionalMap instance; simply calls this(initialCapacity, loadFactor_default).
BidirectionalMap(int initialCapacity, float loadFactor)
          Constructs a new BidirectionalMap instance with the specified initial capacity and load factor.
 
Method Summary
 boolean contains(Object object)
          Determines whether or not this instance contains object (i.e. whether or not object is currently associated with anything).
 Object get(Object object)
          Returns the partner Object that has been associated with object.
protected  boolean isReverseMapped(Object key, Object keysPartner)
          Determines whether or not the reverse map of keysPartner-->key exists in this BidirectionalMap instance.
 void put(Object object1, Object object2)
          Establishes an association (i.e. a bidirectional map) between object1 and object2.
 Object remove(Object object)
          Completely unmaps object from its partner.
 void removeIfPresent(Object object)
          Completely unmaps object from its partner, if an association exists.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

capacityInitial_default

protected static final int capacityInitial_default
See Also:
Constant Field Values

loadFactor_default

protected static final float loadFactor_default
See Also:
Constant Field Values

map

private final Map<Object,Object> map
Constructor Detail

BidirectionalMap

public BidirectionalMap(int initialCapacity,
                        float loadFactor)
Constructs a new BidirectionalMap instance with the specified initial capacity and load factor.

The initialCapacity and loadFactor arguments are strictly for performance tuning. For instance, if a good estimate exists for the number of associations, then specifying it via initialCapacity may lead to fewer resize operations in the internal data structures. Similarly, the loadFactor parameter specifies the trade off between wasted storage space versus potential resize operations in the internal data structures. These parameters have the same meaning as in the HashMap class.

Parameters:
initialCapacity - the initial number of associations that this instance will have the capacity for
loadFactor - a measure of how full the internal data storage structures are allowed to get before their capacity is automatically increased

BidirectionalMap

public BidirectionalMap(int initialCapacity)
Constructs a new BidirectionalMap instance; simply calls this(initialCapacity, loadFactor_default).


BidirectionalMap

public BidirectionalMap()
Constructs a new BidirectionalMap instance; simply calls this(capacityInitial_default).

Method Detail

put

public void put(Object object1,
                Object object2)
         throws IllegalArgumentException
Establishes an association (i.e. a bidirectional map) between object1 and object2. Any previous association involving object1 is first removed, and likewise with object2. Either arg may be null. The order of the args is irrelevant for establishing the bidirectional map.

Throws:
IllegalArgumentException

contains

public boolean contains(Object object)
Determines whether or not this instance contains object (i.e. whether or not object is currently associated with anything).


get

public Object get(Object object)
           throws IllegalArgumentException
Returns the partner Object that has been associated with object.

Throws:
IllegalArgumentException - if object is not currently associated with anything

remove

public Object remove(Object object)
              throws IllegalArgumentException
Completely unmaps object from its partner.

Note: the disassociation is done in both directions (object-->partner and partner-->object) so that there is no need (indeed, it is an error) to subsequently call remove(partner).

Returns:
the partner that used to be associated with object
Throws:
IllegalArgumentException - if object is not currently associated with anything

removeIfPresent

public void removeIfPresent(Object object)
Completely unmaps object from its partner, if an association exists. Else, if object has no association, this method does nothing.

Note: the disassociation, if performed, is done in both directions (object-->partner and partner-->object) so that there is no need to subsequently call removeIfPresent(partner).


isReverseMapped

protected boolean isReverseMapped(Object key,
                                  Object keysPartner)
Determines whether or not the reverse map of keysPartner-->key exists in this BidirectionalMap instance. The purpose of this method is to enable consistency checks on the internal state of this BidirectionalMap.