Interface Result<V>

  • Type Parameters:
    V - The value type of the Result.

    public interface Result<V>
    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 String is the error type.

    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​(aQute.bnd.exceptions.ConsumerWithException<? super V> ok, aQute.bnd.exceptions.ConsumerWithException<? super java.lang.String> err)
      Processes the result.
      <U> Result<U> asError()
      If an Err, return this coerced to the desired generic type.
      static <V> Result<V> err​(java.lang.CharSequence error)
      Returns an Err containing the specified error.
      static <V> Result<V> err​(java.lang.String format, java.lang.Object... args)  
      java.util.Optional<java.lang.String> error()
      Returns the error of this instance as an Optional.
      <U> Result<U> flatMap​(aQute.bnd.exceptions.FunctionWithException<? super V,​? extends Result<? extends U>> 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> map​(aQute.bnd.exceptions.FunctionWithException<? super V,​? extends U> mapper)
      Map the contained value if this is an Ok value.
      Result<V> mapErr​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends java.lang.CharSequence> mapper)
      Map the contained error if this is an Err value.
      static <V> Result<V> of​(V value, java.lang.CharSequence error)
      Returns an Ok if the value parameter is non-null or an Err otherwise.
      static <V> Result<V> 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​(aQute.bnd.exceptions.SupplierWithException<? extends V> orElseSupplier)
      Returns the contained value if this is an Ok value.
      <R extends java.lang.Throwable>
      V
      orElseThrow​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends R> throwableSupplier)
      Returns the contained value if this is an Ok value.
      Result<V> recover​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends V> recover)
      Recover the contained error if this is an Err value.
      Result<V> recoverWith​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends Result<? 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.CharSequence message)
      Express the expectation that this object is an Ok value.
      java.util.Optional<V> value()
      Returns the value of this instance as an Optional.
    • Method Detail

      • of

        static <V> Result<V> of​(V value,
                                java.lang.CharSequence error)
        Returns an Ok if the value parameter is non-null or an Err otherwise. At least one of value or error must be non-null.
        Type Parameters:
        V - The value type of the Result.
        Parameters:
        value - If value is 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> Result<V> ok​(V value)
        Returns an Ok containing the specified value.
        Type Parameters:
        V - The value type of the Result.
        Parameters:
        value - The value to contain in the Ok result. May be null.
        Returns:
        An Ok result.
      • err

        static <V> Result<V> err​(java.lang.CharSequence error)
        Returns an Err containing the specified error.
        Type Parameters:
        V - The value 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> 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<java.lang.String> 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.CharSequence 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. Must not be null.
        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​(aQute.bnd.exceptions.SupplierWithException<? 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​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? 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 - The exception returned by the throwableSupplier if this is an Err instance.
        R extends java.lang.Throwable
      • map

        <U> Result<U> map​(aQute.bnd.exceptions.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.
        Returns:
        A result containing the mapped value if this is an Ok value. Otherwise this.
      • mapErr

        Result<V> mapErr​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends java.lang.CharSequence> mapper)
        Map the contained error if this is an Err value. Otherwise return this.
        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> flatMap​(aQute.bnd.exceptions.FunctionWithException<? super V,​? extends Result<? extends U>> 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> recover​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends V> recover)
        Recover the contained error if this is an Err value. Otherwise return this.

        To recover with a recovery value of null, the recoverWith(FunctionWithException) method must be used. The specified function for recoverWith(FunctionWithException) can return Result.ok(null) to supply the desired null value.

        Parameters:
        recover - The function to recover the contained error into a new value. Must not be null.
        Returns:
        A result containing the new non-null value if this is an Err value. Otherwise this if this is an Ok value or the recover function returned null.
      • recoverWith

        Result<V> recoverWith​(aQute.bnd.exceptions.FunctionWithException<? super java.lang.String,​? extends Result<? 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 result. Must not be null. The function must return a non-null value.
        Returns:
        A result if this is an Err value. Otherwise this.
      • accept

        void accept​(aQute.bnd.exceptions.ConsumerWithException<? super V> ok,
                    aQute.bnd.exceptions.ConsumerWithException<? super java.lang.String> err)
        Processes the result.
        Parameters:
        ok - The consumer called this result is an Ok value. Must not be null.
        err - The consumer called when this result is an Err value. Must not be null.
      • asError

        <U> Result<U> asError()
        If an Err, return this coerced to the desired generic type.
        Type Parameters:
        U - The desired generic type of the Err.
        Returns:
        this
        Throws:
        ResultException - If this is an Ok instance.