Class Try

java.lang.Object
org.djutils.exceptions.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-2020 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 Details

    • 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)
      Fails if the assignment succeeds.
      Type Parameters:
      V - value type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      Returns:
      V; value to assign
    • testFail

      public static <V> V testFail​(Try.Assignment<V> assignment, String message)
      Fails if the assignment succeeds.
      Type Parameters:
      V - value type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      message - String; fail message
      Returns:
      V; value to assign
    • testFail

      public static <V,​ T extends Throwable> V testFail​(Try.Assignment<V> assignment, Class<T> throwableClass)
      Fails if the assignment succeeds.
      Type Parameters:
      V - value type
      T - throwable type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      throwableClass - Class<T>; throwable class to catch
      Returns:
      V; value to assign
    • testFail

      public static <V,​ T extends Throwable> V testFail​(Try.Assignment<V> assignment, String message, Class<T> throwableClass)
      Fails if the assignment succeeds.
      Type Parameters:
      V - value type
      T - throwable type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      message - String; fail message
      throwableClass - Class<T>; throwable class to catch
      Returns:
      V; value to assign
    • testSucceed

      public static <V> V testSucceed​(Try.Assignment<V> assignment)
      Fails if the assignment does not succeed.
      Type Parameters:
      V - value type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      Returns:
      V; value to assign
    • testSucceed

      public static <V> V testSucceed​(Try.Assignment<V> assignment, String message)
      Fails if the assignment does not succeed.
      Type Parameters:
      V - value type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      message - String; fail message
      Returns:
      V; value to assign
    • testSucceed

      public static <V,​ T extends Throwable> V testSucceed​(Try.Assignment<V> assignment, Class<T> throwableClass)
      Fails if the assignment does not succeed.
      Type Parameters:
      V - value type
      T - throwable type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      throwableClass - Class<T>; throwable class to catch
      Returns:
      V; value to assign
    • testSucceed

      public static <V,​ T extends Throwable> V testSucceed​(Try.Assignment<V> assignment, String message, Class<T> throwableClass)
      Fails if the assignment does not succeed.
      Type Parameters:
      V - value type
      T - throwable type
      Parameters:
      assignment - Assignment<V>; functional interface to assign value
      message - String; fail message
      throwableClass - Class<T>; throwable class to catch
      Returns:
      V; value to assign
    • testFail

      public static void testFail​(Try.Execution execution)
      Fails if the execution succeeds.
      Parameters:
      execution - Execution; functional interface to execute
    • testFail

      public static void testFail​(Try.Execution execution, String message)
      Fails if the execution succeeds.
      Parameters:
      execution - Execution; functional interface to execute
      message - String; fail message
    • testFail

      public static <T extends Throwable> void testFail​(Try.Execution execution, Class<T> throwableClass)
      Fails if the execution succeeds.
      Type Parameters:
      T - throwable type
      Parameters:
      execution - Execution; functional interface to execute
      throwableClass - Class<T>; throwable class to catch
    • testFail

      public static <T extends Throwable> void testFail​(Try.Execution execution, String message, Class<T> throwableClass)
      Fails if the execution succeeds.
      Type Parameters:
      T - throwable type
      Parameters:
      execution - Execution; functional interface to execute
      message - String; fail message
      throwableClass - Class<T>; throwable class to catch
    • testSucceed

      public static void testSucceed​(Try.Execution execution)
      Fails if the execution does not succeed.
      Parameters:
      execution - Execution; functional interface to execute
    • testSucceed

      public static void testSucceed​(Try.Execution execution, String message)
      Fails if the execution does not succeed.
      Parameters:
      execution - Execution; functional interface to execute
      message - String; fail message
    • testSucceed

      public static <T extends Throwable> void testSucceed​(Try.Execution execution, Class<T> throwableClass)
      Fails if the execution does not succeed.
      Type Parameters:
      T - throwable type
      Parameters:
      execution - Execution; functional interface to execute
      throwableClass - Class<T>; throwable class to catch
    • testSucceed

      public static <T extends Throwable> void testSucceed​(Try.Execution execution, String message, Class<T> throwableClass)
      Fails if the execution does not succeed.
      Type Parameters:
      T - throwable type
      Parameters:
      execution - Execution; functional interface to execute
      message - String; fail message
      throwableClass - Class<T>; throwable class to catch