Package com.leakyabstractions.result.api

Interface Result<S,F>

Type Parameters:
S - the type of the success value
F - the type of the failure value
public interface Result<S,F>
Encapsulates a single non-null value, representing the outcome of an operation that can either succeed or fail.
  • Successful results hold a value of type S, indicating that the operation has completed as intended.
  • Failed results hold a value of type F, indicating that the operation did not complete as intended.

The exact definitions of success and failure depend on the semantics of the operation.

Author:
Guillermo Calvo
See Also:
API Note:
Result is primarily, but not only, intended for use as a method return type to handle anticipated failures without throwing exceptions or returning null.
Impl Spec:
This is a value-based type; use of identity-sensitive operations on instances of Result should be avoided.

  • Method Details

    • hasSuccess

      boolean hasSuccess()
      Checks if this Result is successful. 

        
 Result<Integer, String> r = getResult();
 boolean x = r.hasSuccess();
      Returns:
      if this Result is successful, true; otherwise, false
      See Also:

    • hasFailure

      boolean hasFailure()
      Checks if this Result is failed. 

        
 Result<Integer, String> r = getResult();
 boolean x = r.hasFailure();
      Returns:
      if this Result is failed, true; otherwise, false
      See Also:

    • getSuccess

      Optional<S> getSuccess()
      Returns this Result's success value as a possibly-empty Optional. 

        
 Result<Integer, String> r = getResult();
 Optional<Integer> x = r.getSuccess();
      Returns:
      if this Result is successful, an Optional containing its value; otherwise, an empty Optional
      See Also:

    • getFailure

      Optional<F> getFailure()
      Returns this Result's failure value as a possibly-empty Optional. 

        
 Result<Integer, String> r = getResult();
 Optional<String> x = r.getFailure();
      Returns:
      if this Result is failed, an Optional containing its value; otherwise, an empty Optional
      See Also:

    • orElse

      S orElse(S other)
      Returns this Result's success value, or the alternative one. 

        
 Result<Integer, String> r = getResult();
 int x = r.orElse(8);
      Parameters:
      other - the alternative success value; may be null
      Returns:
      if this Result is successful, its value; otherwise other
      See Also:

    • orElseMap

      S orElseMap(Function<? super F,? extends S> mapper)
      Returns this Result's success value, or maps its failure value.

      If this Result is failed, mapper will be applied to its value to produce an alternative success value. 

        
 Result<Integer, String> r = getResult();
 int x = r.orElseMap(f -> 8);
      Parameters:
      mapper - the mapping Function that produces the alternative success value; may return null
      Returns:
      if this Result is successful, its value; otherwise the value produced by mapper
      Throws:
      NullPointerException - if this Result is failed and mapper is null
      See Also:

    • streamSuccess

      Stream<S> streamSuccess()
      Returns this Result's success value as a possibly-empty Stream. 

        
 Result<Integer, String> r = getResult();
 Stream<Integer> x = r.streamSuccess();
      Returns:
      If this Result is successful, a sequential Stream containing only its value; otherwise an empty Stream

    • streamFailure

      Stream<F> streamFailure()
      Returns this Result's failure value as a possibly-empty Stream. 

        
 Result<Integer, String> r = getResult();
 Stream<String> x = r.streamFailure();
      Returns:
      if this Result is failed, a sequential Stream containing only its value; otherwise an empty Stream

    • ifSuccess

      Result<S,F> ifSuccess(Consumer<? super S> action)
      Performs the given action with this Result's success value.

      If this Result is successful, performs action with its value; otherwise does nothing. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifSuccess(System.out::println);
      Parameters:
      action - the Consumer to be applied to this Result's success value
      Returns:
      this Result
      Throws:
      NullPointerException - if this Result is successful and action is null
      See Also:

    • ifFailure

      Result<S,F> ifFailure(Consumer<? super F> action)
      Performs the given action with this Result's failure value.

      If this Result is failed, performs action with its value; otherwise does nothing. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifFailure(System.err::println);
      Parameters:
      action - the Consumer to be applied to this Result's failure value
      Returns:
      this Result
      Throws:
      NullPointerException - if this Result is failed and action is null
      See Also:

    • ifSuccessOrElse

      Result<S,F> ifSuccessOrElse(Consumer<? super S> successAction, Consumer<? super F> failureAction)
      Performs either of the given actions with this Result's value.

      If this Result is successful, performs successAction; otherwise performs failureAction. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifSuccessOrElse(System.out::println, System.err::println);
      Parameters:
      successAction - the Consumer to be applied to this Result's success value
      failureAction - the Consumer to be applied to this Result's failure value
      Returns:
      this Result
      Throws:
      NullPointerException - if this Result is successful and successAction is null; or if it is failed and failureAction is null
      See Also:

    • filter

      Result<S,F> filter(Predicate<? super S> isAcceptable, Function<? super S,? extends F> mapper)
      Transforms this successful Result into a failed one, based on the given condition.

      If this is a successful Result whose value does not satisfy isAcceptable, mapper will be applied to the value to produce a failure value. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.filter(s -> s < 3, s -> "E");
      Parameters:
      isAcceptable - the Predicate to apply to this Result's success value
      mapper - the mapping Function that produces the failure value
      Returns:
      if this is a successful Result whose value is deemed not acceptable, a new failed Result holding the value produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is successful and isAcceptable is null; or if its success value is not acceptable and mapper is null or returns null
      See Also:

    • recover

      Result<S,F> recover(Predicate<? super F> isRecoverable, Function<? super F,? extends S> mapper)
      Transforms this failed Result into a successful one, based on the given condition.

      If this is a failed Result whose value satisfies isRecoverable, mapper will be applied to the value to produce a success value. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.recover("B"::equals, f -> 5);
      Parameters:
      isRecoverable - the Predicate to apply to this Result's failure value
      mapper - the mapping Function that produces the success value
      Returns:
      if this is a failed Result whose value is deemed recoverable, a new successful Result holding the value produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is failed and isRecoverable is null; or if its failure value is recoverable and mapper is null or returns null
      See Also:

    • mapSuccess

      <S2> Result<S2,F> mapSuccess(Function<? super S,? extends S2> mapper)
      Transforms this Result's success value.

      If this Result is successful, mapper will be applied to its value to produce a new one, which may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Fruit, String> x = r.mapSuccess(s -> CHERRIES);
      Type Parameters:
      S2 - the type of the value returned by mapper
      Parameters:
      mapper - the mapping Function that produces the new success value
      Returns:
      if this is a successful Result, a new successful Result holding the value produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is successful and mapper is null or returns null
      See Also:

    • mapFailure

      <F2> Result<S,F2> mapFailure(Function<? super F,? extends F2> mapper)
      Transforms this Result's failure value.

      If this Result is failed, mapper will be applied to its value to produce a new one, which may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, Suit> x = r.mapFailure(f -> CLUBS);
      Type Parameters:
      F2 - the type of the value returned by mapper
      Parameters:
      mapper - the mapping Function that produces the new failure value
      Returns:
      if this is a failed Result, a new failed Result holding the value produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is failed and mapper is null or returns null
      See Also:

    • map

      <S2, F2> Result<S2,F2> map(Function<? super S,? extends S2> successMapper, Function<? super F,? extends F2> failureMapper)
      Transforms this Result's success or failure value.

      If this is Result is successful, successMapper will be applied to its value to produce a new one. Otherwise, failureMapper will be applied to its failure value to produce a new one.

      Both success and failure values may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Fruit, Suit> x = r.map(s -> CHERRIES, f -> CLUBS);
      Type Parameters:
      S2 - the type of the value returned by successMapper
      F2 - the type of the value returned by failureMapper
      Parameters:
      successMapper - the mapping Function that produces the new success value
      failureMapper - the mapping Function that produces the new failure value
      Returns:
      if this is a successful Result, a new successful Result holding the value produced by successMapper; otherwise, a new failed Result holding the value produced by failureMapper
      Throws:
      NullPointerException - if this result is successful and successMapper is null or returns null; or if this Result is failed and failureMapper is null or returns null
      See Also:

    • flatMapSuccess

      <S2> Result<S2,F> flatMapSuccess(Function<? super S,? extends Result<? extends S2,? extends F>> mapper)
      Transforms this successful Result into a different one.

      If this Result is successful, mapper will be applied to its value to produce a new Result, which may now hold either a success or a failure value. New success value may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Fruit, String> x = r.flatMapSuccess(s -> s < 3 ? success(CHERRIES) : failure("E"));
      Type Parameters:
      S2 - the success type of the Result returned by mapper
      Parameters:
      mapper - the mapping Function that produces a new Result
      Returns:
      if this Result is successful, a new Result produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is successful and mapper is null or returns null
      See Also:

    • flatMapFailure

      <F2> Result<S,F2> flatMapFailure(Function<? super F,? extends Result<? extends S,? extends F2>> mapper)
      Transforms this failed Result into a different one.

      If this Result is failed, mapper will be applied to its value to produce a new Result, which may now hold either a success or a failure value. New failure value may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Integer, Suit> x = r.flatMapFailure(f -> f.equals("B") ? success(5) : failure(CLUBS));
      Type Parameters:
      F2 - the failure type of the Result returned by mapper
      Parameters:
      mapper - the mapping Function that produces a new Result
      Returns:
      if this Result is failed, a new Result produced by mapper; otherwise, this Result
      Throws:
      NullPointerException - if this Result is failed and mapper is null or returns null
      See Also:

    • flatMap

      <S2, F2> Result<S2,F2> flatMap(Function<? super S,? extends Result<? extends S2,? extends F2>> successMapper, Function<? super F,? extends Result<? extends S2,? extends F2>> failureMapper)
      Transforms this Result into a different one.

      If this Result is successful, successMapper will be applied to its value to produce a new Result; otherwise, failureMapper will be applied to its value to produce a new Result.

      The new Result may now hold either a success or a failure value. Both may differ in type. 

        
 Result<Integer, String> r = getResult();
 Result<Fruit, Suit> x = r.flatMap(s -> s < 3 ? success(CHERRIES) : failure(SPADES),
     f -> f.equals("B") ? success(WATERMELON) : failure(CLUBS));
      Type Parameters:
      S2 - the success type of the Result returned by successMapper and failureMapper
      F2 - the failure type of the Result returned by successMapper and failureMapper
      Parameters:
      successMapper - the mapping Function that produces a new Result if this Result is successful
      failureMapper - the mapping Function that produces a new Result if this Result is failed
      Returns:
      the Result produced by either successMapper or failureMapper
      Throws:
      NullPointerException - if this Result is successful and successMapper is null or returns null; or if this Result is failed and failureMapper is null or returns null
      See Also:

    • equals

      boolean equals(Object obj)
      Indicates whether some other object is "equal to" this Result.

      The other object is considered equal if:

      • it is also a Result and;
      • both objects are instances of the same class and;
      • their values are "equal to" each other via equals().
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to be tested for equality
      Returns:
      true if the other object is "equal to" this object; otherwise false
      See Also:

    • hashCode

      int hashCode()
      Returns the hash code of this Result's value.
      Overrides:
      hashCode in class Object
      Returns:
      hash code value of this Result's value

    • toString

      String toString()
      Returns a string representation of this Result.

      The exact presentation format is unspecified and may vary between implementations and versions.

      Overrides:
      toString in class Object
      Returns:
      a string representation of this Result
      Impl Spec:
      The returned string should be suitable for debugging and must include the string representation of its value. Successful and failed Result instances must be unambiguously differentiable.