Package org.hibernate.reactive.util.async.impl

Interface Either<L,R>

Type Parameters:
L - The left type, by convention the error type if being used to represent possible errors
R - The right type, by convention the success type if being used to represent possible errors
public interface Either<L,R>
Copy of com.ibm.asyncutil.util.Either from com.ibm.async:asyncutil:0.1.0 without all the methods and imports we don't need for Hibernate Reactive. A container type that contains either an L or an R type object. An Either indicating a left value can be constructed with Either.left(value), a right with Either.right(value).

By convention, if using this class to represent a result that may be an error or a success, the error type should be in the left position and the success type should be in the right position (mnemonic: "right" also means correct). As a result, this class implements monadic methods (similar to those on Optional, Stream, etc) for working on the R type. 

 
 Either<Exception, String> tryGetString();
 Either<Exception, Integer> tryParse(String s);
 Double convert(Integer i);

 // if any intermediate step fails, will just be an Either.left(exception).
 Either<Exception, Double> eitherDouble = tryGetString() // Either<Exception, String>
  .flatMap(tryParse) // Either<Exception, Integer>
  .map(convert); // Either<Exception, Double>

  • Method Summary

    Modifier and Type
    Method
    Description
    default <V> Either<L,V>
    flatMap(Function<? super R,? extends Either<L,V>> f)
    Transforms the right type of this, producing a right Either of type V if this was right and f produced a right Either, or a left Either otherwise.
    <V> V
    fold(Function<? super L,? extends V> leftFn, Function<? super R,? extends V> rightFn)
    Applies exactly one of the two provided functions to produce a value of type V.
    default void
    forEach(Consumer<? super L> leftConsumer, Consumer<? super R> rightConsumer)
    Calls exactly one of the two provided functions with an L or an R
    default boolean
    isLeft()
    Whether this container holds an L type
    default boolean
    isRight()
    Whether this container holds an R type
    default Optional<L>
    left()
    Optionally gets the left value of this if it exists
    static <A, B> Either<A,B>
    left(A a)
    Constructs an Either with a left value
    default <A, B> Either<A,B>
    map(Function<? super L,? extends A> leftFn, Function<? super R,? extends B> rightFn)
    Creates a new Either possibly of two new and distinct types, by applying the provided transformation functions.
    default <V> Either<L,V>
    map(Function<? super R,? extends V> fn)
    Transforms the right type of this, producing an Either of the transformed value if this contained right, or an Either of the original left value otherwise.
    default Optional<R>
    right()
    Optionally gets the right value of this if it exists
    static <A, B> Either<A,B>
    right(B b)
    Constructs an Either with a right value

  • Method Details

    • isLeft

      default boolean isLeft()
      Whether this container holds an L type
      Returns:
      true if this is a Left, false otherwise

    • isRight

      default boolean isRight()
      Whether this container holds an R type
      Returns:
      true if this is a Right, false otherwise

    • fold

      <V> V fold(Function<? super L,? extends V> leftFn, Function<? super R,? extends V> rightFn)
      Applies exactly one of the two provided functions to produce a value of type V. For example, applying an int function or defaulting to zero on error: 
       
 {
   Either<Exception, Integer> either = tryGetInteger();
   int halvedOrZero = either.fold(e -> 0, i -> i / 2);
 }
      Type Parameters:
      V - the return type
      Parameters:
      leftFn - a function the produces a V from an L, only applied if this contains an L type
      rightFn - a function the produces a V from an R, only applied if this contains an R type
      Returns:
      a V value produced by leftFn if this contained an L, produced by rightFn otherwise.
      Throws:
      NullPointerException - if the function to be applied is null

    • forEach

      default void forEach(Consumer<? super L> leftConsumer, Consumer<? super R> rightConsumer)
      Calls exactly one of the two provided functions with an L or an R
      Parameters:
      leftConsumer - a function that consumes an L, only applied if this contains an L type
      rightConsumer - a function the consumes an R, only applied if this contains an R type
      Throws:
      NullPointerException - if the function to be applied is null

    • map

      default <A, B> Either<A,B> map(Function<? super L,? extends A> leftFn, Function<? super R,? extends B> rightFn)
      Creates a new Either possibly of two new and distinct types, by applying the provided transformation functions. 
       
 Either<Double, Integer> result;
 Either<String, Boolean> x = result.map(d -> d.toString(), i -> i % 2 == 0)
      Type Parameters:
      A - the left type of the returned Either
      B - the right type of the returned Either
      Parameters:
      leftFn - a function that takes an L and produces an A, to be applied if this contains an L
      rightFn - a function that takes an R and produces and B, to be applied if this contains an R
      Returns:
      a new Either, containing an A resulting from the application of leftFn if this contained an L, or containing a B resulting from the application of rightFn otherwise
      Throws:
      NullPointerException - if the function to be applied is null

    • map

      default <V> Either<L,V> map(Function<? super R,? extends V> fn)
      Transforms the right type of this, producing an Either of the transformed value if this contained right, or an Either of the original left value otherwise. For example, if we have either a Double or an error, convert it into an Integer if it's a Double, then convert it to a String if it's an Integer: 
       
 Either<Exception, Double> eitherDouble;
 Either<Exception, String> eitherString = eitherDouble.map(Double::intValue).map(Integer::toString)
      Type Parameters:
      V - the right type of the returned Either
      Parameters:
      fn - function that takes an R value and produces a V value, to be applied if this contains an R
      Returns:
      an Either containing the transformed value produced by fn if this contained an R, or the original L value otherwise.

    • flatMap

      default <V> Either<L,V> flatMap(Function<? super R,? extends Either<L,V>> f)
      Transforms the right type of this, producing a right Either of type V if this was right and f produced a right Either, or a left Either otherwise. For example, if we have either a String or an error, attempt to parse into an Integer (which could potentially itself produce an error): 
       
 Either<Exception, Integer> tryParse(String s);
 Either<Exception, String> eitherString;

 // will be an exception if eitherString was an exception
 // or if tryParse failed, otherwise will be an Integer
 Either<Exception, Integer> e = eitherString.flatMap(tryParse);
      Type Parameters:
      V - the right type of the returned Either
      Parameters:
      f - a function that takes an R value and produces an Either of a L value or a V value
      Returns:
      an Either containing the right value produced by f if both this and the produced Either were right, the left value of the produced Either if this was right but the produced value wasn't, or the original left value if this was left.

    • left

      default Optional<L> left()
      Optionally gets the left value of this if it exists
      Returns:
      a present Optional of an L if this contains an L, an empty one otherwise.
      Throws:
      NullPointerException - if the left value of this is present and null

    • right

      default Optional<R> right()
      Optionally gets the right value of this if it exists
      Returns:
      a present Optional of an R if this contains an R, an empty one otherwise.
      Throws:
      NullPointerException - if the right value of this is present and null

    • left

      static <A, B> Either<A,B> left(A a)
      Constructs an Either with a left value
      Parameters:
      a - the left element of the new Either
      Returns:
      an Either with a left value

    • right

      static <A, B> Either<A,B> right(B b)
      Constructs an Either with a right value
      Parameters:
      b - the right element of the new Either
      Returns:
      An Either with a right value