Package org.apache.juneau.junit.bct

Class Listifiers

java.lang.Object
org.apache.juneau.junit.bct.Listifiers
public class Listifiers extends Object
Collection of standard listifier implementations for the Bean-Centric Testing framework.

This class provides built-in list conversion strategies that handle common Java collection and iterable types. These listifiers are automatically registered when using BasicBeanConverter.Builder.defaultSettings().

Purpose:

Listifiers convert various collection-like objects to List instances for uniform processing in BCT assertions. This enables consistent iteration and element access across different data structures like arrays, iterators, streams, and custom collections.

Built-in Listifiers:
Usage Example:

// Register listifiers using builder var converter = BasicBeanConverter.builder() .defaultSettings() .addListifier(Collection.class, Listifiers.collectionListifier()) .addListifier(Stream.class, Listifiers.streamListifier()) .build();

Iterator Consumption:

Warning: Some listifiers consume their input objects during conversion:

  • Iterator: Elements are consumed and iterator becomes exhausted
  • Enumeration: Elements are consumed and enumeration becomes exhausted
  • Stream: Stream is terminated and cannot be reused
Custom Listifier Development:

When creating custom listifiers, follow these patterns:

  • Null Safety: Handle null inputs gracefully
  • Immutability: Return new lists rather than modifying inputs
  • Type Safety: Ensure proper generic type handling
  • Performance: Consider memory usage for large collections
See Also:

  • Method Details

    • collectionListifier

      public static Listifier<Collection> collectionListifier()
      Returns a listifier for Collection objects that converts them to ArrayList.

      This listifier creates a new ArrayList containing all elements from the source collection. It works with any Collection subtype including List, Set, Queue, and Deque.

      Behavior:
      • Non-empty collections: Returns new ArrayList with all elements in iteration order
      • Empty collections: Returns new empty ArrayList
      • Preserves order: Maintains the iteration order of the source collection
      • Set ordering: Converts unordered Sets (HashSet, etc.) to TreeSet for deterministic ordering
      Set Ordering Behavior:

      To ensure predictable test results, this listifier handles Sets with unreliable ordering:

      Usage Examples:

      // Test with different collection types var list = List.of("a", "b", "c"); assertList(list, "a", "b", "c"); // HashSet converted to TreeSet for predictable ordering var set = Set.of("z", "a", "m"); assertList(set, "a", "m", "z"); // Natural ordering // LinkedHashSet preserves insertion order var linkedSet = new LinkedHashSet<>(Arrays.asList("first", "second")); assertList(linkedSet, "first", "second"); var queue = new LinkedList<>(Arrays.asList("first", "second")); assertList(queue, "first", "second");

      Performance:

      This listifier creates a new ArrayList and copies all elements, so it has O(n) time and space complexity. For unordered Sets, an additional TreeSet conversion adds O(n log n) sorting overhead. For large collections, consider the memory implications.

      Returns:
      A Listifier for Collection objects
      See Also:

    • iterableListifier

      public static Listifier<Iterable> iterableListifier()
      Returns a listifier for Iterable objects that converts them using streams.

      This listifier handles any Iterable implementation by creating a stream from its spliterator and collecting elements to a list. It works with custom iterables and collection types not covered by more specific listifiers.

      Behavior:
      • Standard iterables: Converts elements to list maintaining iteration order
      • Custom iterables: Works with any object implementing Iterable interface
      • Large iterables: Processes all elements regardless of size
      Usage Examples:

      // Test with custom iterable var range = IntStream.range(1, 4).boxed().collect(toList()); assertList(range, 1, 2, 3); // Test with custom Iterable implementation var fibonacci = new FibonacciIterable(5); assertList(fibonacci, 1, 1, 2, 3, 5);

      Returns:
      A Listifier for Iterable objects
      See Also:

    • iteratorListifier

      public static Listifier<Iterator> iteratorListifier()
      Returns a listifier for Iterator objects that converts them to lists.

      Warning: This listifier consumes the iterator during conversion. After listification, the iterator will be exhausted and cannot be used again.

      Behavior:
      • Element extraction: Consumes all remaining elements from the iterator
      • Order preservation: Maintains the iterator's order in the resulting list
      • Iterator exhaustion: The iterator becomes unusable after conversion
      Usage Examples:

      // Test with list iterator var list = List.of("a", "b", "c"); var iterator = list.iterator(); assertList(iterator, "a", "b", "c"); // iterator is now exhausted // Test with custom iterator var numbers = IntStream.range(1, 4).iterator(); assertList(numbers, 1, 2, 3);

      Important Notes:
      • One-time use: The iterator becomes exhausted and unusable after conversion
      • Side effects: Any side effects in the iterator's next() method will occur
      • Exception handling: Exceptions from the iterator are propagated
      Returns:
      A Listifier for Iterator objects
      See Also:

    • enumerationListifier

      public static Listifier<Enumeration> enumerationListifier()
      Returns a listifier for Enumeration objects that converts them to lists.

      Warning: This listifier consumes the enumeration during conversion. After listification, the enumeration will be exhausted and cannot be used again.

      Behavior:
      • Element extraction: Consumes all remaining elements from the enumeration
      • Order preservation: Maintains the enumeration's order in the resulting list
      • Enumeration exhaustion: The enumeration becomes unusable after conversion
      Usage Examples:

      // Test with Vector enumeration var vector = new Vector<>(List.of("x", "y", "z")); var enumeration = vector.elements(); assertList(enumeration, "x", "y", "z"); // Test with Hashtable enumeration var table = new Hashtable<>(Map.of("key1", "value1")); var keys = table.keys(); assertList(keys, "key1");

      Returns:
      A Listifier for Enumeration objects
      See Also:

    • streamListifier

      public static Listifier<Stream> streamListifier()
      Returns a listifier for Stream objects that converts them to lists.

      Warning: This listifier terminates the stream during conversion. After listification, the stream is closed and cannot be used again.

      Behavior:
      • Stream termination: Calls toList() to collect all stream elements
      • Order preservation: Maintains stream order in the resulting list
      • Stream closure: The stream becomes unusable after conversion
      Usage Examples:

      // Test with filtered stream var numbers = IntStream.range(1, 10) .filter(n -> n % 2 == 0) .boxed(); assertList(numbers, 2, 4, 6, 8); // Test with mapped stream var words = Stream.of("hello", "world") .map(String::toUpperCase); assertList(words, "HELLO", "WORLD");

      Important Notes:
      • One-time use: The stream is terminated and cannot be reused
      • Lazy evaluation: Stream operations are executed during listification
      • Exception handling: Stream operation exceptions are propagated
      Returns:
      A Listifier for Stream objects
      See Also:

    • mapListifier

      public static Listifier<Map> mapListifier()
      Returns a listifier for Map objects that converts them to lists of Map.Entry objects.

      This listifier enables maps to be processed as lists in BCT assertions, making it easy to test map contents using list-based assertion methods.

      Behavior:
      • Entry conversion: Each key-value pair becomes a Map.Entry in the list
      • Order preservation: Maintains the map's iteration order
      • Empty maps: Returns empty list for empty maps
      • Map ordering: Converts unordered Maps (HashMap, etc.) to TreeMap for deterministic ordering
      Map Ordering Behavior:

      To ensure predictable test results, this listifier handles Maps with unreliable ordering:

      Usage Examples:

      // Test map contents with deterministic ordering var map = Map.of("z", "value1", "a", "value2"); assertSize(map, 2); // Entries will be ordered by key: [a=value2, z=value1] // LinkedHashMap preserves insertion order var linkedMap = new LinkedHashMap<>(); linkedMap.put("first", "1"); linkedMap.put("second", "2"); // Entries will maintain insertion order: [first=1, second=2] // Test empty map var emptyMap = Map.of(); assertEmpty(emptyMap); // Test map in object property var config = new Configuration().setProperties(map); assertSize(config, "properties", 2);

      Entry Processing:

      The resulting Map.Entry objects can be further processed by other parts of the conversion system, typically being stringified to "key=value" format.

      Performance:

      This listifier creates a new ArrayList from the map's entrySet. For unordered Maps, an additional TreeMap conversion adds O(n log n) sorting overhead based on key ordering. For large maps, consider the memory implications.

      Returns:
      A Listifier for Map objects
      See Also: