Collections Package

The org.apache.juneau.commons.collections package provides enhanced collection utilities that extend the standard Java Collections Framework with fluent APIs, specialized collection types, and caching capabilities.

Key Classes

Collection Builders

Lists

Fluent builder for constructing List instances with various configuration options.

import static org.apache.juneau.commons.utils.CollectionUtils.*;

// Basic usage
List<String> list = listb(String.class)
    .add("apple", "banana", "cherry")
    .build();

// With sorting
List<Integer> sorted = listb(Integer.class)
    .add(3, 1, 4, 1, 5, 9, 2, 6)
    .sorted()
    .build();

// Conditional elements
List<String> filtered = listb(String.class)
    .add("always")
    .addIf(includeOptional, "optional")
    .build();

// Immutable list
List<String> immutable = listb(String.class)
    .add("read", "only")
    .unmodifiable()
    .build();

Maps

Fluent builder for constructing Map instances.

import static org.apache.juneau.commons.utils.CollectionUtils.*;

// Basic usage
Map<String, Integer> map = mapb(String.class, Integer.class)
    .add("one", 1)
    .add("two", 2)
    .add("three", 3)
    .build();

// Using pairs
Map<String, String> props = mapb(String.class, String.class)
    .addPairs("host", "localhost", "port", "8080")
    .build();

// With sorting by key
Map<String, Integer> sorted = mapb(String.class, Integer.class)
    .add("zebra", 3)
    .add("apple", 1)
    .add("banana", 2)
    .sorted()
    .build();

Sets

Fluent builder for constructing Set instances with automatic deduplication.

import static org.apache.juneau.commons.utils.CollectionUtils.*;

// Basic usage
Set<String> set = setb(String.class)
    .add("apple", "banana", "cherry")
    .build();

// Automatic deduplication
Set<Integer> unique = setb(Integer.class)
    .add(1, 2, 3, 2, 1)  // Duplicates ignored
    .build();  // Contains: 1, 2, 3

Fluent Collections

FluentMap

A fluent wrapper around an arbitrary map that provides convenient methods for adding entries.

FluentMap<String, String> map = new FluentMap<>(new LinkedHashMap<>());

map
    .a("key1", "value1")
    .a("key2", "value2")
    .ai(true, "key3", "value3")   // Added
    .ai(false, "key4", "value4");  // Not added

// Add all entries from another map
Map<String, String> other = Map.of("key5", "value5", "key6", "value6");
map.aa(other);

FluentList

A fluent wrapper around a list for convenient element addition.

FluentList<String> list = new FluentList<>(new ArrayList<>());

list
    .a("item1")
    .a("item2")
    .ai(true, "item3")   // Added
    .ai(false, "item4"); // Not added

FluentSet

A fluent wrapper around a set for convenient element addition.

FluentSet<String> set = new FluentSet<>(new LinkedHashSet<>());

set
    .a("item1")
    .a("item2")
    .ai(true, "item3");  // Added

Specialized Collections

MultiMap

A composite map that presents multiple maps as a single unified map.

Map<String, String> map1 = Map.of("key1", "value1", "key2", "value2");
Map<String, String> map2 = Map.of("key3", "value3", "key2", "value2b");
Map<String, String> map3 = Map.of("key4", "value4");

MultiMap<String, String> multiMap = new MultiMap<>(map1, map2, map3);

// Access entries by key
multiMap.get("key1");  // Returns "value1" from map1
multiMap.get("key2");  // Returns "value2" from map1 (first match wins)
multiMap.get("key3");  // Returns "value3" from map2

MultiList

A composite list that presents multiple lists as a single unified list.

List<String> list1 = List.of("a", "b", "c");
List<String> list2 = List.of("d", "e");
List<String> list3 = List.of("f", "g", "h");

MultiList<String> multiList = new MultiList<>(list1, list2, list3);

// Access elements
multiList.get(0);  // Returns "a" from list1
multiList.get(3);  // Returns "d" from list2
multiList.size();  // Returns 8 (total elements)

MultiSet

A composite set that presents multiple sets as a single unified set.

Set<String> set1 = Set.of("a", "b", "c");
Set<String> set2 = Set.of("c", "d", "e");  // "c" is duplicate
Set<String> set3 = Set.of("f", "g");

MultiSet<String> multiSet = new MultiSet<>(set1, set2, set3);

// Access elements (duplicates handled automatically)
multiSet.contains("c");  // Returns true
multiSet.size();  // Returns 7 (unique elements: a, b, c, d, e, f, g)

BidiMap

A bidirectional map that allows lookup by both key and value.

BidiMap<String, Integer> bidiMap = new BidiMap<>();

bidiMap.put("one", 1);
bidiMap.put("two", 2);
bidiMap.put("three", 3);

// Forward lookup
bidiMap.get("one");  // Returns 1

// Reverse lookup
bidiMap.getKey(1);  // Returns "one"
bidiMap.getKey(2);  // Returns "two"

Filtered Collections

FilteredMap

A map that filters entries based on a predicate.

FilteredMap<String, Integer> filtered = new FilteredMap<>(
    new HashMap<>(),
    (k, v) -> v > 0  // Only keep positive values
);

filtered.put("a", 5);   // Added
filtered.put("b", -1);  // Filtered out
filtered.put("c", 10);  // Added

FilteredList

A list that filters elements based on a predicate.

FilteredList<Integer> filtered = new FilteredList<>(
    new ArrayList<>(),
    v -> v > 0  // Only keep positive values
);

filtered.add(5);   // Added
filtered.add(-1);  // Filtered out
filtered.add(10);  // Added

FilteredSet

A set that filters elements based on a predicate.

FilteredSet<Integer> filtered = new FilteredSet<>(
    new LinkedHashSet<>(),
    v -> v > 0  // Only keep positive values
);

filtered.add(5);   // Added
filtered.add(-1);  // Filtered out
filtered.add(10);  // Added

Caching

Cache

Simple in-memory cache for storing and retrieving objects by key.

// Create a cache with default supplier
Cache<String, Pattern> patternCache = Cache
    .of(String.class, Pattern.class)
    .maxSize(100)
    .supplier(Pattern::compile)
    .build();

// Retrieve using default supplier
Pattern pattern1 = patternCache.get("[a-z]+");

// Or override the supplier
Pattern pattern2 = patternCache.get("[0-9]+", 
    () -> Pattern.compile("[0-9]+", Pattern.CASE_INSENSITIVE));

HashKey

A composite key composed of multiple values, suitable for use as a key in hash-based collections.

// Create a composite key from multiple values
HashKey key = HashKey.of(
    "config1",
    "config2",
    true,
    42
);

// Use as a key in a cache or map
Map<HashKey, MyObject> cache = new HashMap<>();
cache.put(key, myObject);

// Retrieve using an equivalent key
HashKey lookupKey = HashKey.of("config1", "config2", true, 42);
MyObject cached = cache.get(lookupKey);  // Returns myObject

Other Utilities

SortedArrayList

An ArrayList that maintains elements in sorted order.

SortedArrayList<String> sorted = new SortedArrayList<>();

sorted.add("zebra");
sorted.add("apple");
sorted.add("banana");

// Elements are automatically sorted
// Contains: ["apple", "banana", "zebra"]

SortedLinkedList

A LinkedList that maintains elements in sorted order.

SortedLinkedList<Integer> sorted = new SortedLinkedList<>();

sorted.add(3);
sorted.add(1);
sorted.add(4);

// Elements are automatically sorted
// Contains: [1, 3, 4]

ReversedList

A list that presents a reversed view of another list.

List<String> original = List.of("a", "b", "c", "d");
ReversedList<String> reversed = new ReversedList<>(original);

reversed.get(0);  // Returns "d"
reversed.get(1);  // Returns "c"
reversed.get(2);  // Returns "b"
reversed.get(3);  // Returns "a"

See Also

• Juneau Commons Basics
• Juneau Commons Utils
• JavaDoc: Collections Package