Interface Reducer<C,T>

Type Parameters:
C - the type of criteria
T - the element type
All Known Implementing Classes:
RankedReducer
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Reducer<C,T>
A functional interface whose implementations can either reduce a supplied List of elements representing a successful selection to a single element normally drawn or calculated from the selection according to some criteria, or fail gracefully in the face of ambiguity by invoking a supplied failure handler.

The reduction may be a simple filtering operation, or may be a summing or aggregating operation, or anything else.

This interface is conceptually subordinate to, but should not be confused with, the Reducible interface.

Reducer implementations are often used to help build Reducible implementations. See, for example, Reducible.ofCaching(Selectable, Reducer, BiFunction).

Author:
Laird Nelson
See Also:

  • Method Details

    • reduce

      T reduce(List<? extends T> elements, C c, BiFunction<? super List<? extends T>,? super C,? extends T> failureHandler)
      Performs some kind of reductive or filtering operation on the supplied List, according to the supplied criteria, and returns the single result, or, if reduction fails, invokes the supplied BiFunction with a sublist representing a partial reduction (or an empty list representing a reduction that simply could not be performed), along with the supplied criteria, and returns its result.

      Implementations of this method must return determinate values.

      Parameters:
      elements - an immutable List to reduce; must not be null; represents a successful selection from a larger collection of elements
      c - the criteria effectively describing the initial selection and the desired reduction; may be null to indicate no criteria; may be ignored if not needed by an implementation
      failureHandler - a BiFunction receiving a failed reduction (usually a portion of the supplied elements), and the selection and reduction criteria, that returns a substitute reduction (or, more commonly, throws an exception); must not be null; must be invoked if reduction fails or undefined behavior may result
      Returns:
      a single, possibly null, element normally drawn or computed from the supplied elements, or a synthetic value returned by an invocation of the supplied failureHandler's apply(Object, Object) method
      Throws:
      NullPointerException - if elements or failureHandler is null
      ReductionException - if the failureHandler function throws a ReductionException
      See Also:

    • reduce

      default T reduce(Selectable<? super C,? extends T> f, C c, BiFunction<? super List<? extends T>,? super C,? extends T> failureHandler)
      Invokes the reduce(List, Object, BiFunction) method with the return value of an invocation of the select(Object) method on the supplied Selectable supplied with c, and the supplied c and failureHandler arguments, and returns the result.
      Parameters:
      f - a Selectable; must not be null
      c - the criteria effectively describing the initial selection and the desired reduction; may be null to indicate no criteria; may be ignored if not needed by an implementation
      failureHandler - a BiFunction receiving a failed reduction (usually a portion of the supplied elements), and the selection and reduction criteria, that returns a substitute reduction (or, more commonly, throws an exception); must not be null; must be invoked if reduction fails or undefined behavior may result
      Returns:
      a single, possibly null, element normally drawn or computed from the List returned from the supplied Selectable's select(Object) method, or a synthetic value returned by an invocation of the supplied failureHandler's apply(Object, Object) method
      Throws:
      NullPointerException - if f or failureHandler is null
      See Also:

    • reduce

      default T reduce(Selectable<? super C,? extends T> f, C c)
      Invokes the reduce(List, Object, BiFunction) method with the return value of an invocation of the select(Object) method on the supplied Selectable supplied with c, and the supplied c and a reference to the fail(List, Object) method, and returns the result.
      Parameters:
      f - a Selectable; must not be null
      c - the criteria effectively describing the initial selection and the desired reduction; may be null to indicate no criteria; may be ignored if not needed by an implementation
      Returns:
      a single, possibly null, element normally drawn or computed from the List returned from the supplied Selectable's select(Object) method, or the sole element returned by an invocation of the fail(List, Object) method
      Throws:
      NullPointerException - if f or failureHandler is null
      UnsatisfiedReductionException - if an invocation of the fail(List, Object) method throws an UnsatisfiedReductionException
      AmbiguousReductionException - if an invocation of the fail(List, Object) method throws an AmbiguousReductionException
      See Also:

    • reduce

      default T reduce(List<? extends T> elements, C c)
      Invokes the reduce(List, Object, BiFunction) method with the supplied arguments and a reference to the fail(List, Object) method, and returns the result.
      Parameters:
      elements - an immutable List to reduce; must not be null; represents a successful selection from a larger collection of elements
      c - the criteria effectively describing the initial selection and the desired reduction; may be null to indicate no criteria; may be ignored if not needed by an implementation
      Returns:
      a single, possibly null, element normally drawn or computed from the supplied elements, or a synthetic value returned by an invocation of the supplied failureHandler's apply(Object, Object) method
      Throws:
      NullPointerException - if elements is null
      See Also:

    • ofSimple

      static <C, T> Reducer<C,T> ofSimple()
      Returns a Reducer whose reduce(List, Object, BiFunction) method, for a given List of elements, returns the List's sole element if the List has exactly one element, returns null if the List is empty, and returns the result of invoking its supplied failure handler otherwise.
      Type Parameters:
      C - the type of the criteria
      T - the type of the elements
      Returns:
      a Reducer; never null
      See Also:

    • ofFailing

      static <C, T> Reducer<C,T> ofFailing()
      Returns a Reducer whose reduce(List, Object, BiFunction) method, for a given List of elements, returns the result of invoking its supplied failure handler.
      Type Parameters:
      C - the type of the criteria
      T - the type of the elements
      Returns:
      a Reducer; never null
      See Also:

    • fail

      static <C, T> T fail(List<? extends T> elements, C c)
      Throws an UnsatisfiedReductionException if elements is empty, throws an AmbiguousReductionException if the size of elements is greater than 1, and returns the sole element of elements otherwise.

      A reference to this method is often used as a failure handler in an invocation of the reduce(List, Object, BiFunction) method.

      Type Parameters:
      C - the type of the criteria
      T - the type of the elements
      Parameters:
      elements - a List of elements under reduction; must not be null
      c - a criteria object; may be null
      Returns:
      the sole element present in elements, which may be null
      Throws:
      NullPointerException - if elements is null
      UnsatisfiedReductionException - if elements is empty
      AmbiguousReductionException - if the size of elements is greater than 1
      See Also:

    • returnNull

      static <A, B, C> C returnNull(A a, B b)
      Returns null when invoked, regardless of arguments.

      A reference to this method can be used as a failure handler in an invocation of the reduce(List, Object, BiFunction) method.

      Type Parameters:
      A - the type of the first parameter; ignored
      B - the type of the second parameter; ignored
      C - the type of the return type; ignored
      Parameters:
      a - an object; may be null; ignored
      b - an object; may be null; ignored
      Returns:
      null when invoked