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

Package org.apache.commons.lang3.stream

# Class Streams.FailableStream<T>

java.lang.Object
org.apache.commons.lang3.stream.Streams.FailableStream<T>

Type Parameters:
  `T` - The streams element type.

Enclosing class:
  Streams

public static class Streams.FailableStream<T> extends Object
A reduced, and simplified version of a `Stream` with failable method signatures.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FailableStream(Stream<T> stream)`
  Constructs a new instance with the given `stream`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `allMatch(FailablePredicate<T,?> predicate)`
  Returns whether all elements of this stream match the provided predicate.
  `boolean`
  `anyMatch(FailablePredicate<T,?> predicate)`
  Returns whether any elements of this stream match the provided predicate.
  `protected void`
  `assertNotTerminated()`
  Throws IllegalStateException if this stream is already terminated.
  `<A, R> R`
  `collect(Supplier<R> supplier, BiConsumer<R,? super T> accumulator, BiConsumer<R,R> combiner)`
  Performs a mutable reduction operation on the elements of this FailableStream.
  `<A, R> R`
  `collect(Collector<? super T,A,R> collector)`
  Performs a mutable reduction operation on the elements of this stream using a `Collector`.
  `Streams.FailableStream<T>`
  `filter(FailablePredicate<T,?> predicate)`
  Returns a FailableStream consisting of the elements of this stream that match the given FailablePredicate.
  `void`
  `forEach(FailableConsumer<T,?> action)`
  Performs an action for each element of this stream.
  `protected void`
  `makeTerminated()`
  Marks this stream as terminated.
  `<R> Streams.FailableStream<R>`
  `map(FailableFunction<T,R,?> mapper)`
  Returns a stream consisting of the results of applying the given function to the elements of this stream.
  `T`
  `reduce(T identity, BinaryOperator<T> accumulator)`
  Performs a reduction on the elements of this stream, using the provided identity value and an associative accumulation function, and returns the reduced value.
  `Stream<T>`
  `stream()`
  Converts the FailableStream into an equivalent stream.

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

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

- ## Constructor Details

  - ### FailableStream

    public FailableStream(Stream<T> stream)
    Constructs a new instance with the given `stream`.
    Parameters:
      `stream` - The stream.

- ## Method Details

  - ### allMatch

    public boolean allMatch(FailablePredicate<T,?> predicate)
    Returns whether all elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then `true` is returned and the predicate is not evaluated.

    This is a short-circuiting terminal operation.

    Note This method evaluates the universal quantification of the predicate over the elements of the stream (for all x P(x)). If the stream is empty, the quantification is said to be vacuously satisfied and is always `true` (regardless of P(x)).
    Parameters:
      `predicate` - A non-interfering, stateless predicate to apply to elements of this stream
    Returns:
      `true` If either all elements of the stream match the provided predicate or the stream is empty, otherwise `false`.

  - ### anyMatch

    public boolean anyMatch(FailablePredicate<T,?> predicate)
    Returns whether any elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then `false` is returned and the predicate is not evaluated.

    This is a short-circuiting terminal operation.

    Note This method evaluates the existential quantification of the predicate over the elements of the stream (for some x P(x)).
    Parameters:
      `predicate` - A non-interfering, stateless predicate to apply to elements of this stream
    Returns:
      `true` if any elements of the stream match the provided predicate, otherwise `false`

  - ### assertNotTerminated

    protected void assertNotTerminated()
    Throws IllegalStateException if this stream is already terminated.
    Throws:
      `IllegalStateException` - if this stream is already terminated.

  - ### collect

    public <A, R> R collect(Collector<? super T,A,R> collector)
    Performs a mutable reduction operation on the elements of this stream using a `Collector`. A `Collector` encapsulates the functions used as arguments to `collect(Supplier, BiConsumer, BiConsumer)`, allowing for reuse of collection strategies and composition of collect operations such as multiple-level grouping or partitioning.

    If the underlying stream is parallel, and the `Collector` is concurrent, and either the stream is unordered or the collector is unordered, then a concurrent reduction will be performed (see `Collector` for details on concurrent reduction.)

    This is a terminal operation.

    When executed in parallel, multiple intermediate results may be instantiated, populated, and merged so as to maintain isolation of mutable data structures. Therefore, even when executed in parallel with non-thread-safe data structures (such as `ArrayList`), no additional synchronization is needed for a parallel reduction.

    Note The following will accumulate strings into an ArrayList:

             List<String> asList = stringStream.collect(Collectors.toList());

    The following will classify `Person` objects by city:

             Map<String, List<Person>> peopleByCity = personStream.collect(Collectors.groupingBy(Person::getCity));

    The following will classify `Person` objects by state and city, cascading two `Collector`s together:

             Map<String, Map<String, List<Person>>> peopleByStateAndCity = personStream
                 .collect(Collectors.groupingBy(Person::getState, Collectors.groupingBy(Person::getCity)));

    Type Parameters:
      `R` - the type of the result
      `A` - the intermediate accumulation type of the `Collector`
    Parameters:
      `collector` - the `Collector` describing the reduction
    Returns:
      the result of the reduction
    See Also:
      - `collect(Supplier, BiConsumer, BiConsumer)`
      - `Collectors`

  - ### collect

    public <A, R> R collect(Supplier<R> supplier, BiConsumer<R,? super T> accumulator, BiConsumer<R,R> combiner)
    Performs a mutable reduction operation on the elements of this FailableStream. A mutable reduction is one in which the reduced value is a mutable result container, such as an `ArrayList`, and elements are incorporated by updating the state of the result rather than by replacing the result. This produces a result equivalent to:

             R result = supplier.get();
             for (T element : this stream)
                 accumulator.accept(result, element);
             return result;

    Like `reduce(Object, BinaryOperator)`, `collect` operations can be parallelized without requiring additional synchronization.

    This is a terminal operation.

    Note There are many existing classes in the JDK whose signatures are well-suited for use with method references as arguments to `collect()`. For example, the following will accumulate strings into an `ArrayList`:

             List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);

    The following will take a stream of strings and concatenates them into a single string:

             String concat = stringStream.collect(StringBuilder::new, StringBuilder::append, StringBuilder::append).toString();

    Type Parameters:
      `R` - type of the result
      `A` - Type of the accumulator.
    Parameters:
      `supplier` - a function that creates a new result container. For a parallel execution, this function may be called multiple times and must return a fresh value each time.
      `accumulator` - An associative, non-interfering, stateless function for incorporating an additional element into a result
      `combiner` - An associative, non-interfering, stateless function for combining two values, which must be compatible with the accumulator function
    Returns:
      The result of the reduction

  - ### filter

    public Streams.FailableStream<T> filter(FailablePredicate<T,?> predicate)
    Returns a FailableStream consisting of the elements of this stream that match the given FailablePredicate.

    This is an intermediate operation.

    Parameters:
      `predicate` - a non-interfering, stateless predicate to apply to each element to determine if it should be included.
    Returns:
      the new stream

  - ### forEach

    public void forEach(FailableConsumer<T,?> action)
    Performs an action for each element of this stream.

    This is a terminal operation.

    The behavior of this operation is explicitly nondeterministic. For parallel stream pipelines, this operation does not guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the action may be performed at whatever time and in whatever thread the library chooses. If the action accesses shared state, it is responsible for providing the required synchronization.

    Parameters:
      `action` - a non-interfering action to perform on the elements

  - ### makeTerminated

    protected void makeTerminated()
    Marks this stream as terminated.
    Throws:
      `IllegalStateException` - if this stream is already terminated.

  - ### map

    public <R> Streams.FailableStream<R> map(FailableFunction<T,R,?> mapper)
    Returns a stream consisting of the results of applying the given function to the elements of this stream.

    This is an intermediate operation.

    Type Parameters:
      `R` - The element type of the new stream
    Parameters:
      `mapper` - A non-interfering, stateless function to apply to each element
    Returns:
      the new stream

  - ### reduce

    public T reduce(T identity, BinaryOperator<T> accumulator)
    Performs a reduction on the elements of this stream, using the provided identity value and an associative accumulation function, and returns the reduced value. This is equivalent to:

             T result = identity;
             for (T element : this stream)
                 result = accumulator.apply(result, element)
             return result;

    but is not constrained to execute sequentially.

    The `identity` value must be an identity for the accumulator function. This means that for all `t`, `accumulator.apply(identity, t)` is equal to `t`. The `accumulator` function must be an associative function.

    This is a terminal operation.

    Note Sum, min, max, average, and string concatenation are all special cases of reduction. Summing a stream of numbers can be expressed as:

             Integer sum = integers.reduce(0, (a, b) -> a + b);

    or:

             Integer sum = integers.reduce(0, Integer::sum);

    While this may seem a more roundabout way to perform an aggregation compared to simply mutating a running total in a loop, reduction operations parallelize more gracefully, without needing additional synchronization and with greatly reduced risk of data races.

    Parameters:
      `identity` - the identity value for the accumulating function
      `accumulator` - an associative, non-interfering, stateless function for combining two values
    Returns:
      the result of the reduction

  - ### stream

    public Stream<T> stream()
    Converts the FailableStream into an equivalent stream.
    Returns:
      A stream, which will return the same elements, which this FailableStream would return.