Package com.cedarsoftware.util

Class MultiKeyMap<V>

java.lang.Object
com.cedarsoftware.util.MultiKeyMap<V>
Type Parameters:
V - the type of values stored in the map
All Implemented Interfaces:
ConcurrentMap<Object,V>, Map<Object,V>
public final class MultiKeyMap<V> extends Object implements ConcurrentMap<Object,V>
High-performance N-dimensional key-value Map implementation - the definitive solution for multi-dimensional lookups.

MultiKeyMap allows storing and retrieving values using multiple keys. Unlike traditional maps that use a single key, this map can handle keys with any number of components, making it ideal for complex lookup scenarios like user permissions, configuration trees, and caching systems.

Key Features:

  • N-Dimensional Keys: Support for keys with any number of components (1, 2, 3, ... N).
  • High Performance: Zero-allocation polymorphic storage, MurmurHash3 finalization, and optimized hash computation — no GC/heap pressure for gets in flat cases.
  • Thread-Safe: Lock-free reads with auto-tuned stripe locking that scales with your server cores, similar to ConcurrentHashMap.
  • Map Interface Compatible: Supports single-key operations via the standard Map interface (get()/put() automatically unpack Collections/Arrays into multi-keys).
  • Flexible API: Var-args methods for convenient multi-key operations (getMultiKey()/putMultiKey() with many keys).
  • Smart Collection Handling: Configurable behavior for Collections via MultiKeyMap.CollectionKeyMode — change the default automatic unpacking capability as needed.
  • N-Dimensional Array Expansion: Nested arrays of any depth are automatically flattened recursively into multi-keys, with configurable structure preservation.
  • Cross-Container Equivalence: Arrays and Collections with equivalent structure are treated as identical keys, regardless of container type.

Dimensional Behavior Control:

MultiKeyMap provides revolutionary control over how dimensions are handled through the flattenDimensions parameter:

  • Structure-Preserving Mode (default, flattenDimensions = false): Different structural depths remain distinct keys. Arrays/Collections with different nesting levels create separate entries.
  • Dimension-Flattening Mode (flattenDimensions = true): All equivalent flat representations are treated as identical keys, regardless of original container structure.

Performance Characteristics:

  • Lock-Free Reads: Get operations require no locking for optimal concurrent performance
  • Auto-Tuned Stripe Locking: Write operations use stripe locking that adapts to your server's core count
  • Zero-Allocation Gets: No temporary objects created during retrieval operations
  • MurmurHash3 Finalization: Enhanced hash distribution reduces collisions
  • Polymorphic Storage: Efficient memory usage adapts storage format based on key complexity

API Overview:

MultiKeyMap provides two complementary APIs:

  • Map Interface: Use as Map<Object, V> for compatibility with existing code and single-key operations
  • MultiKeyMap API: Declare as MultiKeyMap<V> to access powerful var-args methods for multi-dimensional operations

Usage Examples:


 // Basic multi-dimensional usage
 MultiKeyMap<String> map = new MultiKeyMap<>();
 map.putMultiKey("user-config", "user123", "settings", "theme");
 String theme = map.getMultiKey("user123", "settings", "theme");
 
 // Cross-container equivalence
 map.put(new String[]{"key1", "key2"}, "value1");           // Array key
 String value = map.get(Arrays.asList("key1", "key2"));     // Collection lookup - same key!
 
 // Structure-preserving vs flattening modes
 MultiKeyMap<String> structured = new MultiKeyMap<>(false); // Structure-preserving (default)
 MultiKeyMap<String> flattened = new MultiKeyMap<>(true);   // Dimension-flattening

For comprehensive examples and advanced usage patterns, see the user guide documentation.

Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.