Package io.microsphere.lang.function

Interface ThrowableFunction<T,​R>

  • Type Parameters:
    T - the type of the input to the function
    R - the type of the result of the function
    Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
    @FunctionalInterface
public interface ThrowableFunction<T,​R>
    Represents a function that accepts one argument and produces a result, which may throw a checked exception.

    This interface is similar to Function, but allows the functional method to throw any Throwable. It also provides default methods for composing functions and handling exceptions gracefully.

    Example Usage

    
 // <h3>Example Usage</h3>
 ThrowableFunction<String, Integer> parser = Integer::valueOf;

 // Using execute() with default exception handling (throws RuntimeException)
 Integer result1 = parser.execute("123"); // returns 123

 // Using execute() with custom exception handling
 Integer result2 = parser.execute("invalid", (input, ex) -> {
     System.out.println("Parsing failed for: " + input);
     return -1; // fallback value
 });
    Since:
    1.0.0
    Author:
    Mercy
    See Also:
    Function, Throwable

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default <V> ThrowableFunction<T,​V> andThen​(ThrowableFunction<? super R,​? extends V> after)
      Returns a composed throwable-function that first applies this throwable-function to its input, and then applies the after throwable-function to the result.
      R apply​(T t)
      Applies this function to the given argument.
      default <V> ThrowableFunction<V,​R> compose​(ThrowableFunction<? super V,​? extends T> before)
      Returns a composed throwable-function that first applies the before throwable-function to its input, and then applies this throwable-function to the result.
      default R execute​(T t)
      Executes #apply(T) with the default exception handling
      static <T,​R>
      R      		 execute​(T t, ThrowableFunction<T,​R> function)
      Executes the given ThrowableFunction with the provided argument using the function's default exception handling.
      static <T,​R>
      R      		 execute​(T t, ThrowableFunction<T,​R> function, java.util.function.BiFunction<T,​java.lang.Throwable,​R> exceptionHandler)
      Executes the given ThrowableFunction with the provided argument using a custom exception handler.
      default R execute​(T t, java.util.function.BiFunction<T,​java.lang.Throwable,​R> exceptionHandler)
      Executes #apply(T) with the customized exception handling
      default R handleException​(T t, java.lang.Throwable failure)
      Handle any exception that the #apply(T) method throws

    • Method Detail

      • apply

        R apply​(T t)
 throws java.lang.Throwable
        Applies this function to the given argument.
        Parameters:
        t - the function argument
        Returns:
        the function result
        Throws:
        java.lang.Throwable - if met with any error

      • execute

        default R execute​(T t)
           throws java.lang.RuntimeException
        Executes #apply(T) with the default exception handling
        Parameters:
        t - the function argument
        Returns:
        the function result
        Throws:
        java.lang.RuntimeException

      • execute

        default R execute​(T t,
                  java.util.function.BiFunction<T,​java.lang.Throwable,​R> exceptionHandler)
           throws java.lang.RuntimeException
        Executes #apply(T) with the customized exception handling
        Parameters:
        t - the function argument
        exceptionHandler - the handler to handle the function argument and the exception that the #apply(T) method throws
        Returns:
        the function result
        Throws:
        java.lang.RuntimeException

      • handleException

        default R handleException​(T t,
                          java.lang.Throwable failure)
        Handle any exception that the #apply(T) method throws
        Parameters:
        t - the value to be consumed
        failure - the instance of Throwable

      • compose

        default <V> ThrowableFunction<V,​R> compose​(ThrowableFunction<? super V,​? extends T> before)
        Returns a composed throwable-function that first applies the before throwable-function to its input, and then applies this throwable-function to the result. If evaluation of either throwable-function throws an exception, it is relayed to the caller of the composed throwable-function.
        Type Parameters:
        V - the type of input to the before throwable-function, and to the composed throwable-function
        Parameters:
        before - the throwable-function to apply before this throwable-function is applied
        Returns:
        a composed throwable-function that first applies the before throwable-function and then applies this throwable-function
        Throws:
        java.lang.NullPointerException - if before is null
        See Also:
        andThen(ThrowableFunction)

      • andThen

        default <V> ThrowableFunction<T,​V> andThen​(ThrowableFunction<? super R,​? extends V> after)
        Returns a composed throwable-function that first applies this throwable-function to its input, and then applies the after throwable-function to the result. If evaluation of either throwable-function throws an exception, it is relayed to the caller of the composed throwable-function.
        Type Parameters:
        V - the type of output of the after throwable-function, and of the composed throwable-function
        Parameters:
        after - the throwable-function to apply after this throwable-function is applied
        Returns:
        a composed throwable-function that first applies this throwable-function and then applies the after throwable-function
        Throws:
        java.lang.NullPointerException - if after is null
        See Also:
        compose(ThrowableFunction)

      • execute

        static <T,​R> R execute​(T t,
                             ThrowableFunction<T,​R> function)
                      throws java.lang.IllegalArgumentException
        Executes the given ThrowableFunction with the provided argument using the function's default exception handling.

        If the execution of the function throws an exception, it will be handled by the function's own handleException(Object, Throwable) method.

        Example Usage

        
 ThrowableFunction<String, Integer> parser = Integer::valueOf;

 // Successful execution
 Integer result1 = execute("123", parser); // returns 123

 // Execution that fails and uses the default exception handler (throws RuntimeException)
 Integer result2 = execute("invalid", parser); // throws RuntimeException wrapping NumberFormatException
        Type Parameters:
        T - the type of the input to the function
        R - the type of the result of the function
        Parameters:
        t - the input argument to the function
        function - the ThrowableFunction to execute
        Returns:
        the result of the function execution
        Throws:
        java.lang.IllegalArgumentException - if the provided function is null

      • execute

        static <T,​R> R execute​(T t,
                             ThrowableFunction<T,​R> function,
                             java.util.function.BiFunction<T,​java.lang.Throwable,​R> exceptionHandler)
                      throws java.lang.IllegalArgumentException
        Executes the given ThrowableFunction with the provided argument using a custom exception handler.

        This method applies the provided function to the input argument. If the function throws an exception, it is passed to the provided exceptionHandler for handling, allowing custom fallback behavior.

        Example Usage

        
 ThrowableFunction<String, Integer> parser = Integer::valueOf;

 // Successful execution
 Integer result1 = execute("123", parser, (input, ex) -> -1); // returns 123

 // Execution that fails, using the custom exception handler
 Integer result2 = execute("invalid", parser, (input, ex) -> -1); // returns -1
        Type Parameters:
        T - the type of the input to the function
        R - the type of the result of the function
        Parameters:
        t - the input argument to the function
        function - the ThrowableFunction to execute
        exceptionHandler - the handler to use if the function throws an exception; takes the input and the exception, and returns a fallback value
        Returns:
        the result of the function execution
        Throws:
        java.lang.IllegalArgumentException - if the provided function or exception handler is null