Package com.cedarsoftware.util

Class MultiKeyMap.Builder<V>

java.lang.Object
com.cedarsoftware.util.MultiKeyMap.Builder<V>
Enclosing class:
MultiKeyMap<V>
public static class MultiKeyMap.Builder<V> extends Object
Builder for creating configured MultiKeyMap instances.

The builder provides a fluent API for configuring various aspects of the map's behavior:

  • capacity - Initial capacity (will be rounded up to power of 2)
  • loadFactor - Load factor for resizing (default 0.75)
  • collectionKeyMode - How Collections are treated as keys
  • flattenDimensions - Whether to flatten nested structures
  • simpleKeysMode - Performance optimization for non-nested keys
  • valueBasedEquality - Enable cross-type numeric matching (default true)
  • caseSensitive - Whether CharSequence comparisons are case-sensitive (default true)

  • Method Details

    • capacity

      public MultiKeyMap.Builder<V> capacity(int capacity)
      Sets the initial capacity of the map.

      The actual capacity will be rounded up to the nearest power of 2 for optimal performance.

      Parameters:
      capacity - the initial capacity (must be non-negative)
      Returns:
      this builder instance for method chaining
      Throws:
      IllegalArgumentException - if capacity is negative

    • loadFactor

      public MultiKeyMap.Builder<V> loadFactor(float loadFactor)
      Sets the load factor for the map.

      The load factor determines when the map will resize. A value of 0.75 means the map will resize when it's 75% full.

      Parameters:
      loadFactor - the load factor (must be positive)
      Returns:
      this builder instance for method chaining
      Throws:
      IllegalArgumentException - if loadFactor is not positive or is NaN

    • collectionKeyMode

      public MultiKeyMap.Builder<V> collectionKeyMode(MultiKeyMap.CollectionKeyMode mode)
      Sets the collection key mode for the map.

      This determines how Collections are treated when used as keys:

      • COLLECTIONS_EXPANDED (default) - Collections are unpacked into multi-dimensional keys
      • COLLECTIONS_NOT_EXPANDED - Collections are treated as single key objects
      Parameters:
      mode - the collection key mode (must not be null)
      Returns:
      this builder instance for method chaining
      Throws:
      NullPointerException - if mode is null

    • flattenDimensions

      public MultiKeyMap.Builder<V> flattenDimensions(boolean flatten)
      Sets whether to flatten nested dimensions.

      When enabled, nested arrays and collections are recursively flattened so that all equivalent flat representations are treated as the same key.

      When disabled (default), structure is preserved and different nesting levels create distinct keys.

      Parameters:
      flatten - true to flatten nested structures, false to preserve structure
      Returns:
      this builder instance for method chaining

    • simpleKeysMode

      public MultiKeyMap.Builder<V> simpleKeysMode(boolean simple)
      Enables simple keys mode for maximum performance.

      When enabled, the map assumes keys do not contain nested arrays or collections, allowing it to skip expensive nested structure checks. This provides significant performance improvements when you know your keys are "flat" (no nested containers).

      Warning: If you enable this mode but use keys with nested arrays/collections, they will not be expanded and may not match as expected.

      Parameters:
      simple - true to enable simple keys optimization, false for normal operation
      Returns:
      this builder instance for method chaining

    • valueBasedEquality

      public MultiKeyMap.Builder<V> valueBasedEquality(boolean valueBasedEquality)
      Enables value-based equality for numeric keys.

      When enabled, numeric keys are compared by value rather than type:

      • Integral types (byte, short, int, long) compare as longs
      • Floating point types (float, double) compare as doubles
      • Float/double can equal integers only when they represent whole numbers
      • Booleans only equal other booleans
      • Characters only equal other characters

      Default is true (value-based equality with cross-type numeric matching).

      Parameters:
      valueBasedEquality - true to enable value-based equality, false for type-based
      Returns:
      this builder instance for method chaining

    • caseSensitive

      public MultiKeyMap.Builder<V> caseSensitive(boolean caseSensitive)
      Sets whether CharSequence comparisons should be case-sensitive.

      When disabled (false), all CharSequence instances (String, StringBuilder, etc.) are compared case-insensitively for both equality and hashing.

      Default is true (case-sensitive comparison).

      Parameters:
      caseSensitive - true for case-sensitive comparison, false for case-insensitive
      Returns:
      this builder instance for method chaining
      Since:
      3.6.0

    • from

      public MultiKeyMap.Builder<V> from(MultiKeyMap<?> source)
      Copies configuration from an existing MultiKeyMap.

      This copies all configuration settings including capacity, load factor, collection key mode, and dimension flattening settings.

      Parameters:
      source - the MultiKeyMap to copy configuration from
      Returns:
      this builder instance for method chaining

    • build

      public MultiKeyMap<V> build()
      Builds and returns a new MultiKeyMap with the configured settings.
      Returns:
      a new MultiKeyMap instance with the specified configuration