Package org.apache.juneau.commons.collections

Class Lists<E>

java.lang.Object
org.apache.juneau.commons.collections.Lists<E>
Type Parameters:
E - The element type.
public class Lists<E> extends Object
A fluent builder for constructing List instances with various configuration options.

This builder provides a flexible and type-safe way to construct lists with support for adding elements, collections, arrays, sorting, and applying modifiers like unmodifiable or sparse modes. It's particularly useful when you need to construct lists dynamically with conditional elements or from multiple sources.

Features:
  • Fluent API - all methods return this for method chaining
  • Multiple add methods - single elements, varargs, collections, arrays
  • Arbitrary input support - automatic type conversion with addAny(Object...)
  • Conditional adding - addIf(boolean, Object) for conditional elements
  • Sorting support - natural order or custom Comparator
  • Sparse mode - return null for empty lists
  • Unmodifiable mode - create immutable lists
  • Filtering support - exclude unwanted elements via filtered() or filtered(Predicate)
  • Custom conversion functions - type conversion via elementFunction(Function)
Examples:

// Basic usage List<String> list = Lists.create(String.class) .add("apple", "banana", "cherry") .build(); // With sorting List<Integer> sorted = Lists.create(Integer.class) .add(3, 1, 4, 1, 5, 9, 2, 6) .sorted() .build(); // Conditional elements List<String> filtered = Lists.create(String.class) .add("always") .addIf(includeOptional, "optional") .build(); // Immutable list List<String> immutable = Lists.create(String.class) .add("read", "only") .unmodifiable() .build(); // Sparse mode - returns null when empty List<String> maybeNull = Lists.create(String.class) .sparse() .build(); // Returns null, not empty list // From multiple sources List<Integer> existing = l(1, 2, 3); List<Integer> combined = Lists.create(Integer.class) .addAll(existing) .add(4, 5, 6) .build(); // FluentList wrapper - use buildFluent() FluentList<String> fluent = Lists.create(String.class) .add("one", "two") .buildFluent(); // FilteredList - use buildFiltered() FilteredList<Integer> filtered = Lists.create(Integer.class) .filtered(v -> v > 0) .add(5) .add(-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

    • Lists

      public Lists(Class<E> elementType)
      Constructor.
      Parameters:
      elementType - The element type. Must not be null.

  • Method Details

    • create

      public static <E> Lists<E> create(Class<E> elementType)
      Creates a new list builder for the specified element type.
      Example:

      List<String> list = Lists.create(String.class) .add("a", "b", "c") .build();

      Type Parameters:
      E - The element type.
      Parameters:
      elementType - The element type class. Required for type-safe operations. Must not be null.
      Returns:
      A new list builder instance.

    • add

      public Lists<E> add(E value)
      Adds a single value to this list.

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

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

    • add

      public Lists<E> add(E... values)
      Adds multiple values to this list.
      Parameters:
      values - The values to add to this list.
      Returns:
      This object.

    • addAll

      public Lists<E> addAll(Collection<E> value)
      Appends the contents of the specified collection into this list.

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

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

    • addAny

      public Lists<E> addAny(Object... values)
      Adds arbitrary values to this list with automatic type conversion.

      This method provides flexible input handling by automatically converting and flattening various input types:

      • Direct instances of the element type - added as-is
      • Collections - recursively flattened and elements converted
      • Arrays - recursively flattened and elements converted
      • Convertible types - converted using elementFunction(Function)
      Example:

      // Mix different input types List<Integer> list = Lists.create(Integer.class) .addAny(1, 2, 3) // Direct values .addAny(l(4, 5, 6)) // Collection .addAny(new int[]{7, 8, 9}) // Array .build();

      Parameters:
      values - The values to add. null values are ignored.
      Returns:
      This object for method chaining.
      Throws:
      IllegalStateException - if element type is unknown.
      RuntimeException - if a value cannot be converted to the element type.

    • addIf

      public Lists<E> addIf(boolean flag, E value)
      Appends a value to this list of the flag is true.
      Parameters:
      flag - The flag.
      value - The value.
      Returns:
      This object.

    • build

      public List<E> build()
      Builds the list.

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

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

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

    • buildFluent

      public FluentList<E> buildFluent()
      Builds the list and wraps it in a FluentList.

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

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FluentList<String> list = Lists.create(String.class) .add("one", "two") .buildFluent();

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

    • buildFiltered

      public FilteredList<E> buildFiltered()
      Builds the list as a FilteredList.
      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FilteredList<Integer> list = Lists.create(Integer.class) .filtered(v -> v != null && v > 0) .add(5) .add(-1) // Will be filtered out .buildFiltered();

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

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

    • elementFunction

      public Lists<E> elementFunction(Function<Object,E> elementFunction)
      Sets the element conversion function for converting elements in addAny(Object...).

      The function is applied to each element when adding elements in addAny(Object...).

      Parameters:
      elementFunction - The function to convert elements. Must not be null.
      Returns:
      This object.

    • elementType

      public Lists<E> elementType(Class<E> value)
      Specifies the element type on this list.
      Parameters:
      value - The element type. Must not be null.
      Returns:
      This object.

    • filtered

      public Lists<E> filtered()
      Applies a default filter that excludes common "empty" or "unset" values from being added to the list.

      The following values are filtered out:

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; List<Object> list = Lists.create(Object.class) .filtered() .add("name") .add(-1) // Filtered out at build time .add(false) // Filtered out at build time .add(new String[0]) // Filtered out at build time .build();

      Returns:
      This object.

    • filtered

      public Lists<E> filtered(Predicate<E> filter)
      Applies a filter predicate to elements when building the list.

      The filter receives the element value. Elements where the predicate returns true will be kept; elements 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 element must pass all filters to be kept in the list.

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

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; // Keep only non-null, positive integers List<Integer> list = Lists.create(Integer.class) .filtered(v -> v != null && v > 0) .add(5) .add(-1) // Filtered out at build time .add(null) // Filtered out at build time .build(); // Multiple filters combined with AND List<Integer> list2 = Lists.create(Integer.class) .filtered(v -> v != null) // First filter .filtered(v -> v > 0) // Second filter (ANDed with first) .filtered(v -> v < 100); // Third filter (ANDed with previous) .add(5) .add(150) // Filtered out (not < 100) .add(-1) // Filtered out (not > 0) .build();

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

    • sorted

      public Lists<E> sorted()
      Sorts the contents of the list.
      Returns:
      This object.

    • sorted

      public Lists<E> sorted(Comparator<E> comparator)
      Sorts the contents of the list using the specified comparator.
      Parameters:
      comparator - The comparator to use for sorting. Must not be null.
      Returns:
      This object.

    • sparse

      public Lists<E> sparse()
      When specified, the build() method will return null if the list is empty.

      Otherwise build() will never return null.

      Returns:
      This object.

    • unmodifiable

      public Lists<E> unmodifiable()
      When specified, build() will return an unmodifiable list.
      Returns:
      This object.

    • concurrent

      public Lists<E> concurrent()
      When specified, build() will return a thread-safe synchronized list.

      The list will be wrapped using Collections.synchronizedList(List) to provide thread-safety. This is useful when the list needs to be accessed from multiple threads.

      Example:

      // Create a thread-safe list List<String> list = Lists.create(String.class) .add("one", "two") .concurrent() .build();

      Returns:
      This object.

    • concurrent

      public Lists<E> concurrent(boolean value)
      Sets whether build() should return a thread-safe synchronized list.

      When true, the list will be wrapped using Collections.synchronizedList(List) to provide thread-safety. This is useful when the list needs to be accessed from multiple threads.

      Example:

      // Conditionally create a thread-safe list List<String> list = Lists.create(String.class) .add("one", "two") .concurrent(needsThreadSafety) .build();

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