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

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default <V> Either<L,​V> flatMap​(java.util.function.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​(java.util.function.Function<? super L,​? extends V> leftFn, java.util.function.Function<? super R,​? extends V> rightFn)
      Applies exactly one of the two provided functions to produce a value of type V.
      default void forEach​(java.util.function.Consumer<? super L> leftConsumer, java.util.function.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 java.util.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​(java.util.function.Function<? super L,​? extends A> leftFn, java.util.function.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​(java.util.function.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 java.util.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 Detail

      • 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​(java.util.function.Function<? super L,​? extends V> leftFn,
           java.util.function.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:
        java.lang.NullPointerException - if the function to be applied is null

      • forEach

        default void forEach​(java.util.function.Consumer<? super L> leftConsumer,
                     java.util.function.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:
        java.lang.NullPointerException - if the function to be applied is null

      • map

        default <A,​B> Either<A,​B> map​(java.util.function.Function<? super L,​? extends A> leftFn,
                                          java.util.function.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:
        java.lang.NullPointerException - if the function to be applied is null

      • map

        default <V> Either<L,​V> map​(java.util.function.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​(java.util.function.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 java.util.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:
        java.lang.NullPointerException - if the left value of this is present and null

      • right

        default java.util.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:
        java.lang.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