Package org.apache.juneau.commons.collections

Class BidiMap<K,V>

java.lang.Object
org.apache.juneau.commons.collections.BidiMap<K,V>
Type Parameters:
K - The key type.
V - The value type.
All Implemented Interfaces:
Map<K,V>
public class BidiMap<K,V> extends Object implements Map<K,V>
A bidirectional map with reverse key lookup by value.

This implementation provides efficient bidirectional lookups by maintaining two internal maps: a forward map for key-to-value lookups and a reverse map for value-to-key lookups.

Features:
  • Implements the standard Map interface for forward key→value lookups
  • Provides getKey(Object) method for reverse value→key lookups
  • Maintains insertion order using LinkedHashMap internally
  • Automatically filters out null keys and values
  • Supports both mutable and unmodifiable instances via the builder
  • Thread-safety: Not thread-safe by default; external synchronization required if accessed by multiple threads
Usage:

// Create a bidirectional map BidiMap<String,Integer> map = BidiMap.create() .add("one", 1) .add("two", 2) .add("three", 3) .build(); // Forward lookup: key → value Integer value = map.get("two"); // Returns 2 // Reverse lookup: value → key String key = map.getKey(2); // Returns "two"

Null Handling:

This map automatically filters out entries with null keys or values during construction. Attempting to add null keys or values via put(Object, Object) or putAll(Map) after construction will result in them being stored in the forward map but not the reverse map.

Unmodifiable Instances:

// Create an unmodifiable bidirectional map BidiMap<String,Integer> map = BidiMap.create() .add("one", 1) .add("two", 2) .unmodifiable() .build();

See Also:

  • Constructor Details

    • BidiMap

      public BidiMap(BidiMap.Builder<K,V> builder)
      Constructor.

      Constructs a bidirectional map from the provided builder, automatically filtering out any entries with null keys or values.

      Parameters:
      builder - The builder containing the initial entries.

  • Method Details

    • create

      public static <K, V> BidiMap.Builder<K,V> create()
      Creates a new builder for this class.
      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new BidiMap.Builder instance.

    • clear

      public void clear()
      Removes all key-value mappings from this map.

      Clears both the forward and reverse maps.

      Specified by:
      clear in interface Map<K,V>
      Throws:
      UnsupportedOperationException - if the map is unmodifiable.

    • containsKey

      public boolean containsKey(Object key)
      Returns true if this map contains a mapping for the specified key.
      Specified by:
      containsKey in interface Map<K,V>
      Parameters:
      key - The key to check for.
      Returns:
      true if this map contains a mapping for the specified key.

    • containsValue

      public boolean containsValue(Object value)
      Returns true if this map maps one or more keys to the specified value.

      This implementation uses the reverse map for efficient lookup.

      Specified by:
      containsValue in interface Map<K,V>
      Parameters:
      value - The value to check for.
      Returns:
      true if this map maps one or more keys to the specified value.

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Returns a Set view of the mappings contained in this map.
      Specified by:
      entrySet in interface Map<K,V>
      Returns:
      A set view of the mappings contained in this map.

    • get

      public V get(Object key)
      Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
      Specified by:
      get in interface Map<K,V>
      Parameters:
      key - The key whose associated value is to be returned.
      Returns:
      The value to which the specified key is mapped, or null if this map contains no mapping for the key.

    • getKey

      public K getKey(V value)
      Returns the key that is currently mapped to the specified value.

      This is the reverse lookup operation that makes this a bidirectional map.

      Example:

      BidiMap<String,Integer> map = BidiMap.create().add("two", 2).build(); String key = map.getKey(2); // Returns "two"

      Parameters:
      value - The value whose associated key is to be returned.
      Returns:
      The key to which the specified value is mapped, or null if this map contains no mapping for the value.

    • isEmpty

      public boolean isEmpty()
      Returns true if this map contains no key-value mappings.
      Specified by:
      isEmpty in interface Map<K,V>
      Returns:
      true if this map contains no key-value mappings.

    • keySet

      public Set<K> keySet()
      Returns a Set view of the keys contained in this map.
      Specified by:
      keySet in interface Map<K,V>
      Returns:
      A set view of the keys contained in this map.

    • put

      public V put(K key, V value)
      Associates the specified value with the specified key in this map.

      This operation updates both the forward map (key→value) and the reverse map (value→key).

      Specified by:
      put in interface Map<K,V>
      Parameters:
      key - The key with which the specified value is to be associated.
      value - The value to be associated with the specified key.
      Returns:
      The previous value associated with the key, or null if there was no mapping for the key.
      Throws:
      UnsupportedOperationException - if the map is unmodifiable.
      IllegalArgumentException - if the value already exists mapped to a different key.

    • putAll

      public void putAll(Map<? extends K,? extends V> m)
      Copies all mappings from the specified map to this map.

      This operation updates both the forward and reverse maps.

      Specified by:
      putAll in interface Map<K,V>
      Parameters:
      m - Mappings to be stored in this map.
      Throws:
      UnsupportedOperationException - if the map is unmodifiable.
      IllegalArgumentException - if any value in the map already exists mapped to a different key.

    • remove

      public V remove(Object key)
      Removes the mapping for a key from this map if it is present.

      This operation removes the entry from both the forward and reverse maps.

      Specified by:
      remove in interface Map<K,V>
      Parameters:
      key - The key whose mapping is to be removed from the map.
      Returns:
      The previous value associated with the key, or null if there was no mapping for the key.
      Throws:
      UnsupportedOperationException - if the map is unmodifiable.

    • size

      public int size()
      Returns the number of key-value mappings in this map.
      Specified by:
      size in interface Map<K,V>
      Returns:
      The number of key-value mappings in this map.

    • values

      public Collection<V> values()
      Returns a Collection view of the values contained in this map.
      Specified by:
      values in interface Map<K,V>
      Returns:
      A collection view of the values contained in this map.

    • toString

      public String toString()
      Returns a string representation of this map.

      The format follows the standard Java map convention: "{key1=value1, key2=value2, ...}"

      Overrides:
      toString in class Object
      Returns:
      A string representation of this map.

    • equals

      public boolean equals(Object o)
      Compares the specified object with this map for equality.

      Returns true if the given object is also a map and the two maps represent the same mappings. More formally, two maps m1 and m2 represent the same mappings if m1.entrySet().equals(m2.entrySet()).

      This implementation compares the entry sets of the two maps.

      Specified by:
      equals in interface Map<K,V>
      Overrides:
      equals in class Object
      Parameters:
      o - Object to be compared for equality with this map.
      Returns:
      true if the specified object is equal to this map.

    • hashCode

      public int hashCode()
      Returns the hash code value for this map.

      The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view. This ensures that m1.equals(m2) implies that m1.hashCode()==m2.hashCode() for any two maps m1 and m2, as required by the general contract of Object.hashCode().

      This implementation computes the hash code from the entry set.

      Specified by:
      hashCode in interface Map<K,V>
      Overrides:
      hashCode in class Object
      Returns:
      The hash code value for this map.