Package com.github.badpop.jcoinbase.control

Class CallResult<L,​R>

java.lang.Object
com.github.badpop.jcoinbase.control.CallResult<L,​R>
Type Parameters:
L - The type of the Failure value of an CallResult.
R - The type of the Success value of an CallResult.
All Implemented Interfaces:
FunctionalValue<R>, java.io.Serializable, java.lang.Iterable<R>
Direct Known Subclasses:
CallResult.Failure, CallResult.Success
public abstract class CallResult<L,​R>
extends java.lang.Object
implements java.lang.Iterable<R>, FunctionalValue<R>, java.io.Serializable
Call result is a simplified version of the vavr Either adapted to the JCoinbase needs. For more information, please take a look at the vavr site

CallResult represents a value of two possible types. A CallResult is callResult a CallResult.Failure or a CallResult.Success.

If the given CallResult is a Success and projected to a Failure, the Failure operations have no effect on the Success value.
If the given CallResult is a Failure and projected to a Success, the Success operations have no effect on the Failure value.
If a Failure is projected to a Failure or a Success is projected to a Success, the operations have an effect.

Example: A compute() function, which results callResult in an Integer value (in the case of success) or in an error message of type String (in the case of failure). By convention the success case is Success and the failure is Failure. 

 
 CallResult<String,Integer> value = compute().success().map(i -> i * 2).toCallResult();
If the result of compute() is Success(1), the value is Success(2).
If the result of compute() is Failure("error"), the value is Failure("error").
See Also:
Serialized Form

  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  CallResult.Failure<L,​R>
    The Failure version of a CallResult.
    static class  CallResult.FailureProjection<L,​R>
    A failure projection of a CallResult.
    static class  CallResult.Success<L,​R>
    The Success version of a CallResult.
    static class  CallResult.SuccessProjection<L,​R>
    A success projection of a CallResult.

  • Constructor Summary

    Constructors
    Constructor Description
    CallResult()  

  • Method Summary

    Modifier and Type Method Description
    <X,​ Y> CallResult<X,​Y> bimap​(java.util.function.Function<? super L,​? extends X> failureMapper, java.util.function.Function<? super R,​? extends Y> successMapper)
    Maps callResult the failure or the success side of this disjunction.
    CallResult.FailureProjection<L,​R> failure()
    Returns a FailureProjection of this CallResult.
    static <L,​ R> CallResult<L,​R> failure​(L failure)
    Constructs a CallResult.Failure
    io.vavr.control.Option<CallResult<L,​R>> filter​(java.util.function.Predicate<? super R> predicate)
    Filters this success-biased CallResult by testing a predicate.
    io.vavr.control.Option<CallResult<L,​R>> filterNot​(java.util.function.Predicate<? super R> predicate)
    Filters this success-biased CallResult by testing a predicate.
    CallResult<L,​R> filterOrElse​(java.util.function.Predicate<? super R> predicate, java.util.function.Function<? super R,​? extends L> zero)
    Filters this success-biased CallResult by testing a predicate.
    <U> CallResult<L,​U> flatMap​(java.util.function.Function<? super R,​? extends CallResult<L,​? extends U>> mapper)
    FlatMaps this success-biased CallResult.
    <U> U fold​(java.util.function.Function<? super L,​? extends U> failureMapper, java.util.function.Function<? super R,​? extends U> successMapper)
    Folds callResult the failure or the success side of this disjunction.
    abstract L getFailure()
    Returns the failure value.
    R getOrElseGet​(java.util.function.Function<? super L,​? extends R> other)
    Gets the Success value or an alternate value, if the projected CallResult is a Failure.
    <X extends java.lang.Throwable>
    R    		 getOrElseThrow​(java.util.function.Function<? super L,​X> exceptionFunction)
    Gets the Success value or throws, if the projected CallResult is a Failure.
    boolean isEmpty()
    Checks, this Value is empty, i.e. if the underlying functionalValue is absent.
    abstract boolean isFailure()
    Returns whether this CallResult is a Failure.
    abstract boolean isSuccess()
    Returns whether this CallResult is a Success.
    io.vavr.collection.Iterator<R> iterator()
    Returns a rich io.vavr.collection.Iterator.
    <U> CallResult<L,​U> map​(java.util.function.Function<? super R,​? extends U> mapper)
    Maps the value of this CallResult if it is a Success, performs no operation if this is a Failure.
    <U> CallResult<U,​R> mapFailure​(java.util.function.Function<? super L,​? extends U> failureMapper)
    Maps the value of this CallResult if it is a Failure, performs no operation if this is a Success.
    <U> CallResult<U,​R> mapLeft​(java.util.function.Function<? super L,​? extends U> leftMapper)
    Maps the value of this CallResult if it is a Failure, performs no operation if this is a Success.
    static <L,​ R> CallResult<L,​R> narrow​(CallResult<? extends L,​? extends R> callResult)
    Narrows a widened CallResult<? extends L, ? extends R> to CallResult<L, R> by performing a type-safe cast.
    CallResult<L,​R> orElse​(CallResult<? extends L,​? extends R> other)  
    CallResult<L,​R> orElse​(java.util.function.Supplier<? extends CallResult<? extends L,​? extends R>> supplier)  
    void orElseRun​(java.util.function.Consumer<? super L> action)
    Runs an action in the case this is a projection on a Failure value.
    CallResult<L,​R> peek​(java.util.function.Consumer<? super L> failureAction, java.util.function.Consumer<? super R> successAction)
    Performs the given failureAction on the failure element if this is Failure.
    CallResult<L,​R> peek​(java.util.function.Consumer<? super R> action)
    Performs the given action on the first element if this is an eager implementation.
    CallResult<L,​R> peekFailure​(java.util.function.Consumer<? super L> action)  
    CallResult<L,​R> recover​(java.util.function.Function<? super L,​? extends R> recoveryFunction)
    Calls recoveryFunction if the projected CallResult is a Failure, or returns this if Success.
    CallResult<L,​R> recoverWith​(java.util.function.Function<? super L,​? extends CallResult<? extends L,​? extends R>> recoveryFunction)
    Calls recoveryFunction if the projected CallResult is a Failure, performs no operation if this is a Success.
    static <L,​ R> CallResult<io.vavr.collection.Seq<L>,​io.vavr.collection.Seq<R>> sequence​(java.lang.Iterable<? extends CallResult<? extends L,​? extends R>> callResults)
    Reduces many CallResults into a single CallResult by transforming an Iterable<CallResult<L, R>> into a CallResult<Seq<L>, Seq<R>>.
    CallResult.SuccessProjection<L,​R> success()
    Returns a SuccessProjection of this CallResult.
    static <L,​ R> CallResult<L,​R> success​(R success)
    Constructs a CallResult.Success
    CallResult<R,​L> swap()
    Converts a Failure to a Success vice versa by wrapping the value in a new type.
    <U> U transform​(java.util.function.Function<? super CallResult<L,​R>,​? extends U> f)
    Transforms this CallResult.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface com.github.badpop.jcoinbase.control.FunctionalValue

    contains, equals, exists, forAll, get, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, hashCode, isAsync, isLazy, isSingleValued, spliterator, toCallResult, toCallResult, toJavaOptional, toOption, toString

    Methods inherited from interface java.lang.Iterable

    forEach

  • Constructor Details

    • CallResult

      public CallResult()

  • Method Details

    • success

      public static <L,​ R> CallResult<L,​R> success​(R success)
      Constructs a CallResult.Success 
      
 // Creates CallResult instance initiated with success value 1
 CallResult<?, Integer> callResult = CallResult.success(1);
      Type Parameters:
      L - Type of failure value.
      R - Type of success value.
      Parameters:
      success - The value.
      Returns:
      A new Success instance.

    • failure

      public static <L,​ R> CallResult<L,​R> failure​(L failure)
      Constructs a CallResult.Failure 
      
 // Creates CallResult instance initiated with failure value "error message"
 CallResult<String, ?> callResult = CallResult.failure("error message");
      Type Parameters:
      L - Type of failure value.
      R - Type of success value.
      Parameters:
      failure - The value.
      Returns:
      A new Failure instance.

    • narrow

      public static <L,​ R> CallResult<L,​R> narrow​(CallResult<? extends L,​? extends R> callResult)
      Narrows a widened CallResult<? extends L, ? extends R> to CallResult<L, R> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant. 
      
 // It's ok, Integer inherits from Number
 CallResult<?, Number> answer = CallResult.success(42);

 // RuntimeException is an Exception
 CallResult<Exception, ?> failed = CallResult.failure(new RuntimeException("poetry recital"));
      Type Parameters:
      L - Type of failure value.
      R - Type of success value.
      Parameters:
      callResult - A CallResult.
      Returns:
      the given callResult instance as narrowed type CallResult<L, R>.

    • sequence

      public static <L,​ R> CallResult<io.vavr.collection.Seq<L>,​io.vavr.collection.Seq<R>> sequence​(java.lang.Iterable<? extends CallResult<? extends L,​? extends R>> callResults)
      Reduces many CallResults into a single CallResult by transforming an Iterable<CallResult<L, R>> into a CallResult<Seq<L>, Seq<R>>.

      If any of the given CallResults is a CallResult.Failure then sequence returns a CallResult.Failure containing a non-empty Seq of all failure values.

      If none of the given CallResults is a CallResult.Failure then sequence returns a CallResult.Success containing a (possibly empty) Seq of all success values. 

      
 // = Success(Seq())
 CallResult.sequence(List.empty())

 // = Success(Seq(1, 2))
 CallResult.sequence(List.of(CallResult.success(1), CallResult.success(2)))

 // = Failure(Seq("x"))
 CallResult.sequence(List.of(CallResult.success(1), CallResult.failure("x")))
      Type Parameters:
      L - closure of all failure types of the given CallResults
      R - closure of all success types of the given CallResults
      Parameters:
      callResults - An Iterable of CallResults
      Returns:
      An CallResult of a Seq of failure or success values
      Throws:
      java.lang.NullPointerException - if callResults is null

    • getFailure

      public abstract L getFailure()
      Returns the failure value. 
      
 // prints "error"
 System.out.println(CallResult.failure("error").getFailure());

 // throws NoSuchElementException
 System.out.println(CallResult.success(42).getFailure());
      Returns:
      The failure value.
      Throws:
      java.util.NoSuchElementException - if this is a Success.

    • isFailure

      public abstract boolean isFailure()
      Returns whether this CallResult is a Failure. 
      
 // prints "true"
 System.out.println(CallResult.failure("error").isFailure());

 // prints "false"
 System.out.println(CallResult.success(42).isFailure());
      Returns:
      true, if this is a Failure, false otherwise

    • isSuccess

      public abstract boolean isSuccess()
      Returns whether this CallResult is a Success. 
      
 // prints "true"
 System.out.println(CallResult.success(42).isSuccess());

 // prints "false"
 System.out.println(CallResult.failure("error").isSuccess());
      Returns:
      true, if this is a Success, false otherwise

    • failure

      public final CallResult.FailureProjection<L,​R> failure()
      Returns a FailureProjection of this CallResult.
      Returns:
      a new FailureProjection of this

    • success

      public final CallResult.SuccessProjection<L,​R> success()
      Returns a SuccessProjection of this CallResult.
      Returns:
      a new SuccessProjection of this

    • bimap

      public final <X,​ Y> CallResult<X,​Y> bimap​(java.util.function.Function<? super L,​? extends X> failureMapper, java.util.function.Function<? super R,​? extends Y> successMapper)
      Maps callResult the failure or the success side of this disjunction. 
      
 CallResult<?, AtomicInteger> success = CallResult.success(new AtomicInteger(42));

 // prints "Success(42)"
 System.out.println(success.bimap(Function1.identity(), AtomicInteger::get));

 CallResult<Exception, ?> failure = CallResult.failure(new Exception("error"));

 // prints "Failure(error)"
 System.out.println(failure.bimap(Exception::getMessage, Function1.identity()));
      Type Parameters:
      X - The new failure type of the resulting CallResult
      Y - The new success type of the resulting CallResult
      Parameters:
      failureMapper - maps the failure value if this is a Failure
      successMapper - maps the success value if this is a Success
      Returns:
      A new CallResult instance

    • fold

      public final <U> U fold​(java.util.function.Function<? super L,​? extends U> failureMapper, java.util.function.Function<? super R,​? extends U> successMapper)
      Folds callResult the failure or the success side of this disjunction. 
      
 CallResult<Exception, Integer> success = CallResult.success(3);

 // prints "Users updated: 3"
 System.out.println(success.fold(Exception::getMessage, count -> "Users updated: " + count));

 CallResult<Exception, Integer> failure = CallResult.failure(new Exception("Failed to update users"));

 // prints "Failed to update users"
 System.out.println(failure.fold(Exception::getMessage, count -> "Users updated: " + count));
      Type Parameters:
      U - type of the folded value
      Parameters:
      failureMapper - maps the failure value if this is a Failure
      successMapper - maps the success value if this is a Success
      Returns:
      A value of type U

    • transform

      public final <U> U transform​(java.util.function.Function<? super CallResult<L,​R>,​? extends U> f)
      Transforms this CallResult. 
      
 // prints "Answer is 42"
 System.out.println(CallResult.success(42).<String> transform(e -> "Answer is " + e.get()));
      Type Parameters:
      U - Type of transformation result
      Parameters:
      f - A transformation
      Returns:
      An instance of type U
      Throws:
      java.lang.NullPointerException - if f is null

    • getOrElseGet

      public final R getOrElseGet​(java.util.function.Function<? super L,​? extends R> other)
      Gets the Success value or an alternate value, if the projected CallResult is a Failure. 
      
 // prints "42"
 System.out.println(CallResult.success(42).getOrElseGet(l -> -1));

 // prints "13"
 System.out.println(CallResult.failure("error message").getOrElseGet(String::length));
      Parameters:
      other - a function which converts a Failure value to an alternative Success value
      Returns:
      the success value, if the underlying CallResult is a Success or else the alternative Success value provided by other by applying the Failure value.

    • orElseRun

      public final void orElseRun​(java.util.function.Consumer<? super L> action)
      Runs an action in the case this is a projection on a Failure value. 
      
 // prints "no value found"
 CallResult.failure("no value found").orElseRun(System.out::println);
      Parameters:
      action - an action which consumes a Failure value

    • getOrElseThrow

      public final <X extends java.lang.Throwable> R getOrElseThrow​(java.util.function.Function<? super L,​X> exceptionFunction) throws X extends java.lang.Throwable
      Gets the Success value or throws, if the projected CallResult is a Failure. 
      
 Function<String, RuntimeException> exceptionFunction = RuntimeException::new;
 // prints "42"
 System.out.println(CallResult.<String, Integer>success(42).getOrElseThrow(exceptionFunction));

 // throws RuntimeException("no value found")
 CallResult.failure("no value found").getOrElseThrow(exceptionFunction);
      Type Parameters:
      X - a throwable type
      Parameters:
      exceptionFunction - a function which creates an exception based on a Failure value
      Returns:
      the success value, if the underlying CallResult is a Success or else throws the exception provided by exceptionFunction by applying the Failure value.
      Throws:
      X - if the projected CallResult is a Failure

    • swap

      public final CallResult<R,​L> swap()
      Converts a Failure to a Success vice versa by wrapping the value in a new type. 
      
 // prints "Success(42)"
 System.out.println(CallResult.failure(42).swap());

 // prints "Failure(message)"
 System.out.println(CallResult.success("message").swap());
      Returns:
      a new CallResult

    • recoverWith

      public final CallResult<L,​R> recoverWith​(java.util.function.Function<? super L,​? extends CallResult<? extends L,​? extends R>> recoveryFunction)
      Calls recoveryFunction if the projected CallResult is a Failure, performs no operation if this is a Success. This is similar to getOrElseGet, but where the fallback method also returns an CallResult. 
      
 CallResult<Integer, String> tryGetString() { return CallResult.failure(1); }

 CallResult<Integer, String> tryGetStringAnotherWay(Integer lvalue) { return CallResult.success("yo " + lvalue); }

 = Success("yo 1")
 tryGetString().recover(this::tryGetStringAnotherWay);
      Parameters:
      recoveryFunction - a function which accepts a Failure value and returns an CallResult
      Returns:
      an CallResult<L, R> instance
      Throws:
      java.lang.NullPointerException - if the given recoveryFunction is null

    • recover

      public final CallResult<L,​R> recover​(java.util.function.Function<? super L,​? extends R> recoveryFunction)
      Calls recoveryFunction if the projected CallResult is a Failure, or returns this if Success. The result of recoveryFunction will be projected as a Success. 
      
 CallResult<Integer, String> tryGetString() { return CallResult.failure(1); }

 String getStringAnotherWay() { return "yo"; }

 = Success("yo")
 tryGetString().recover(this::getStringAnotherWay);
      Parameters:
      recoveryFunction - a function which accepts a Failure value and returns a Success value
      Returns:
      an CallResult<L, R> instance
      Throws:
      java.lang.NullPointerException - if the given recoveryFunction is null

    • flatMap

      public final <U> CallResult<L,​U> flatMap​(java.util.function.Function<? super R,​? extends CallResult<L,​? extends U>> mapper)
      FlatMaps this success-biased CallResult. 
      
 // prints "Success(42)"
 System.out.println(CallResult.success(21).flatMap(v -> CallResult.success(v * 2)));

 // prints "Failure(error message)"
 System.out.println(CallResult.failure("error message").flatMap(CallResult::success));
      Type Parameters:
      U - Component type of the mapped success value
      Parameters:
      mapper - A mapper
      Returns:
      this as CallResult<L, U> if this is a Failure, otherwise the success mapping result
      Throws:
      java.lang.NullPointerException - if mapper is null

    • map

      public final <U> CallResult<L,​U> map​(java.util.function.Function<? super R,​? extends U> mapper)
      Maps the value of this CallResult if it is a Success, performs no operation if this is a Failure. 
      
 // = Success("A")
 CallResult.success("a").map(String::toUpperCase);

 // = Failure(1)
 CallResult.failure(1).map(String::toUpperCase);
      Specified by:
      map in interface FunctionalValue<L>
      Type Parameters:
      U - Component type of the mapped success value
      Parameters:
      mapper - A mapper
      Returns:
      a mapped Monad
      Throws:
      java.lang.NullPointerException - if mapper is null

    • mapLeft

      public final <U> CallResult<U,​R> mapLeft​(java.util.function.Function<? super L,​? extends U> leftMapper)
      Maps the value of this CallResult if it is a Failure, performs no operation if this is a Success. 
      
 // = Failure(2)
 CallResult.failure(1).mapLeft(i -> i + 1);

 // = Success("a")
 CallResult.success("a").mapLeft(i -> i + 1);
      Type Parameters:
      U - Component type of the mapped right value
      Parameters:
      leftMapper - A mapper
      Returns:
      a mapped Monad
      Throws:
      java.lang.NullPointerException - if mapper is null

    • mapFailure

      public final <U> CallResult<U,​R> mapFailure​(java.util.function.Function<? super L,​? extends U> failureMapper)
      Maps the value of this CallResult if it is a Failure, performs no operation if this is a Success. 
      
 // = Failure(2)
 CallResult.failure(1).mapFailure(i -> i + 1);

 // = Success("a")
 CallResult.success("a").mapFailure(i -> i + 1);
      Type Parameters:
      U - Component type of the mapped success value
      Parameters:
      failureMapper - A mapper
      Returns:
      a mapped Monad
      Throws:
      java.lang.NullPointerException - if mapper is null

    • filter

      public final io.vavr.control.Option<CallResult<L,​R>> filter​(java.util.function.Predicate<? super R> predicate)
      Filters this success-biased CallResult by testing a predicate.

      Parameters:
      predicate - A predicate
      Returns:
      a new Option instance
      Throws:
      java.lang.NullPointerException - if predicate is null

    • filterNot

      public final io.vavr.control.Option<CallResult<L,​R>> filterNot​(java.util.function.Predicate<? super R> predicate)
      Filters this success-biased CallResult by testing a predicate.
      Parameters:
      predicate - A predicate
      Returns:
      a new CallResult
      Throws:
      java.lang.NullPointerException - if predicate is null

    • filterOrElse

      public final CallResult<L,​R> filterOrElse​(java.util.function.Predicate<? super R> predicate, java.util.function.Function<? super R,​? extends L> zero)
      Filters this success-biased CallResult by testing a predicate. If the CallResult is a Success and the predicate doesn't match, the CallResult will be turned into a Failure with contents computed by applying the zero function to the CallResult value. 
      
 // = Failure("bad: a")
 CallResult.success("a").filterOrElse(i -> false, val -> "bad: " + val);

 // = Success("a")
 CallResult.success("a").filterOrElse(i -> true, val -> "bad: " + val);
      Parameters:
      predicate - A predicate
      zero - A function that turns a success value into a failure value if the success value does not make it through the filter.
      Returns:
      an CallResult instance
      Throws:
      java.lang.NullPointerException - if predicate is null

    • isEmpty

      public final boolean isEmpty()
      Description copied from interface: FunctionalValue
      Checks, this Value is empty, i.e. if the underlying functionalValue is absent.
      Specified by:
      isEmpty in interface FunctionalValue<L>
      Returns:
      false, if no underlying functionalValue is present, true otherwise.

    • orElse

      public final CallResult<L,​R> orElse​(CallResult<? extends L,​? extends R> other)

    • orElse

      public final CallResult<L,​R> orElse​(java.util.function.Supplier<? extends CallResult<? extends L,​? extends R>> supplier)

    • iterator

      public final io.vavr.collection.Iterator<R> iterator()
      Description copied from interface: FunctionalValue
      Returns a rich io.vavr.collection.Iterator.
      Specified by:
      iterator in interface FunctionalValue<L>
      Specified by:
      iterator in interface java.lang.Iterable<L>
      Returns:
      A new Iterator

    • peek

      public final CallResult<L,​R> peek​(java.util.function.Consumer<? super L> failureAction, java.util.function.Consumer<? super R> successAction)
      Performs the given failureAction on the failure element if this is Failure. Performs the given successAction on the success element if this is Success.
      Parameters:
      failureAction - The action that will be performed on the failure element
      successAction - The action that will be performed on the success element
      Returns:
      this instance

    • peek

      public final CallResult<L,​R> peek​(java.util.function.Consumer<? super R> action)
      Description copied from interface: FunctionalValue
      Performs the given action on the first element if this is an eager implementation. Performs the given action on all elements (the first immediately, successive deferred), if this is a lazy implementation.
      Specified by:
      peek in interface FunctionalValue<L>
      Parameters:
      action - The action that will be performed on the element(s).
      Returns:
      this instance

    • peekFailure

      public final CallResult<L,​R> peekFailure​(java.util.function.Consumer<? super L> action)