Design and Implementation of Multi-Key HashMap in Java

Problem Background of Multi-Dimensional Key-Value Mapping

In software development practice, scenarios frequently arise where data needs to be accessed and stored based on multiple keys. Particularly when dealing with two-dimensional arrays or matrix data, traditional single-key HashMaps cannot satisfy the requirement of directly accessing elements through row and column indices. For example, for a two-dimensional integer array A, the desire to retrieve the value at position A[2][5] through map.get(2, 5) necessitates the design of mapping structures that support multiple keys.

Three Implementation Approaches for 2D Scenarios

Nested Map Structure

The most intuitive solution employs a nested Map structure: Map<Integer, Map<Integer, V>>. Access in this approach is achieved through map.get(2).get(5), offering straightforward implementation. However, this structure presents limitations in null value handling and performance, requiring additional null-check logic when outer keys are absent.

Custom Key Object Encapsulation

A more elegant solution involves creating a dedicated key class to encapsulate multiple key values:

public class Key {
    private final int x;
    private final int y;
    
    public Key(int x, int y) {
        this.x = x;
        this.y = y;
    }
    
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Key)) return false;
        Key key = (Key) o;
        return x == key.x && y == key.y;
    }
    
    @Override
    public int hashCode() {
        int result = x;
        result = 31 * result + y;
        return result;
    }
}

Usage follows the pattern map.get(new Key(2, 5)). The critical aspect of this method lies in the proper implementation of equals() and hashCode() methods, ensuring key object uniqueness and uniform hash distribution. The use of prime number 31 in hashCode computation helps minimize hash collisions.

Guava Table Utility

The Google Guava library provides a specialized Table interface: Table<Integer, Integer, V>, instantiated via HashBasedTable.create(), with direct access through table.get(2, 5). While Table internally uses nested Map implementation, it offers more user-friendly API and additional functional support.

Extension Solutions for N-Dimensional Scenarios

For higher-dimensional scenarios, the custom key class approach demonstrates superior extensibility. It can easily support key combinations of arbitrary dimensions by increasing field counts. In contrast, the Map<List<Integer>, V> approach exhibits significant drawbacks in performance, readability, and type safety.

Performance Optimization and Index Encoding

For specific N×N matrix scenarios, index encoding technique can transform multi-dimensional indices into single keys:

int key = i * N + j;
// Storage: map.put(key, a[i][j])
// Retrieval: int i = key / N; int j = key % N;

This method offers advantages in memory usage and access performance, particularly suitable for fixed-dimension dense matrix storage.

Design Principles and Best Practices

Important insights can be drawn from JSON key-value pair structure design: data structures should balance semantic clarity with processing efficiency. Similar to the compact structure of {"key1": "value1", "key2": "value2"} in JSON, the custom key object method achieves an excellent balance between semantic clarity and runtime efficiency.

In practical applications, the choice of approach requires comprehensive consideration of dimension count, performance requirements, code maintainability, and third-party library dependencies. For simple two-dimensional scenarios, each of the three approaches has distinct advantages and disadvantages; for complex high-dimensional scenarios, custom key objects typically represent the optimal choice.