Package org.apache.juneau.commons.collections

Class SimpleMap<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
org.apache.juneau.commons.collections.SimpleMap<K,V>
Type Parameters:
K - The key type.
V - The value type.
All Implemented Interfaces:
Map<K,V>
public class SimpleMap<K,V> extends AbstractMap<K,V>
An unmodifiable, fixed-size map implementation backed by parallel key and value arrays.

This class provides a simple, efficient, immutable map implementation for scenarios where the set of keys and values is known in advance and doesn't need to change. It's particularly useful for small maps (typically less than 10 entries) where the overhead of a HashMap is not justified.

Features:
  • Unmodifiable: All mutation operations throw UnsupportedOperationException
  • Fixed Keys and Values: Keys and values are set at construction time
  • Insertion Order: Preserves the order of keys as provided in the constructor
  • Null Support: Supports null keys and values (unlike Map.of())
  • Array-Backed: Uses simple arrays for storage, avoiding hash computation overhead
  • Memory Efficient: Minimal memory footprint compared to HashMap
  • Predictable Performance: O(n) lookup time, but faster than HashMap for small n
Use Cases:
  • Immutable configuration maps with a fixed set of known keys
  • Small lookup tables that should not be modified
  • Method return values where immutability is desired
  • Situations where map size is small and keys are known at compile time
Usage:

// Create an unmodifiable map with fixed keys and values String[] keys = {"host", "port", "timeout"}; Object[] values = {"localhost", 8080, 30000}; SimpleMap<String,Object> config = new SimpleMap<>(keys, values); // Get values String host = (String)config.get("host"); // Returns: "localhost" Integer port = (Integer)config.get("port"); // Returns: 8080 // Cannot modify config.put("port", 9090); // Throws UnsupportedOperationException

Restrictions:
  • Immutable: Cannot add, remove, or modify entries after construction
  • Fixed Size: Size is determined at construction time
  • Unique Keys: Keys must be unique (no duplicates)
  • Array Length: Keys and values arrays must have the same length
Performance Characteristics:
  • get(key): O(n) - Linear search through keys array
  • size(): O(1) - Direct array length access
  • Memory: Lower overhead than HashMap for small maps
Thread Safety:

This class is thread-safe since it's immutable after construction. Multiple threads can safely read from a SimpleMap concurrently without synchronization.

Example - Configuration Map:

// Create immutable configuration SimpleMap<String,Object> defaults = new SimpleMap<>( new String[]{"maxConnections", "timeout", "retries"}, new Object[]{100, 5000, 3} ); // Safe to share across threads return defaults;

Comparison with Map.of():
  • Null Support: SimpleMap supports null keys/values, Map.of() does not
  • Insertion Order: SimpleMap preserves insertion order, Map.of() does not
  • Size Limit: Map.of() limited to 10 entries, SimpleMap has no limit
See Also:

  • Constructor Details

    • SimpleMap

      public SimpleMap(K[] keys, V[] values)
      Constructs a new SimpleMap with the specified keys and values.

      The keys and values arrays are stored by reference (not copied), so external modifications to the arrays after construction will affect the map's behavior. For true immutability, ensure the arrays are not modified after passing them to this constructor.

      Example:

      String[] keys = {"name", "age", "city"}; Object[] values = {"John", 30, "NYC"}; SimpleMap<String,Object> person = new SimpleMap<>(keys, values);

      Parameters:
      keys - The map keys. Must not be null. Individual keys can be null.
      values - The map values. Must not be null and must have the same length as keys. Individual values can be null.
      Throws:
      IllegalArgumentException - if:
      • The keys array is null
      • The values array is null
      • The keys and values arrays have different lengths
      • Any key appears more than once (duplicate keys)

  • Method Details

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Returns a Set view of the mappings contained in this map.

      The returned set is unmodifiable and backed by the underlying entries array.

      Example:

      SimpleMap<String,Integer> map = new SimpleMap<>( new String[]{"a", "b"}, new Integer[]{1, 2} ); for (Map.Entry<String,Integer> entry : map.entrySet()) { System.out.println(entry.getKey() + "=" + entry.getValue()); }

      Specified by:
      entrySet in interface Map<K,V>
      Specified by:
      entrySet in class AbstractMap<K,V>
      Returns:
      An unmodifiable set view of the mappings in this map.

    • get

      public V get(Object key)
      Returns the value associated with the specified key.

      This method performs a linear search through the keys array, using Object.equals(Object) for comparison. For small maps (typically less than 10 entries), this is often faster than the hash lookup in HashMap.

      Example:

      SimpleMap<String,Integer> map = new SimpleMap<>( new String[]{"age", "score"}, new Integer[]{25, 100} ); Integer age = map.get("age"); // Returns: 25 Integer height = map.get("height"); // Returns: null (key not found)

      Specified by:
      get in interface Map<K,V>
      Overrides:
      get in class AbstractMap<K,V>
      Parameters:
      key - The key whose associated value is to be returned.
      Returns:
      The value associated with the specified key, or null if the key is not found (or if the key is mapped to null).

    • keySet

      public Set<K> keySet()
      Returns a Set view of the keys contained in this map.

      The returned set is unmodifiable and backed by the underlying keys array.

      Example:

      SimpleMap<String,Integer> map = new SimpleMap<>( new String[]{"x", "y", "z"}, new Integer[]{1, 2, 3} ); Set<String> keys = map.keySet(); // Returns: [x, y, z]

      Specified by:
      keySet in interface Map<K,V>
      Overrides:
      keySet in class AbstractMap<K,V>
      Returns:
      An unmodifiable set view of the keys in this map.

    • put

      public V put(K key, V value)
      Throws UnsupportedOperationException as this map is unmodifiable.
      Specified by:
      put in interface Map<K,V>
      Overrides:
      put in class AbstractMap<K,V>
      Parameters:
      key - Ignored.
      value - Ignored.
      Returns:
      Never returns normally.
      Throws:
      UnsupportedOperationException - Always thrown, as this map cannot be modified.

    • 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 AbstractMap<K,V>
      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 AbstractMap<K,V>
      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 AbstractMap<K,V>
      Returns:
      The hash code value for this map.