Interface Result<V,​E>

  • Type Parameters:
    V - The value type of the Result.
    E - The error type of the Result.
    All Known Implementing Classes:
    Err, Ok

    public interface Result<V,​E>
    The Result type is an alternative way of chaining together functions in a functional programming style while hiding away error handling structures such as try-catch-blocks and conditionals.
    Instead of adding a throws declaration to a function, the return type of the function is instead set to Result where V is the original return type, i.e. the "happy case" and E is the error type, usually the Exception type or a String if an error explanation is sufficient.

    Example:
     public Result divide(int a, int b) {
            if (b == 0) {
                    return Result.err("Can't divide by zero!");
            } else {
                    return Result.ok(a / b);
            }
     }
     
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void accept​(ConsumerWithException<? super V> ok, ConsumerWithException<? super E> err)
      Terminal function that processes the result or the error
      <X> Result<X,​E> asError()  
      static <V,​E>
      Result<V,​E>
      err​(E error)
      Returns an Err containing the specified error.
      static <V> Result<V,​java.lang.String> err​(java.lang.String format, java.lang.Object... args)  
      java.util.Optional<E> error()
      Returns the error of this instance as an Optional.
      <U> Result<U,​E> flatMap​(FunctionWithException<? super V,​? extends Result<? extends U,​? extends E>> mapper)
      FlatMap the contained value if this is an Ok value.
      boolean isErr()
      Returns true if this instance represents an Err value, false otherwise.
      boolean isOk()
      Returns true if this instance represents an Ok value, false otherwise.
      <U> Result<U,​E> map​(FunctionWithException<? super V,​? extends U> mapper)
      Map the contained value if this is an Ok value.
      <F> Result<V,​F> mapErr​(FunctionWithException<? super E,​? extends F> mapper)
      Map the contained error if this is an Err value.
      static <V,​E>
      Result<V,​E>
      of​(V value, E error)
      Returns an Ok if the value parameter is non-null or an Err otherwise.
      static <V,​E>
      Result<V,​E>
      ok​(V value)
      Returns an Ok containing the specified value.
      V orElse​(V orElse)
      Returns the contained value if this is an Ok value.
      V orElseGet​(java.util.function.Supplier<? extends V> orElseSupplier)
      Returns the contained value if this is an Ok value.
      <R extends java.lang.Throwable>
      V
      orElseThrow​(FunctionWithException<? super E,​? extends R> throwableSupplier)
      Returns the contained value if this is an Ok value.
      Result<V,​E> recover​(FunctionWithException<? super E,​? extends V> recover)
      Recover the contained error if this is an Err value.
      V unwrap()
      Returns the contained value if this is an Ok value.
      V unwrap​(java.lang.String message)
      Express the expectation that this object is an Ok value.
      <X extends java.lang.Throwable>
      V
      unwrap​(java.util.function.Function<E,​X> constructor)  
      java.util.Optional<V> value()
      Returns the value of this instance as an Optional.
    • Method Detail

      • of

        static <V,​E> Result<V,​E> of​(V value,
                                                E error)
        Returns an Ok if the value parameter is non-null or an Err otherwise. Either one of value or error must not be null.
        Type Parameters:
        V - The value type of the Result.
        E - The error type of the Result.
        Parameters:
        value - If non-null, an Ok result is returned with the specified value.
        error - If value is null, an Err result is returned with the specified error.
        Returns:
        An Ok if the value parameter is non-null or an Err otherwise.
      • ok

        static <V,​E> Result<V,​E> ok​(V value)
        Returns an Ok containing the specified value.
        Type Parameters:
        V - The value type of the Result.
        E - The error type of the Result.
        Parameters:
        value - The value to contain in the Ok result. Must not be null.
        Returns:
        An Ok result.
      • err

        static <V,​E> Result<V,​E> err​(E error)
        Returns an Err containing the specified error.
        Type Parameters:
        V - The value type of the Result.
        E - The error type of the Result.
        Parameters:
        error - The error to contain in the Err result. Must not be null.
        Returns:
        An Err result.
      • err

        static <V> Result<V,​java.lang.String> err​(java.lang.String format,
                                                        java.lang.Object... args)
      • isOk

        boolean isOk()
        Returns true if this instance represents an Ok value, false otherwise.
        Returns:
        true if this instance represents an Ok value, false otherwise.
      • isErr

        boolean isErr()
        Returns true if this instance represents an Err value, false otherwise.
        Returns:
        true if this instance represents an Err value, false otherwise.
      • value

        java.util.Optional<V> value()
        Returns the value of this instance as an Optional. Returns Optional.empty() if this is an Err instance.
        Returns:
        The value of this instance as an Optional. Returns Optional.empty() if this is an Err instance.
      • error

        java.util.Optional<E> error()
        Returns the error of this instance as an Optional. Returns Optional.empty() if this is an Ok instance.
        Returns:
        The error of this instance as an Optional. Returns Optional.empty() if this is an Ok instance.
      • unwrap

        V unwrap()
        Returns the contained value if this is an Ok value. Otherwise throws a ResultException.
        Returns:
        The contained value
        Throws:
        ResultException - If this is an Err instance.
      • unwrap

        V unwrap​(java.lang.String message)
        Express the expectation that this object is an Ok value. Otherwise throws a ResultException with the specified message.
        Parameters:
        message - The message to pass to a potential ResultException.
        Throws:
        ResultException - If this is an Err instance.
      • orElse

        V orElse​(V orElse)
        Returns the contained value if this is an Ok value. Otherwise returns the specified alternate value.
        Parameters:
        orElse - The value to return if this is an Err instance.
        Returns:
        The contained value or the alternate value
      • orElseGet

        V orElseGet​(java.util.function.Supplier<? extends V> orElseSupplier)
        Returns the contained value if this is an Ok value. Otherwise returns the alternate value supplied by the specified supplier.
        Parameters:
        orElseSupplier - The supplier to supply an alternate value if this is an Err instance. Must not be null.
        Returns:
        The contained value or the alternate value
      • orElseThrow

        <R extends java.lang.Throwable> V orElseThrow​(FunctionWithException<? super E,​? extends R> throwableSupplier)
                                               throws R extends java.lang.Throwable
        Returns the contained value if this is an Ok value. Otherwise throws the exception supplied by the specified function.
        Type Parameters:
        R - The exception type.
        Parameters:
        throwableSupplier - The supplier to supply an exception if this is an Err instance. Must not be null. The supplier must return a non-null result.
        Returns:
        The contained value.
        Throws:
        R - If this is an Err instance.
        R extends java.lang.Throwable
      • map

        <U> Result<U,​E> map​(FunctionWithException<? super V,​? extends U> mapper)
        Map the contained value if this is an Ok value. Otherwise return this.
        Type Parameters:
        U - The new value type.
        Parameters:
        mapper - The function to map the contained value into a new value. Must not be null. The function must return a non-null value.
        Returns:
        A result containing the mapped value if this is an Ok value. Otherwise this.
      • mapErr

        <F> Result<V,​F> mapErr​(FunctionWithException<? super E,​? extends F> mapper)
        Map the contained error if this is an Err value. Otherwise return this.
        Type Parameters:
        F - The new error type.
        Parameters:
        mapper - The function to map the contained error into a new error. Must not be null. The function must return a non-null error.
        Returns:
        A result containing the mapped error if this is an Err value. Otherwise this.
      • flatMap

        <U> Result<U,​E> flatMap​(FunctionWithException<? super V,​? extends Result<? extends U,​? extends E>> mapper)
        FlatMap the contained value if this is an Ok value. Otherwise return this.
        Type Parameters:
        U - The new value type.
        Parameters:
        mapper - The function to flatmap the contained value into a new result. Must not be null. The function must return a non-null result.
        Returns:
        The flatmapped result if this is an Ok value. Otherwise this.
      • recover

        Result<V,​E> recover​(FunctionWithException<? super E,​? extends V> recover)
        Recover the contained error if this is an Err value. Otherwise return this.
        Parameters:
        recover - The function to recover the contained error into a new value. Must not be null. The function must return a non-null value.
        Returns:
        A result containing the new value if this is an Err value. Otherwise this.
      • accept

        void accept​(ConsumerWithException<? super V> ok,
                    ConsumerWithException<? super E> err)
        Terminal function that processes the result or the error
        Parameters:
        ok - the consumer called when ok
        err - the consumer called when not ok
      • asError

        <X> Result<X,​E> asError()
      • unwrap

        <X extends java.lang.Throwable> V unwrap​(java.util.function.Function<E,​X> constructor)
                                          throws X extends java.lang.Throwable
        Throws:
        X extends java.lang.Throwable