Streams (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.stream, class: Streams

Package org.apache.commons.lang3.stream

# Class Streams

java.lang.Object
org.apache.commons.lang3.stream.Streams

public class Streams extends Object
Provides utility functions, and classes for working with the `java.util.stream` package, or more generally, with Java 8 lambdas. More specifically, it attempts to address the fact that lambdas are supposed not to throw Exceptions, at least not checked Exceptions, AKA instances of `Exception`. This enforces the use of constructs like:

     Consumer<java.lang.reflect.Method> consumer = m -> {
         try {
             m.invoke(o, args);
         } catch (Throwable t) {
             throw Failable.rethrow(t);
         }
     };
     stream.forEach(consumer);

Using a `Streams.FailableStream`, this can be rewritten as follows:

     Streams.failable(stream).forEach(m -> m.invoke(o, args));

Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than in the first version.

Since:
  3.11
See Also:
  - `Stream`
  - `Failable`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `Streams.ArrayCollector<E>`
  A Collector type for arrays.
  `static class`
  `Streams.FailableStream<T>`
  A reduced, and simplified version of a `Stream` with failable method signatures.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Streams()`
  Deprecated.
  Will be private in 4.0.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> Streams.FailableStream<T>`
  `failableStream(Collection<T> stream)`
  Converts the given `Collection` into a `Streams.FailableStream`.
  `static <T> Streams.FailableStream<T>`
  `failableStream(Stream<T> stream)`
  Converts the given `stream` into a `Streams.FailableStream`.
  `static <T> Streams.FailableStream<T>`
  `failableStream(T value)`
  Shorthand for `Streams.failableStream(value == null ? Stream.empty() : Stream.of(value))`.
  `static <T> Streams.FailableStream<T>`
  `failableStream(T... values)`
  Shorthand for `Streams.failableStream(Streams.of(arrayValues))`.
  `static <E> Stream<E>`
  `instancesOf(Class<? super E> clazz, Collection<? super E> collection)`
  Streams only instances of the give Class in a collection.
  `static <E> Stream<E>`
  `nonNull(E array)`
  Streams the non-null element.
  `static <E> Stream<E>`
  `nonNull(E... array)`
  Streams the non-null elements of an array.
  `static <E> Stream<E>`
  `nonNull(Collection<E> collection)`
  Streams the non-null elements of a collection.
  `static <E> Stream<E>`
  `nonNull(Stream<E> stream)`
  Streams the non-null elements of a stream.
  `static <E> Stream<E>`
  `of(Iterable<E> iterable)`
  Creates a stream on the given Iterable.
  `static <E> Stream<E>`
  `of(Collection<E> collection)`
  Delegates to `Collection.stream()` or returns `Stream.empty()` if the collection is null.
  `static <E> Stream<E>`
  `of(Enumeration<E> enumeration)`
  Streams the elements of the given enumeration in order.
  `static <E> Stream<E>`
  `of(Iterator<E> iterator)`
  Creates a stream on the given Iterator.
  `static <T> Stream<T>`
  `of(T... values)`
  Null-safe version of `Stream.of(Object[])`.
  `static <E> Streams.FailableStream<E>`
  `stream(Collection<E> collection)`
  Deprecated.
  Use `failableStream(Collection)`.
  `static <T> Streams.FailableStream<T>`
  `stream(Stream<T> stream)`
  Deprecated.
  Use `failableStream(Stream)`.
  `static <T> Collector<T,?,T[]>`
  `toArray(Class<T> elementType)`
  Returns a `Collector` that accumulates the input elements into a new array.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Streams

    @Deprecated public Streams()
    Deprecated.
    Will be private in 4.0.0.
    Constructs a new instance.

- ## Method Details

  - ### failableStream

    public static <T> Streams.FailableStream<T> failableStream(Collection<T> stream)
    Converts the given `Collection` into a `Streams.FailableStream`. This is basically a simplified, reduced version of the `Stream` class, with the same underlying element stream, except that failable objects, like `FailablePredicate`, `FailableFunction`, or `FailableConsumer` may be applied, instead of `Predicate`, `Function`, or `Consumer`. The idea is to rewrite a code snippet like this:

         final List<O> list;
         final Method m;
         final Function<O, String> mapper = (o) -> {
             try {
                 return (String) m.invoke(o);
             } catch (Throwable t) {
                 throw Failable.rethrow(t);
             }
         };
         final List<String> strList = list.stream().map(mapper).collect(Collectors.toList());

    as follows:

         final List<O> list;
         final Method m;
         final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList());

    While the second version may not be quite as efficient (because it depends on the creation of additional, intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas better than the first version.
    Type Parameters:
      `T` - The streams element type.
    Parameters:
      `stream` - The stream, which is being converted.
    Returns:
      The `Streams.FailableStream`, which has been created by converting the stream.
    Since:
      3.13.0

  - ### failableStream

    public static <T> Streams.FailableStream<T> failableStream(Stream<T> stream)
    Converts the given `stream` into a `Streams.FailableStream`. This is basically a simplified, reduced version of the `Stream` class, with the same underlying element stream, except that failable objects, like `FailablePredicate`, `FailableFunction`, or `FailableConsumer` may be applied, instead of `Predicate`, `Function`, or `Consumer`. The idea is to rewrite a code snippet like this:

         final List<O> list;
         final Method m;
         final Function<O, String> mapper = (o) -> {
             try {
                 return (String) m.invoke(o);
             } catch (Throwable t) {
                 throw Failable.rethrow(t);
             }
         };
         final List<String> strList = list.stream().map(mapper).collect(Collectors.toList());

    as follows:

         final List<O> list;
         final Method m;
         final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList());

    While the second version may not be quite as efficient (because it depends on the creation of additional, intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas better than the first version.
    Type Parameters:
      `T` - The streams element type.
    Parameters:
      `stream` - The stream, which is being converted.
    Returns:
      The `Streams.FailableStream`, which has been created by converting the stream.
    Since:
      3.13.0

  - ### failableStream

    public static <T> Streams.FailableStream<T> failableStream(T value)
    Shorthand for `Streams.failableStream(value == null ? Stream.empty() : Stream.of(value))`.
    Type Parameters:
      `T` - the type of stream elements.
    Parameters:
      `value` - the single element of the new stream, may be `null`.
    Returns:
      the new FailableStream on `value` or an empty stream.
    Since:
      3.15.0

  - ### failableStream

    @SafeVarargs public static <T> Streams.FailableStream<T> failableStream(T... values)
    Shorthand for `Streams.failableStream(Streams.of(arrayValues))`.
    Type Parameters:
      `T` - the type of stream elements.
    Parameters:
      `values` - the elements of the new stream, may be `null`.
    Returns:
      the new FailableStream on `values` or an empty stream.
    Since:
      3.14.0

  - ### instancesOf

    public static <E> Stream<E> instancesOf(Class<? super E> clazz, Collection<? super E> collection)
    Streams only instances of the give Class in a collection.

    This method shorthand for:

         (Stream<E>) Streams.toStream(collection).filter(collection, SomeClass.class::isInstance);

    Type Parameters:
      `E` - the type of elements in the collection we want to stream.
    Parameters:
      `clazz` - the type of elements in the collection we want to stream.
      `collection` - the collection to stream or null.
    Returns:
      A non-null stream that only provides instances we want.
    Since:
      3.13.0

  - ### nonNull

    public static <E> Stream<E> nonNull(Collection<E> collection)
    Streams the non-null elements of a collection.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `collection` - the collection to stream or null.
    Returns:
      A non-null stream that filters out null elements.
    Since:
      3.13.0

  - ### nonNull

    public static <E> Stream<E> nonNull(E array)
    Streams the non-null element.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `array` - the element to stream or null.
    Returns:
      A non-null stream that filters out a null element.
    Since:
      3.15.0

  - ### nonNull

    @SafeVarargs public static <E> Stream<E> nonNull(E... array)
    Streams the non-null elements of an array.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `array` - the array to stream or null.
    Returns:
      A non-null stream that filters out null elements.
    Since:
      3.13.0

  - ### nonNull

    public static <E> Stream<E> nonNull(Stream<E> stream)
    Streams the non-null elements of a stream.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `stream` - the stream to stream or null.
    Returns:
      A non-null stream that filters out null elements.
    Since:
      3.13.0

  - ### of

    public static <E> Stream<E> of(Collection<E> collection)
    Delegates to `Collection.stream()` or returns `Stream.empty()` if the collection is null.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `collection` - the collection to stream or null.
    Returns:
      `Collection.stream()` or `Stream.empty()` if the collection is null.
    Since:
      3.13.0

  - ### of

    public static <E> Stream<E> of(Enumeration<E> enumeration)
    Streams the elements of the given enumeration in order.
    Type Parameters:
      `E` - The enumeration element type.
    Parameters:
      `enumeration` - The enumeration to stream.
    Returns:
      a new stream.
    Since:
      3.13.0

  - ### of

    public static <E> Stream<E> of(Iterable<E> iterable)
    Creates a stream on the given Iterable.
    Type Parameters:
      `E` - the type of elements in the Iterable.
    Parameters:
      `iterable` - the Iterable to stream or null.
    Returns:
      a new Stream or `Stream.empty()` if the Iterable is null.
    Since:
      3.13.0

  - ### of

    public static <E> Stream<E> of(Iterator<E> iterator)
    Creates a stream on the given Iterator.
    Type Parameters:
      `E` - the type of elements in the Iterator.
    Parameters:
      `iterator` - the Iterator to stream or null.
    Returns:
      a new Stream or `Stream.empty()` if the Iterator is null.
    Since:
      3.13.0

  - ### of

    @SafeVarargs public static <T> Stream<T> of(T... values)
    Null-safe version of `Stream.of(Object[])`.
    Type Parameters:
      `T` - the type of stream elements.
    Parameters:
      `values` - the elements of the new stream, may be `null`.
    Returns:
      the new stream on `values` or `Stream.empty()`.
    Since:
      3.13.0

  - ### stream

    @Deprecated public static <E> Streams.FailableStream<E> stream(Collection<E> collection)
    Deprecated.
    Use `failableStream(Collection)`.
    Converts the given `Collection` into a `Streams.FailableStream`. This is basically a simplified, reduced version of the `Stream` class, with the same underlying element stream, except that failable objects, like `FailablePredicate`, `FailableFunction`, or `FailableConsumer` may be applied, instead of `Predicate`, `Function`, or `Consumer`. The idea is to rewrite a code snippet like this:

         final List<O> list;
         final Method m;
         final Function<O, String> mapper = (o) -> {
             try {
                 return (String) m.invoke(o);
             } catch (Throwable t) {
                 throw Failable.rethrow(t);
             }
         };
         final List<String> strList = list.stream().map(mapper).collect(Collectors.toList());

    as follows:

         final List<O> list;
         final Method m;
         final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList());

    While the second version may not be quite as efficient (because it depends on the creation of additional, intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas better than the first version.
    Type Parameters:
      `E` - The streams element type.
    Parameters:
      `collection` - The stream, which is being converted.
    Returns:
      The `Streams.FailableStream`, which has been created by converting the stream.

  - ### stream

    @Deprecated public static <T> Streams.FailableStream<T> stream(Stream<T> stream)
    Deprecated.
    Use `failableStream(Stream)`.
    Converts the given `stream` into a `Streams.FailableStream`. This is basically a simplified, reduced version of the `Stream` class, with the same underlying element stream, except that failable objects, like `FailablePredicate`, `FailableFunction`, or `FailableConsumer` may be applied, instead of `Predicate`, `Function`, or `Consumer`. The idea is to rewrite a code snippet like this:

         final List<O> list;
         final Method m;
         final Function<O, String> mapper = (o) -> {
             try {
                 return (String) m.invoke(o);
             } catch (Throwable t) {
                 throw Failable.rethrow(t);
             }
         };
         final List<String> strList = list.stream().map(mapper).collect(Collectors.toList());

    as follows:

         final List<O> list;
         final Method m;
         final List<String> strList = Failable.stream(list.stream()).map((o) -> (String) m.invoke(o)).collect(Collectors.toList());

    While the second version may not be quite as efficient (because it depends on the creation of additional, intermediate objects, of type FailableStream), it is much more concise, and readable, and meets the spirit of Lambdas better than the first version.
    Type Parameters:
      `T` - The streams element type.
    Parameters:
      `stream` - The stream, which is being converted.
    Returns:
      The `Streams.FailableStream`, which has been created by converting the stream.

  - ### toArray

    public static <T> Collector<T,?,T[]> toArray(Class<T> elementType)
    Returns a `Collector` that accumulates the input elements into a new array.
    Type Parameters:
      `T` - the type of the input elements
    Parameters:
      `elementType` - Type of an element in the array.
    Returns:
      a `Collector` which collects all the input elements into an array, in encounter order