Class Result<S>

java.lang.Object
dev.derklaro.reflexion.Result<S>
Type Parameters:
S - the successful result type of the execution.
All Implemented Interfaces:
Supplier<S>
public final class Result<S> extends Object implements Supplier<S>
A rust inspired result class which either holds the result of an executable or the exception thrown by it. That makes it very easy to write clean code and give exceptions back to the actual producer of them rather than requiring a wrapped rethrow of it.
Since:
1.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Result.ExceptionalSupplier<T>
    Represents a supplier which can throw any exception when executing.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final Throwable
    exception
     
    private final S
    result
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Result(S result, Throwable exception)
    Constructs a new result type.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull Optional<S>
    asOptional()
    Wraps the successful value of this result in an optional.
    @NotNull Result<S>
    consume(@NotNull BiConsumer<S, Throwable> consumer)
    Consumes both, the successful and exceptional result value wrapped in this result and passes them to the given consumer.
    static <T> @NotNull Result<T>
    exceptional(@NotNull Throwable exception)
    Constructs a new result instance which failed and holds the given exception as the reason of the failure.
    <M> @NotNull Result<M>
    flatMap(@NotNull Function<S, Result<M>> function)
    Maps the successful result of this result into a new one or returns the same instance as before when this result already contained an exception.
    <M> @NotNull Result<M>
    flatMapExceptional(@NotNull Function<Throwable, Result<M>> function)
    Maps the wrapped exceptional result of this result into a new one or returns the same instance as before when this result was executed successfully.
    S
    get()
    Get the successful result wrapped in this result.
    @NotNull Throwable
    getException()
    Get the exception which was thrown during the execution.
    @UnknownNullability S
    getOrElse(S or)
    Get the successful result wrapped in this result or the given value if this result was executed exceptionally.
    @UnknownNullability S
    getOrEval(@NotNull Supplier<S> supplier)
    Get the successful result wrapped in this result or evaluates the given supplier value and returns that.
    @UnknownNullability S
    getOrMap(@NotNull Function<Throwable, S> function)
    Get the successful result wrapped in this result or maps the wrapped exception using the supplied function.
    @UnknownNullability S
    getOrThrow()
    Get the wrapped success value of this result or rethrows the wrapped exception unchecked.
    @NotNull Result<S>
    ifExceptional(@NotNull Consumer<Throwable> consumer)
    Executes the given consumer using the wrapped exceptional result value if present.
    @NotNull Result<S>
    ifSuccess(@NotNull Consumer<S> consumer)
    Executes the given consumer using the wrapped successful result value if present.
    <M> @NotNull Result<M>
    map(@NotNull Function<S,M> function)
    Maps the successful result of this result into a new one or returns the same instance as before when this result already contained an exception.
    @NotNull Result<S>
    mapExceptional(@NotNull Function<Throwable, Throwable> function)
    Maps the wrapped exceptional result of this result into a new one or returns the same instance as before when this result was executed successfully.
    static <T> @NotNull Result<T>
    success(T result)
    Constructs a new result instance holding the given object as its successful result.
    static <T> Result<T>
    tryExecute(@NotNull Result.ExceptionalSupplier<T> supplier)
    Tries to execute the supplier and use the result of it as the value of this result.
    boolean
    wasExceptional()
    Get if this result execution failed for some reason.
    boolean
    wasSuccessful()
    Get if this result was executed successfully or if it failed for some reason.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • result

      private final S result

    • exception

      private final Throwable exception

  • Constructor Details

    • Result

      private Result(S result, Throwable exception)
      Constructs a new result type. Either the result or the exception must be present. The state of the result is determined by whether the given exception is present or absent.
      Parameters:
      result - the result of the execution, can be null.
      exception - the exceptional result the execution, only present when the result failed.

  • Method Details

    • tryExecute

      public static <T> Result<T> tryExecute(@NotNull @NotNull Result.ExceptionalSupplier<T> supplier)
      Tries to execute the supplier and use the result of it as the value of this result. If the execution of the supplier fails a result holding the thrown exception is returned instead.

      This method instantly rethrows unrecoverable errors which prevent the current thread from resuming.

      Type Parameters:
      T - the type of the action result.
      Parameters:
      supplier - the which should get executed.
      Returns:
      the result of the action execution, either holding the result value or the thrown exception.
      Throws:
      NullPointerException - if the given supplier is null.

    • success

      @NotNull public static <T> @NotNull Result<T> success(@Nullable T result)
      Constructs a new result instance holding the given object as its successful result.
      Type Parameters:
      T - the type of the result.
      Parameters:
      result - the successful result of the action.
      Returns:
      a new result instance which succeeded and holds the given object as it's result value.

    • exceptional

      @NotNull public static <T> @NotNull Result<T> exceptional(@NotNull @NotNull Throwable exception)
      Constructs a new result instance which failed and holds the given exception as the reason of the failure.
      Type Parameters:
      T - the expected successful return type, even tho the result is never successful.
      Parameters:
      exception - the reason of the failure.
      Returns:
      a new result instance holding the given exception as the failure reason.
      Throws:
      NullPointerException - if the given exception is null.

    • wasSuccessful

      public boolean wasSuccessful()
      Get if this result was executed successfully or if it failed for some reason.
      Returns:
      true if this result was executed successfully, false otherwise.

    • wasExceptional

      public boolean wasExceptional()
      Get if this result execution failed for some reason.
      Returns:
      true if the result holds an exception, false otherwise.

    • getException

      @NotNull public @NotNull Throwable getException()
      Get the exception which was thrown during the execution.
      Returns:
      the thrown exception.
      Throws:
      NoSuchElementException - if this result was executed successfully.

    • get

      public S get()
      Get the successful result wrapped in this result.
      Specified by:
      get in interface Supplier<S>
      Returns:
      the successful result.
      Throws:
      NoSuchElementException - if the result was executed exceptionally.

    • getOrElse

      public @UnknownNullability S getOrElse(@Nullable S or)
      Get the successful result wrapped in this result or the given value if this result was executed exceptionally.
      Parameters:
      or - the value to get if the result was executed exceptionally.
      Returns:
      the wrapped successful return value or the given value.

    • getOrEval

      public @UnknownNullability S getOrEval(@NotNull @NotNull Supplier<S> supplier)
      Get the successful result wrapped in this result or evaluates the given supplier value and returns that.
      Parameters:
      supplier - the supplier to evaluate if this result was executed exceptionally.
      Returns:
      the wrapped success return value or the evaluated value from the given supplier.
      Throws:
      NullPointerException - if the given supplier is null.

    • getOrMap

      public @UnknownNullability S getOrMap(@NotNull @NotNull Function<Throwable, S> function)
      Get the successful result wrapped in this result or maps the wrapped exception using the supplied function.
      Parameters:
      function - the function to call with the exception thrown by the execution.
      Returns:
      the wrapped success return value or the evaluated value from the given function.
      Throws:
      NullPointerException - if the given function is null.

    • getOrThrow

      public @UnknownNullability S getOrThrow()
      Get the wrapped success value of this result or rethrows the wrapped exception unchecked.
      Returns:
      the successful return value of the result.

    • map

      @NotNull public <M> @NotNull Result<M> map(@NotNull @NotNull Function<S,M> function)
      Maps the successful result of this result into a new one or returns the same instance as before when this result already contained an exception. This method will return an exceptional result if the mapping function throws an exception.
      Type Parameters:
      M - the new result type mapped from the given function.
      Parameters:
      function - the mapping function to map the success value of this result.
      Returns:
      a new result based on the mapping function if this result was executed successfully.
      Throws:
      NullPointerException - if the given function is null.

    • flatMap

      @NotNull public <M> @NotNull Result<M> flatMap(@NotNull @NotNull Function<S, Result<M>> function)
      Maps the successful result of this result into a new one or returns the same instance as before when this result already contained an exception. This method will not catch any exceptions thrown by the mapping function.
      Type Parameters:
      M - the new result type mapped from the given function.
      Parameters:
      function - the mapping function to map the success value of this result.
      Returns:
      a new result based on the mapping function if this result was executed successfully.
      Throws:
      NullPointerException - if the given function is null.
      Since:
      1.5.0

    • mapExceptional

      @NotNull public @NotNull Result<S> mapExceptional(@NotNull @NotNull Function<Throwable, Throwable> function)
      Maps the wrapped exceptional result of this result into a new one or returns the same instance as before when this result was executed successfully. This method will always return an exceptional result. This method will not catch any exceptions thrown by the mapping function.
      Parameters:
      function - the mapping function for the wrapped exception.
      Returns:
      a new result based on the mapping function if this result was executed exceptionally.
      Throws:
      NullPointerException - if the given mapping function is null.

    • flatMapExceptional

      @NotNull public <M> @NotNull Result<M> flatMapExceptional(@NotNull @NotNull Function<Throwable, Result<M>> function)
      Maps the wrapped exceptional result of this result into a new one or returns the same instance as before when this result was executed successfully. This method will not catch any exceptions thrown by the mapping function.
      Parameters:
      function - the mapping function for the wrapped exception.
      Returns:
      a new result based on the mapping function if this result was executed exceptionally.
      Throws:
      NullPointerException - if the given mapping function is null.
      Since:
      1.5.0

    • ifSuccess

      @NotNull public @NotNull Result<S> ifSuccess(@NotNull @NotNull Consumer<S> consumer)
      Executes the given consumer using the wrapped successful result value if present. This method does nothing if the result completed exceptionally.
      Parameters:
      consumer - the consumer to call with the wrapped successful value.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given consumer is null.

    • ifExceptional

      @NotNull public @NotNull Result<S> ifExceptional(@NotNull @NotNull Consumer<Throwable> consumer)
      Executes the given consumer using the wrapped exceptional result value if present. This method does nothing if the result completed successfully.
      Parameters:
      consumer - the consumer to call with the wrapped exceptional result.
      Returns:
      the same instance as used to call the method, for chaining.

    • consume

      @NotNull public @NotNull Result<S> consume(@NotNull @NotNull BiConsumer<S, Throwable> consumer)
      Consumes both, the successful and exceptional result value wrapped in this result and passes them to the given consumer. The given exception will be null if the result completed successfully.

      Note: the successful result type might be null even when the result completed successfully, indicating that the execution returned null.

      Parameters:
      consumer - the consumer to accept both, the successful and exceptional value wrapped in this result.
      Returns:
      the same instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given consumer is null.

    • asOptional

      @NotNull public @NotNull Optional<S> asOptional()
      Wraps the successful value of this result in an optional. Note: the optional value might be absent even when the result completed successfully, indicating that the execution returned null.
      Returns:
      an optional of the wrapped return value in this result.