Package org.djutils.exceptions

Class Try

  • public final class Try
extends Object
    The Try class has a number of static methods that make it easy to try-catch an exception for any Throwable class, including the standard Java exceptions and exceptions from libraries that are used in the project. Instead of: 
     FileInputStream fis;
 try
 {
     fis = new FileInputStream(fileString);
 }
 catch (FileNotFoundException exception)
 {
     throw new IllegalArgumentException("File " + fileString + " is not a valid file.", exception);
 }
 try
 {
     fis.close();
 }
 catch (IOException exception)
 {
     throw new RuntimeException("Could not close the file.", exception);
 }
    we can write: 
     FileInputStream fis = Try.assign(() -> new FileInputStream(fileString), IllegalArgumentException.class,
         "File %s is not a valid file.", fileString);
 Try.execute(() -> fis.close(), "Could not close the file.");
    The exception message can be formatted with additional arguments, such that the overhead of building the exception message only occurs if the exception condition is met. For each method there is a version without Throwable class, in which case a RuntimeException will be thrown.

    Try is not suitable for try-with-resource statements.

    Try also has a few methods to aid JUNIT tests: testFail(...) and testNotFail(...).

    Copyright (c) 2016-2023 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

    Author:
    Alexander Verbraeck, Peter Knoppers, Wouter Schakel

    • Method Detail

      • assign

        public static <V> V assign​(Try.Assignment<V> assignment,
                           String message)
                    throws RuntimeException
        Tries to return a value to assign. Will throw a RuntimeException if the try fails.
        Type Parameters:
        V - value type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; the message to use in the throwable
        Returns:
        V; value to assign
        Throws:
        RuntimeException - on failed Try

      • assign

        public static <V> V assign​(Try.Assignment<V> assignment,
                           String message,
                           Object arg)
                    throws RuntimeException
        Tries to return a value to assign. Will throw a RuntimeException if the try fails.
        Type Parameters:
        V - value type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; the message to use in the throwable, with formatting identifier
        arg - Object; value to use for the formatting identifier
        Returns:
        V; value to assign
        Throws:
        RuntimeException - on failed Try

      • assign

        public static <V> V assign​(Try.Assignment<V> assignment,
                           String message,
                           Object arg1,
                           Object arg2)
                    throws RuntimeException
        Tries to return a value to assign. Will throw a RuntimeException if the try fails.
        Type Parameters:
        V - value type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        RuntimeException - on failed Try

      • assign

        public static <V> V assign​(Try.Assignment<V> assignment,
                           String message,
                           Object arg1,
                           Object arg2,
                           Object arg3)
                    throws RuntimeException
        Tries to return a value to assign. Will throw a RuntimeException if the try fails.
        Type Parameters:
        V - value type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        RuntimeException - on failed Try

      • assign

        public static <V> V assign​(Try.Assignment<V> assignment,
                           String message,
                           Object arg1,
                           Object arg2,
                           Object arg3,
                           Object... args)
                    throws RuntimeException
        Tries to return a value to assign. Will throw a RuntimeException if the try fails.
        Type Parameters:
        V - value type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        args - Object...; potential 4th and further values to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        RuntimeException - on failed Try

      • assign

        public static <V,​T extends Throwable> V assign​(Try.Assignment<V> assignment,
                                                     Class<T> throwableClass,
                                                     String message)
                                              throws T extends Throwable
        Tries to return a value to assign. Will throw a specified Throwable if the try fails.
        Type Parameters:
        V - value type
        T - throwable type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable
        Returns:
        V; value to assign
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • assign

        public static <V,​T extends Throwable> V assign​(Try.Assignment<V> assignment,
                                                     Class<T> throwableClass,
                                                     String message,
                                                     Object arg)
                                              throws T extends Throwable
        Tries to return a value to assign. Will throw a specified Throwable if the try fails.
        Type Parameters:
        V - value type
        T - throwable type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifier
        arg - Object; value to use for the formatting identifier
        Returns:
        V; value to assign
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • assign

        public static <V,​T extends Throwable> V assign​(Try.Assignment<V> assignment,
                                                     Class<T> throwableClass,
                                                     String message,
                                                     Object arg1,
                                                     Object arg2)
                                              throws T extends Throwable
        Tries to return a value to assign. Will throw a specified Throwable if the try fails.
        Type Parameters:
        V - value type
        T - throwable type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • assign

        public static <V,​T extends Throwable> V assign​(Try.Assignment<V> assignment,
                                                     Class<T> throwableClass,
                                                     String message,
                                                     Object arg1,
                                                     Object arg2,
                                                     Object arg3)
                                              throws T extends Throwable
        Tries to return a value to assign. Will throw a specified Throwable if the try fails.
        Type Parameters:
        V - value type
        T - throwable type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • assign

        public static <V,​T extends Throwable> V assign​(Try.Assignment<V> assignment,
                                                     Class<T> throwableClass,
                                                     String message,
                                                     Object arg1,
                                                     Object arg2,
                                                     Object arg3,
                                                     Object... args)
                                              throws T extends Throwable
        Tries to return a value to assign. Will throw a specified Throwable if the try fails.
        Type Parameters:
        V - value type
        T - throwable type
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        args - Object...; potential 4th and further values to use for the formatting identifiers
        Returns:
        V; value to assign
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • execute

        public static void execute​(Try.Execution execution,
                           String message)
                    throws RuntimeException
        Tries to execute. Will throw a RuntimeException if the try fails.
        Parameters:
        execution - Execution; functional interface to execute
        message - String; the message to use in the throwable
        Throws:
        RuntimeException - on failed Try

      • execute

        public static void execute​(Try.Execution execution,
                           String message,
                           Object arg)
                    throws RuntimeException
        Tries to execute. Will throw a RuntimeException if the try fails.
        Parameters:
        execution - Execution; functional interface to execute
        message - String; the message to use in the throwable, with formatting identifier
        arg - Object; value to use for the formatting identifier
        Throws:
        RuntimeException - on failed Try

      • execute

        public static void execute​(Try.Execution execution,
                           String message,
                           Object arg1,
                           Object arg2)
                    throws RuntimeException
        Tries to execute. Will throw a RuntimeException if the try fails.
        Parameters:
        execution - Execution; functional interface to execute
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        Throws:
        RuntimeException - on failed Try

      • execute

        public static void execute​(Try.Execution execution,
                           String message,
                           Object arg1,
                           Object arg2,
                           Object arg3)
                    throws RuntimeException
        Tries to execute. Will throw a RuntimeException if the try fails.
        Parameters:
        execution - Execution; functional interface to execute
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        Throws:
        RuntimeException - on failed Try

      • execute

        public static void execute​(Try.Execution execution,
                           String message,
                           Object arg1,
                           Object arg2,
                           Object arg3,
                           Object... args)
                    throws RuntimeException
        Tries to execute. Will throw a RuntimeException if the try fails.
        Parameters:
        execution - Execution; functional interface to execute
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        args - Object...; potential 4th and further values to use for the formatting identifiers
        Throws:
        RuntimeException - on failed Try

      • execute

        public static <T extends Throwable> void execute​(Try.Execution execution,
                                                 Class<T> throwableClass,
                                                 String message)
                                          throws T extends Throwable
        Tries to execute. Will throw a specified Throwable if the try fails.
        Type Parameters:
        T - throwable type
        Parameters:
        execution - Execution; functional interface to execute
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • execute

        public static <T extends Throwable> void execute​(Try.Execution execution,
                                                 Class<T> throwableClass,
                                                 String message,
                                                 Object arg)
                                          throws T extends Throwable
        Tries to execute. Will throw a specified Throwable if the try fails.
        Type Parameters:
        T - throwable type
        Parameters:
        execution - Execution; functional interface to execute
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifier
        arg - Object; value to use for the formatting identifier
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • execute

        public static <T extends Throwable> void execute​(Try.Execution execution,
                                                 Class<T> throwableClass,
                                                 String message,
                                                 Object arg1,
                                                 Object arg2)
                                          throws T extends Throwable
        Tries to execute. Will throw a specified Throwable if the try fails.
        Type Parameters:
        T - throwable type
        Parameters:
        execution - Execution; functional interface to execute
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • execute

        public static <T extends Throwable> void execute​(Try.Execution execution,
                                                 Class<T> throwableClass,
                                                 String message,
                                                 Object arg1,
                                                 Object arg2,
                                                 Object arg3)
                                          throws T extends Throwable
        Tries to execute. Will throw a specified Throwable if the try fails.
        Type Parameters:
        T - throwable type
        Parameters:
        execution - Execution; functional interface to execute
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • execute

        public static <T extends Throwable> void execute​(Try.Execution execution,
                                                 Class<T> throwableClass,
                                                 String message,
                                                 Object arg1,
                                                 Object arg2,
                                                 Object arg3,
                                                 Object... args)
                                          throws T extends Throwable
        Tries to execute. Will throw a specified Throwable if the try fails.
        Type Parameters:
        T - throwable type
        Parameters:
        execution - Execution; functional interface to execute
        throwableClass - Class<T>; class of the throwable to throw
        message - String; the message to use in the throwable, with formatting identifiers
        arg1 - Object; 1st value to use for the formatting identifiers
        arg2 - Object; 2nd value to use for the formatting identifiers
        arg3 - Object; 3rd value to use for the formatting identifiers
        args - Object...; potential 4th and further values to use for the formatting identifiers
        Throws:
        T - throwable on failed Try
        T extends Throwable

      • testFail

        public static <V> V testFail​(Try.Assignment<V> assignment)
        Method for unit tests to test if an expected exception is thrown on an assignment. This method does not provide an explanation, and it is not checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the assignment does not throw any exception. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null));
        or 
        
   Try.testFail(new Try.Assignment<Double>()
   {
       @Override
       public Double assign() throws Throwable
       {
           return methodFailsOnNull(null);
       }
   });
        Type Parameters:
        V - value type, which is the return type of the assignment
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        Returns:
        V; assigned value
        Throws:
        AssertionError - when the assignment fails to throw an exception

      • testFail

        public static <V> V testFail​(Try.Assignment<V> assignment,
                             String message)
        Method for unit tests to test if an expected exception is thrown on an assignment. This method provides an explanation message, but it is not checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the assignment does not throw an exception. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), "call should have thrown an NPE");
        or 
        
   Try.testFail(new Try.Assignment<Double>()
   {
       @Override
       public Double assign() throws Throwable
       {
           return methodFailsOnNull(null);
       }
   }, "call should have thrown an NPE");
        Type Parameters:
        V - value type, which is the return type of the assignment
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; message to use in the AssertionError when the assignment succeeds
        Returns:
        V; assigned value
        Throws:
        AssertionError - when the assignment fails to throw an exception

      • testFail

        public static <V,​T extends Throwable> V testFail​(Try.Assignment<V> assignment,
                                                       Class<T> expectedThrowableClass)
        Method for unit tests to test if an expected exception is thrown on an assignment. This method does not provide an explanation, but it is checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the assignment does not throw an exception, or when it throws a different exception than expectedThrowableClass. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), NullPointerException.class);
        or 
        
   Try.testFail(new Try.Assignment<Double>()
   {
       @Override
       public Double assign() throws Throwable
       {
           return methodFailsOnNull(null);
       }
   }, NullPointerException.class);
        Type Parameters:
        V - value type, which is the return type of the assignment
        T - throwable type, which ensures that we provide a throwable class as the argument
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        expectedThrowableClass - Class<T>; the class of the exception we expect the assignment to throw
        Returns:
        V; assigned value
        Throws:
        AssertionError - when the assignment fails to throw an exception or the correct exception

      • testFail

        public static <V,​T extends Throwable> V testFail​(Try.Assignment<V> assignment,
                                                       String message,
                                                       Class<T> expectedThrowableClass)
        Method for unit tests to test if an expected exception is thrown on an assignment. This method provides an explanation message, and it is checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the assignment does not throw an exception, or when it throws a different exception than expectedThrowableClass. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), "call should have thrown an NPE", NullPointerException.class);
        or 
        
   Try.testFail(new Try.Assignment<Double>()
   {
       @Override
       public Double assign() throws Throwable
       {
           return methodFailsOnNull(null);
       }
   }, "call should have thrown an NPE", NullPointerException.class);
        Type Parameters:
        V - value type, which is the return type of the assignment
        T - throwable type, which ensures that we provide a throwable class as the argument
        Parameters:
        assignment - Assignment<V>; functional interface to assign value
        message - String; message to use in the AssertionError when the test fails
        expectedThrowableClass - Class<T>; the class of the exception we expect the assignment to throw
        Returns:
        V; assigned value

      • testFail

        public static void testFail​(Try.Execution execution)
        Method for unit tests to test if an expected exception is thrown on code execution. This method does not provide an explanation message, nor is it checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the execution does not throw an exception. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null));
        or 
        
   Try.testFail(new Try.Execution()
   {
       @Override
       public void execute() throws Throwable
       {
           methodFailsOnNull(null);
       }
   });
        Parameters:
        execution - Execution; functional interface to execute a method that does not need to return a value

      • testFail

        public static void testFail​(Try.Execution execution,
                            String message)
        Method for unit tests to test if an expected exception is thrown on code execution. This method provides an explanation message, but it is not checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the execution does not throw an exception, or when it throws a different exception than expectedThrowableClass. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), "call should have thrown an NPE");
        or 
        
   Try.testFail(new Try.Execution()
   {
       @Override
       public void execute() throws Throwable
       {
           methodFailsOnNull(null);
       }
   }, "call should have thrown an NPE");
        Parameters:
        execution - Execution; functional interface to execute a method that does not need to return a value
        message - String; message to use in the AssertionError when the test fails

      • testFail

        public static <T extends Throwable> void testFail​(Try.Execution execution,
                                                  Class<T> expectedThrowableClass)
        Method for unit tests to test if an expected exception is thrown on code execution. This method does not provide an explanation message, but it is checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the execution does not throw an exception, or when it throws a different exception than expectedThrowableClass. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), NullPointerException.class);
        or 
        
   Try.testFail(new Try.Execution()
   {
       @Override
       public void execute() throws Throwable
       {
           methodFailsOnNull(null);
       }
   }, NullPointerException.class);
        Type Parameters:
        T - throwable type, which ensures that we provide a throwable class as the argument
        Parameters:
        execution - Execution; functional interface to execute a method that does not need to return a value
        expectedThrowableClass - Class<T>; the class of the exception we expect the execution to throw

      • testFail

        public static <T extends Throwable> void testFail​(Try.Execution execution,
                                                  String message,
                                                  Class<T> expectedThrowableClass)
        Method for unit tests to test if an expected exception is thrown on code execution. This method provides an explanation message, and it is checking for a specific type of exception to be thrown. The testFail() method throws an AssertionError when the execution does not throw an exception, or when it throws a different exception than expectedThrowableClass. A way to use the method is, for instance: 
         
   Try.testFail(() -> methodFailsOnNull(null), "call should have thrown an NPE", NullPointerException.class);
        or 
        
   Try.testFail(new Try.Execution()
   {
       @Override
       public void execute() throws Throwable
       {
           methodFailsOnNull(null);
       }
   }, "call should have thrown an NPE", NullPointerException.class);
        Type Parameters:
        T - throwable type, which ensures that we provide a throwable class as the argument
        Parameters:
        execution - Execution; functional interface to execute a method that does not need to return a value
        message - String; message to use in the AssertionError when the test fails
        expectedThrowableClass - Class<T>; the class of the exception we expect the execution to throw