Package pro.horde.os.cutils.value

Class Try<T>

  • Type Parameters:
    T - type
    All Implemented Interfaces:
    Serializable
    public abstract class Try<T>
extends Object
implements Serializable
    The Try class offers the ability write safe code without focusing on try-catch blocks in the presence of exceptions.

    There are 3 states that determines the functionality of Try from the try operation performed.

    • Successful Operation with result.
    • Successful Operation without result.
    • Failed Operation.

    Requesting for a result on a successful operation which returns no result or failed operation which has not result will throw an IllegalStateException, using the map(Function) will vary depending on the state of the operation ... and so on. Review the methods description for more information.

    Furthermore, fatal exceptions aren't handle by Try:

    Since:
    v5
    Author:
    Bobai Kato
    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract T get()
      Use this method to retrieve the try operation result.
      abstract Throwable getCause()
      Retrieve the Cause of try operation failure.
      abstract boolean isFailure()
      Use to check the state of the try operation.
      abstract boolean isResult()
      Use to check the state of a successful try operation if or not it has a result.
      abstract boolean isSuccess()
      Use to check the stage of the try operation.
      abstract <M> Try<M> map​(Function<? super T,​? extends M> mapper)
      If a try operation return a result, apply the provided mapping function to it, and return and instance of Try with the applied result.
      static <T> Try<T> of​(Dealer<? extends T> operation)
      Accepts a Dealer type function which is expected to return a result if operation was successful.
      static <T> Try<T> of​(Executable operation)
      Accepts a Executable type function with no result expected if operation is successful.
      void onFailure​(Consumer<? super Throwable> exceptionConsumer)
      If try operations fails, invoke the specified consumer with the exception thrown during the execution, otherwise do nothing.
      void onFailureOrElse​(Consumer<? super Throwable> exceptionConsumer, Runnable action)
      Perform further operation on a failed try Exception, if the try succeeds, the second argument block is executed.
      void onFailureOrElse​(Consumer<? super Throwable> exceptionConsumer, Consumer<? super T> resultConsumer)
      Perform further operation on a failed try Exception, if the try succeeds, the second argument block is executed.
      void onSuccess​(Consumer<? super T> resultConsumer)
      If try is successful, invoke the specified consumer with the operation result, otherwise do nothing.
      void onSuccessOrElse​(Consumer<? super T> resultConsumer, Runnable action)
      Perform further operation on successful try result, if the try fails the second argument block is executed.
      void onSuccessOrElse​(Consumer<? super T> resultConsumer, Consumer<? super Throwable> exceptionConsumer)
      Perform further operation on successful try result, if the try fails the second argument block is executed.
      abstract T orElse​(T other)
      Return the result if try operation is successful and has a result, otherwise return other if try operation fails.
      abstract T orElseGet​(Supplier<? extends T> other)
      Return the result if available after the try operation, otherwise invoke other and return the result of that invocation.
      abstract <X extends Throwable>
      T      		 orElseThrow​(Supplier<? extends X> exceptionSupplier)
      Return try result if operation was successful, otherwise throw the exception supplied.

    • Method Detail

      • of

        public static <T> Try<T> of​(Dealer<? extends T> operation)
        Accepts a Dealer type function which is expected to return a result if operation was successful.
        Type Parameters:
        T - variable type
        Parameters:
        operation - the operation that will be tried, a variable of Dealer type.
        Returns:
        instance of Try either with a Try.Success or Try.Failure state.
        Since:
        v5

      • of

        public static <T> Try<T> of​(Executable operation)
        Accepts a Executable type function with no result expected if operation is successful.
        Type Parameters:
        T - variable type
        Parameters:
        operation - the operation that will be tried, a variable of Executable type.
        Returns:
        instance of Try either with a Try.Success or Try.Failure state.
        Since:
        v5

      • onSuccess

        public void onSuccess​(Consumer<? super T> resultConsumer)
        If try is successful, invoke the specified consumer with the operation result, otherwise do nothing.
        Parameters:
        resultConsumer - block of operation to be executed with try result
        Since:
        v5
        See Also:
        Try.Success.get()

      • onFailure

        public void onFailure​(Consumer<? super Throwable> exceptionConsumer)
        If try operations fails, invoke the specified consumer with the exception thrown during the execution, otherwise do nothing.
        Parameters:
        exceptionConsumer - operation to be executed if a an exception was thrown
        Since:
        v5
        See Also:
        Try.Failure.getCause()

      • onSuccessOrElse

        public void onSuccessOrElse​(Consumer<? super T> resultConsumer,
                            Runnable action)
        Perform further operation on successful try result, if the try fails the second argument block is executed.

        NOTE: This method will throw an IllegalStateException if the try operation executed doesn't return a result. Use Try.Success.isSuccess() instead to check the state of the try operation.

        Parameters:
        resultConsumer - block of operation of Consumer type to be executed with try result.
        action - block to be executed if try operation fails.
        Since:
        v5

      • onSuccessOrElse

        public void onSuccessOrElse​(Consumer<? super T> resultConsumer,
                            Consumer<? super Throwable> exceptionConsumer)
        Perform further operation on successful try result, if the try fails the second argument block is executed.

        NOTE: This method will throw an IllegalStateException if the try operation executed doesn't return a result. Use Try.Success.isSuccess() instead to check the state of the try operation.

        Parameters:
        resultConsumer - block of operation of Consumer type to be executed with try result.
        exceptionConsumer - block of operation of Consumer type to be executed when the try operation succeeds.
        Since:
        v5

      • onFailureOrElse

        public void onFailureOrElse​(Consumer<? super Throwable> exceptionConsumer,
                            Runnable action)
        Perform further operation on a failed try Exception, if the try succeeds, the second argument block is executed.
        Parameters:
        exceptionConsumer - block of operation of Consumer type to be executed when the try operation succeeds.
        action - block to be executed if try operation fails.
        Since:
        v5

      • onFailureOrElse

        public void onFailureOrElse​(Consumer<? super Throwable> exceptionConsumer,
                            Consumer<? super T> resultConsumer)
        Perform further operation on a failed try Exception, if the try succeeds, the second argument block is executed.
        Parameters:
        exceptionConsumer - block of operation of Consumer type to be executed when the try operation succeeds.
        resultConsumer - block of operation of Consumer type to be executed with try result.
        Since:
        v5

      • get

        public abstract T get()
        Use this method to retrieve the try operation result.
        Returns:
        try operation result
        Throws:
        IllegalStateException - Try state is Try.Success without an available result.
        UnsupportedOperationException - Try state is Try.Failure when a try operation fails
        Since:
        v5

      • getCause

        public abstract Throwable getCause()
        Retrieve the Cause of try operation failure.
        Returns:
        exception thrown during try operation.
        Throws:
        UnsupportedOperationException - if try operation is successful
        Since:
        v5

      • map

        public abstract <M> Try<M> map​(Function<? super T,​? extends M> mapper)
        If a try operation return a result, apply the provided mapping function to it, and return and instance of Try with the applied result.
        Type Parameters:
        M - The type of the result of the mapping function
        Parameters:
        mapper - a mapping function to apply to the result is available.
        Returns:
        an instance of Try describing the result of applying a mapping function to the result.
        Throws:
        NullPointerException - if the mapping function is null
        IllegalStateException - if a try operation state is Try.Success but without a result.
        UnsupportedOperationException - if a try operation state is Try.Failure.

      • orElse

        public abstract T orElse​(T other)
        Return the result if try operation is successful and has a result, otherwise return other if try operation fails.
        Parameters:
        other - the value to be returned if there is no result available, it could also be a null.
        Returns:
        the result, if present, otherwise other
        Throws:
        IllegalStateException - if a try was successful but returns no result.

      • orElseGet

        public abstract T orElseGet​(Supplier<? extends T> other)
        Return the result if available after the try operation, otherwise invoke other and return the result of that invocation.
        Parameters:
        other - a Supplier block whose result is returned if try fails
        Returns:
        the try result if available otherwise the result of other.get()
        Throws:
        NullPointerException - if value is not present and other is null
        IllegalStateException - if a try was successful but returns no result.

      • orElseThrow

        public abstract <X extends Throwable> T orElseThrow​(Supplier<? extends X> exceptionSupplier)
                                             throws X extends Throwable
        Return try result if operation was successful, otherwise throw the exception supplied.
        Type Parameters:
        X - Type of the exception to be thrown
        Parameters:
        exceptionSupplier - The supplier which will return the exception to be thrown
        Returns:
        the present value
        Throws:
        X - if there is no value present
        IllegalStateException - if a try was successful but returns no result.
        X extends Throwable

      • isSuccess

        public abstract boolean isSuccess()
        Use to check the stage of the try operation.
        Returns:
        a Boolean depending on the state: true if try was successful else false if operation fails.

      • isResult

        public abstract boolean isResult()
        Use to check the state of a successful try operation if or not it has a result.
        Returns:
        a Boolean depending on the state: true if try operation was successful and has a result or false if operation fails or successful but without a result.

      • isFailure

        public abstract boolean isFailure()
        Use to check the state of the try operation.
        Returns:
        a Boolean depending on the state: true if try operation fails else false if operation was successful..