Package org.apache.juneau.commons.collections

Class Sets<E>

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

This builder provides a flexible and type-safe way to construct sets with support for adding elements, collections, arrays, sorting, and applying modifiers like unmodifiable or sparse modes. Sets automatically handle duplicates - adding the same element multiple times will result in only one occurrence in the final set.

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 sets
  • Unmodifiable mode - create immutable sets
  • Filtering support - exclude unwanted elements via filtered() or filtered(Predicate)
  • Custom conversion functions - type conversion via elementFunction(Function)
  • Automatic deduplication - duplicate elements are automatically removed
Examples:

// Basic usage Set<String> set = Sets.create(String.class) .add("apple", "banana", "cherry") .build(); // Automatic deduplication Set<Integer> unique = Sets.create(Integer.class) .add(1, 2, 3, 2, 1) // Duplicates ignored .build(); // Contains: 1, 2, 3 // With sorting Set<String> sorted = Sets.create(String.class) .add("zebra", "apple", "banana") .sorted() .build(); // Returns TreeSet in natural order // Conditional elements Set<String> features = Sets.create(String.class) .add("basic") .addIf(hasPremium, "premium") .addIf(hasEnterprise, "enterprise") .build(); // Immutable set Set<String> immutable = Sets.create(String.class) .add("read", "only") .unmodifiable() .build(); // From multiple sources Set<Integer> existing = Set.of(1, 2, 3); Set<Integer> combined = Sets.create(Integer.class) .addAll(existing) .add(4, 5, 6) .build(); // Sparse mode - returns null when empty Set<String> maybeNull = Sets.create(String.class) .sparse() .build(); // Returns null, not empty set // FluentSet wrapper - use buildFluent() FluentSet<String> fluent = Sets.create(String.class) .add("one", "two") .buildFluent(); // FilteredSet - use buildFiltered() FilteredSet<Integer> filtered = Sets.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

    • Sets

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

  • Method Details

    • create

      public static <E> Sets<E> create(Class<E> elementType)
      Static creator.
      Type Parameters:
      E - The element type.
      Parameters:
      elementType - The element type. Must not be null.
      Returns:
      A new builder.

    • add

      public Sets<E> add(E value)
      Adds a single value to this set.

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

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

    • add

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

    • addAll

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

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

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

    • addAny

      public Sets<E> addAny(Object... values)
      Adds arbitrary values to this set.

      Objects can be any of the following:

      • The same type or convertible to the element type of this set.
      • Collections or arrays of anything on this set.
      • JSON array strings parsed and convertible to the element type of this set.
      Parameters:
      values - The values to add.
      Returns:
      This object.

    • addIf

      public Sets<E> addIf(boolean flag, E value)
      Adds a value to this set if the specified flag is true.
      Parameters:
      flag - The flag.
      value - The value.
      Returns:
      This object.

    • addJson

      public Sets<E> addJson(String... values)
      Adds entries to this set via JSON array strings.
      Parameters:
      values - The JSON array strings to parse and add to this set.
      Returns:
      This object.

    • build

      public Set<E> build()
      Builds the set.

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

      Set type selection:

      • If sorted() is set: Uses TreeSet (or synchronized TreeSet if concurrent)
      • If ordered() is set: Uses LinkedHashSet (or synchronized LinkedHashSet if concurrent)
      • Otherwise: Uses HashSet (or synchronized HashSet if concurrent)

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

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

    • buildFluent

      public FluentSet<E> buildFluent()
      Builds the set and wraps it in a FluentSet.

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

      Example:

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

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

    • buildFiltered

      public FilteredSet<E> buildFiltered()
      Builds the set as a FilteredSet.

      Set type selection:

      • If sorted() is set: Uses TreeSet (or synchronized TreeSet if concurrent)
      • If ordered() is set: Uses LinkedHashSet (or synchronized LinkedHashSet if concurrent)
      • Otherwise: Uses HashSet (or synchronized HashSet if concurrent)
      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; FilteredSet<Integer> set = Sets.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 set will be wrapped in an unmodifiable view, which may cause issues if the FilteredSet tries to modify it internally. It's recommended to avoid using unmodifiable() when calling this method.

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

    • elementFunction

      public Sets<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 Sets<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 Sets<E> filtered()
      Applies a default filter that excludes common "empty" or "unset" values from being added to the set.

      The following values are filtered out:

      Example:

      import static org.apache.juneau.commons.utils.CollectionUtils.*; Set<Object> set = Sets.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 Sets<E> filtered(Predicate<E> filter)
      Applies a filter predicate to elements when building the set.

      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 set.

      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 Set<Integer> set = Sets.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 Set<Integer> set2 = Sets.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 Sets<E> sorted()
      Converts the set into a SortedSet.

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

      Returns:
      This object.

    • sorted

      public Sets<E> sorted(Comparator<E> comparator)
      Converts the set into a SortedSet 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 set type.

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

    • sparse

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

      Otherwise build() will never return null.

      Returns:
      This object.

    • unmodifiable

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

    • concurrent

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

      The thread-safety implementation depends on other settings:

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

      Example:

      // Create a thread-safe set using synchronized HashSet Set<String> set = Sets.create(String.class) .add("one", "two") .concurrent() .build(); // Create a thread-safe ordered set Set<String> set2 = Sets.create(String.class) .ordered() .concurrent() .add("one") .build();

      Returns:
      This object.

    • concurrent

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

      The thread-safety implementation depends on other settings:

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

      Example:

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

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

    • ordered

      public Sets<E> ordered()
      When specified, build() will use a LinkedHashSet to preserve insertion order.

      If not specified, a HashSet 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 set type.

      Example:

      // Create an ordered set (preserves insertion order) Set<String> set = Sets.create(String.class) .ordered() .add("one") .add("two") .build();

      Returns:
      This object.

    • ordered

      public Sets<E> ordered(boolean value)
      Sets whether build() should use a LinkedHashSet to preserve insertion order.

      If false (default), a HashSet is used (no guaranteed order). If true, a LinkedHashSet 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 set type.

      Example:

      // Conditionally create an ordered set Set<String> set = Sets.create(String.class) .ordered(preserveOrder) .add("one") .build();

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