Package com.cedarsoftware.util

Class CompactMap.Builder<K,V>

java.lang.Object
com.cedarsoftware.util.CompactMap.Builder<K,V>
Type Parameters:
K - the type of keys maintained by the map
V - the type of mapped values
Enclosing class:
CompactMap<K,V>
public static final class CompactMap.Builder<K,V> extends Object
Builder class for creating customized CompactMap instances.

Simple example with common options: 


 CompactMap<String, Object> map = CompactMap.<String, Object>builder()
         .caseSensitive(false)
         .sortedOrder()
         .build();

Note the type witness (<String, Object>) in the example above. This explicit type information is required when method chaining directly from builder() due to Java's type inference limitations. Alternatively, you can avoid the type witness by splitting the builder creation and configuration: 


 // Using type witness
 CompactMap<String, Object> map1 = CompactMap.<String, Object>builder()
         .sortedOrder()
         .build();

 // Without type witness
 Builder<String, Object> builder = CompactMap.builder();
 CompactMap<String, Object> map2 = builder
         .sortedOrder()
         .build();

Comprehensive example with all options: 


 CompactMap<String, Object> map = CompactMap.<String, Object>builder()
         .caseSensitive(false)           // Enable case-insensitive key comparison
         .compactSize(80)                // Set threshold for switching to backing map
         .mapType(LinkedHashMap.class)   // Specify backing map implementation
         .singleValueKey("uuid")         // Optimize storage for single entry with this key
         .sourceMap(existingMap)         // Initialize with entries from another map
         .insertionOrder()               // Or: .reverseOrder(), .sortedOrder(), .noOrder()
         .build();
Available Builder Options
Method Description Default
caseSensitive(boolean) Controls case sensitivity for string keys true
compactSize(int) Maximum size before switching to backing map 70
mapType(Class) Type of backing map when size exceeds compact size HashMap.class
singleValueKey(Object) Special key that enables optimized storage when map contains only one entry with this key "id"
sourceMap(Map) Initializes the CompactMap with entries from the provided map null
sortedOrder() Maintains keys in sorted order unordered
reverseOrder() Maintains keys in reverse order unordered
insertionOrder() Maintains keys in insertion order unordered
noOrder() Explicitly sets unordered behavior unordered
See Also:

  • Method Details

    • caseSensitive

      public CompactMap.Builder<K,V> caseSensitive(boolean caseSensitive)
      Sets whether String keys should be compared case-sensitively.

      When set to false, String keys will be compared ignoring case. For example, "Key", "key", and "KEY" would all be considered equal. This setting only affects String keys; other key types are compared normally. Maps can contain heterogeneous content (Strings, Numbers, null, as keys).

      Parameters:
      caseSensitive - true for case-sensitive comparison (default), false for case-insensitive comparison
      Returns:
      this builder instance for method chaining

    • mapType

      public CompactMap.Builder<K,V> mapType(Class<? extends Map> mapType)
      Sets the type of Map to use when size exceeds compact storage threshold.

      Common map types include:

      Note: IdentityHashMap and WeakHashMap are not supported.
      Parameters:
      mapType - the Class object representing the desired Map implementation
      Returns:
      this builder instance for method chaining
      Throws:
      IllegalArgumentException - if mapType is not a Map class

    • singleValueKey

      public CompactMap.Builder<K,V> singleValueKey(K key)
      Sets a special key for optimized single-entry storage.

      When the map contains exactly one entry with this key, the value is stored directly without wrapper objects, reducing memory overhead. The default single value key is "id".

      Parameters:
      key - the key to use for optimized single-entry storage
      Returns:
      this builder instance for method chaining

    • compactSize

      public CompactMap.Builder<K,V> compactSize(int size)
      Sets the maximum size for compact array storage.

      When the map size is between 2 and this value, entries are stored in a compact array format. Above this size, entries are moved to a backing map. Must be greater than or equal to 2.

      Parameters:
      size - the maximum number of entries to store in compact format
      Returns:
      this builder instance for method chaining

    • sortedOrder

      public CompactMap.Builder<K,V> sortedOrder()
      Configures the map to maintain keys in natural sorted order.

      Keys must be Comparable or a ClassCastException will be thrown when incomparable keys are inserted. For String keys, the ordering respects the case sensitivity setting.

      Returns:
      this builder instance for method chaining

    • reverseOrder

      public CompactMap.Builder<K,V> reverseOrder()
      Configures the map to maintain keys in reverse sorted order.

      Keys must be Comparable or a ClassCastException will be thrown when incomparable keys are inserted. For String keys, the ordering respects the case sensitivity setting.

      Returns:
      this builder instance for method chaining

    • insertionOrder

      public CompactMap.Builder<K,V> insertionOrder()
      Configures the map to maintain keys in insertion order.

      The iteration order will match the order in which entries were added to the map. This ordering is preserved even when entries are updated.

      Returns:
      this builder instance for method chaining

    • noOrder

      public CompactMap.Builder<K,V> noOrder()
      Explicitly configures the map to not maintain any specific ordering.

      This is the default behavior if no ordering is specified. The iteration order may change as entries are added or removed.

      Returns:
      this builder instance for method chaining

    • sourceMap

      public CompactMap.Builder<K,V> sourceMap(Map<K,V> source)
      Initializes the map with entries from the specified source map.

      Parameters:
      source - the map whose entries are to be copied
      Returns:
      this builder instance for method chaining
      Throws:
      IllegalArgumentException - if source map's ordering conflicts with configured ordering

    • build

      public CompactMap<K,V> build()
      Creates a new CompactMap instance with the configured options.

      This method validates all options and creates a specialized implementation based on the configuration. The resulting map is optimized for the specified combination of options.

      Returns:
      a new CompactMap instance
      Throws:
      IllegalArgumentException - if any configuration options are invalid or incompatible