Package org.apache.juneau.commons.collections

Class Maps<K,V>

java.lang.Object
org.apache.juneau.commons.collections.Maps<K,V>
Type Parameters:
K - The key type.
V - The value type.
public class Maps<K,V> extends Object
A fluent builder for constructing Map instances with various configuration options.

This builder provides a flexible and type-safe way to construct maps with support for adding entries, other maps, sorting by keys, and applying modifiers like unmodifiable or sparse modes. It's particularly useful when constructing maps dynamically from multiple sources or with conditional entries.

Instances of this builder can be created using create(Class, Class) or the convenience method CollectionUtils.mapb(Class, Class).

Features:
Examples:

import static org.apache.juneau.commons.utils.CollectionUtils.*; // Basic usage - returns Map Map<String,Integer> map = mapb(String.class, Integer.class) .add("one", 1) .add("two", 2) .add("three", 3) .build(); // Using pairs - returns Map Map<String,String> props = mapb(String.class, String.class) .addPairs("host", "localhost", "port", "8080") .build(); // With sorting by key - returns Map Map<String,Integer> sorted = mapb(String.class, Integer.class) .add("zebra", 3) .add("apple", 1) .add("banana", 2) .sorted() .build(); // Returns TreeMap with natural key order // Immutable map - returns Map Map<String,String> config = mapb(String.class, String.class) .add("env", "prod") .add("region", "us-west") .unmodifiable() .build(); // From multiple sources - returns Map Map<String,Integer> existing = Map.of("a", 1, "b", 2); Map<String,Integer> combined = mapb(String.class, Integer.class) .addAll(existing) .add("c", 3) .build(); // Sparse mode - returns null when empty Map<String,String> maybeNull = mapb(String.class, String.class) .sparse() .build(); // Returns null, not empty map // FluentMap wrapper - use buildFluent() FluentMap<String,Integer> fluent = mapb(String.class, Integer.class) .add("one", 1) .buildFluent(); // FilteredMap - use buildFiltered() FilteredMap<String,Integer> filtered = mapb(String.class, Integer.class) .filtered((k, v) -> v > 0) .add("a", 5) .add("b", -1) // Filtered out .buildFiltered();

Thread Safety:

This class is not thread-safe. Each builder instance should be used by a single thread or properly synchronized.

See Also:

  • Constructor Details

    • Maps

      public Maps(Class<K> keyType, Class<V> valueType)
      Constructor.
      Parameters:
      keyType - The key type. Must not be null.
      valueType - The value type. Must not be null.

  • Method Details

    • create

      public static <K, V> Maps<K,V> create(Class<K> keyType, Class<V> valueType)
      Static creator.
      Type Parameters:
      K - Key type.
      V - Value type.
      Parameters:
      keyType - The key type. Must not be null.
      valueType - The value type. Must not be null.
      Returns:
      A new builder.

    • create

      public static <K, V> Maps<K,V> create()
      Static creator without explicit type parameters.

      This is a convenience method that creates a builder without requiring explicit type parameters. The types will be inferred from usage context. Internally uses Object.class for both key and value types, which allows any types to be added.

      Example:

      Map<String, Integer> map = Maps.create() .add("one", 1) .add("two", 2) .build();

      Type Parameters:
      K - Key type.
      V - Value type.
      Returns:
      A new builder.

    • add

      public Maps<K,V> add(K key, V value)
      Adds a single entry to this map.

      Note: Filtering is applied at build time, not when adding entries.

      Parameters:
      key - The map key.
      value - The map value.
      Returns:
      This object.

    • addAll

      public Maps<K,V> addAll(Map<K,V> value)
      Appends the contents of the specified map into this map.

      This is a no-op if the value is null.

      Note: Filtering is applied at build time, not when adding entries.

      Parameters:
      value - The map to add to this map.
      Returns:
      This object.

    • addAny

      public Maps<K,V> addAny(Object... values)
      Adds arbitrary values to this map.

      Objects can be any of the following:

      • Maps of key/value types convertible to the key/value types of this map.

      Each entry from the maps will be added using add(Object, Object), which applies key/value function conversion if configured. Non-Map objects will cause a RuntimeException to be thrown.

      Parameters:
      values - The values to add. Can contain null values (ignored).
      Returns:
      This object.
      Throws:
      RuntimeException - If a non-Map object is provided.

    • addPairs

      public Maps<K,V> addPairs(Object... pairs)
      Adds a list of key/value pairs to this map.
      Parameters:
      pairs - The pairs to add.
      Returns:
      This object.

    • build

      public Map<K,V> build()
      Builds the map.

      Applies filtering, sorting, ordering, concurrent, unmodifiable, and sparse options.

      Map type selection:

      If filtering is applied, the result is wrapped in a FilteredMap.

      Returns:
      The built map, or null if sparse() is set and the map is empty.

    • buildFluent

      public FluentMap<K,V> buildFluent()
      Builds the map and wraps it in a FluentMap.

      This is a convenience method that calls build() and wraps the result in a FluentMap.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FluentMap<String,Integer> map = mapb(String.class, Integer.class) .add("one", 1) .add("two", 2) .buildFluent();

      Returns:
      The built map wrapped in a FluentMap, or null if sparse() is set and the map is empty.

    • buildFiltered

      public FilteredMap<K,V> buildFiltered()
      Builds the map as a FilteredMap.

      Map type selection:

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FilteredMap<String,Integer> map = mapb(String.class, Integer.class) .filtered((k, v) -> v != null && v > 0) .add("a", 5) .add("b", -1) // Will be filtered out .buildFiltered();

      Note: If unmodifiable() is set, the returned map will be wrapped in an unmodifiable view, which may cause issues if the FilteredMap tries to modify it internally. It's recommended to avoid using unmodifiable() when calling this method.

      Returns:
      The built map as a FilteredMap, or null if sparse() is set and the map is empty.

    • keyFunction

      public Maps<K,V> keyFunction(Function<Object,K> keyFunction)
      Sets the key conversion function for converting keys in addAny(Object...).

      The function is applied to each key when adding entries from maps in addAny(Object...).

      Parameters:
      keyFunction - The function to convert keys. Must not be null.
      Returns:
      This object.

    • valueFunction

      public Maps<K,V> valueFunction(Function<Object,V> valueFunction)
      Sets the value conversion function for converting values in addAny(Object...).

      The function is applied to each value when adding entries from maps in addAny(Object...).

      Parameters:
      valueFunction - The function to convert values. Must not be null.
      Returns:
      This object.

    • functions

      public Maps<K,V> functions(Function<Object,K> keyFunction, Function<Object,V> valueFunction)
      Sets both key and value conversion functions.

      Convenience method for setting both functions at once.

      Parameters:
      keyFunction - The function to convert keys. Must not be null.
      valueFunction - The function to convert values. Must not be null.
      Returns:
      This object.

    • filtered

      public Maps<K,V> filtered()
      Applies a default filter that excludes common "empty" or "unset" values from being added to the map.

      The following values are filtered out:

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FluentMap<String,Object> map = mapb(String.class, Object.class) .filtered() .add("name", "John") .add("age", -1) // Filtered out at build time .add("enabled", false) // Filtered out at build time .add("tags", new String[0]) // Filtered out at build time .build();

      Returns:
      This object.

    • filtered

      public Maps<K,V> filtered(BiPredicate<K,V> filter)
      Applies a filter predicate to entries when building the map.

      The filter receives both the key and value of each entry. Entries where the predicate returns true will be kept; entries where it returns false will be filtered out.

      This method can be called multiple times. When called multiple times, all filters are combined using AND logic - an entry must pass all filters to be kept in the map.

      Note: Filtering is applied at build time, not when adding entries.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Keep only non-null, non-empty string values Map<String,String> map = mapb(String.class, String.class) .filtered((k, v) -> v != null && !v.equals("")) .add("a", "foo") .add("b", null) // Filtered out at build time .add("c", "") // Filtered out at build time .build(); // Multiple filters combined with AND Map<String,Integer> map2 = mapb(String.class, Integer.class) .filtered((k, v) -> v != null) // First filter .filtered((k, v) -> v > 0) // Second filter (ANDed with first) .filtered((k, v) -> ! k.startsWith("_")) // Third filter (ANDed with previous) .add("a", 5) .add("_b", 10) // Filtered out (starts with "_") .add("c", -1) // Filtered out (not > 0) .build();

      Parameters:
      filter - The filter predicate. Must not be null.
      Returns:
      This object.

    • sorted

      public Maps<K,V> sorted()
      Converts the set into a SortedMap.

      Note: If ordered() was previously called, calling this method will override it. The last method called (ordered() or sorted()) determines the final map type.

      Returns:
      This object.

    • sorted

      public Maps<K,V> sorted(Comparator<K> comparator)
      Converts the set into a SortedMap using the specified comparator.

      Note: If ordered() was previously called, calling this method will override it. The last method called (ordered() or sorted()) determines the final map type.

      Parameters:
      comparator - The comparator to use for sorting. Must not be null.
      Returns:
      This object.

    • sparse

      public Maps<K,V> sparse()
      When specified, the build() method will return null if the map is empty.

      Otherwise build() will never return null.

      Returns:
      This object.

    • unmodifiable

      public Maps<K,V> unmodifiable()
      When specified, build() will return an unmodifiable map.
      Returns:
      This object.

    • concurrent

      public Maps<K,V> concurrent()
      When specified, build() will return a thread-safe map.

      The thread-safety implementation depends on other settings:

      This is useful when the map needs to be accessed from multiple threads.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Create a thread-safe map using ConcurrentHashMap Map<String,Integer> map = mapb(String.class, Integer.class) .add("one", 1) .add("two", 2) .concurrent() .build(); // Create a thread-safe ordered map Map<String,Integer> map2 = mapb(String.class, Integer.class) .ordered() .concurrent() .add("one", 1) .build();

      Returns:
      This object.

    • concurrent

      public Maps<K,V> concurrent(boolean value)
      Sets whether build() should return a thread-safe map.

      The thread-safety implementation depends on other settings:

      This is useful when the map needs to be accessed from multiple threads.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Conditionally create a thread-safe map Map<String,Integer> map = mapb(String.class, Integer.class) .add("one", 1) .concurrent(needsThreadSafety) .build();

      Parameters:
      value - Whether to make the map thread-safe.
      Returns:
      This object.

    • ordered

      public Maps<K,V> ordered()
      When specified, build() will use a LinkedHashMap to preserve insertion order.

      If not specified, a HashMap is used by default (no guaranteed order).

      Note: If sorted() was previously called, calling this method will override it. The last method called (ordered() or sorted()) determines the final map type.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Create an ordered map (preserves insertion order) Map<String,Integer> map = mapb(String.class, Integer.class) .ordered() .add("one", 1) .add("two", 2) .build();

      Returns:
      This object.

    • ordered

      public Maps<K,V> ordered(boolean value)
      Sets whether build() should use a LinkedHashMap to preserve insertion order.

      If false (default), a HashMap is used (no guaranteed order). If true, a LinkedHashMap is used (preserves insertion order).

      Note: If sorted() was previously called, calling this method with true will override it. The last method called (ordered() or sorted()) determines the final map type.

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Conditionally create an ordered map Map<String,Integer> map = mapb(String.class, Integer.class) .ordered(preserveOrder) .add("one", 1) .build();

      Parameters:
      value - Whether to preserve insertion order.
      Returns:
      This object.