org.djutils.exceptions

Class Throw

java.lang.Object

org.djutils.exceptions.Throw

public final class Throw
extends Object

The Throw class has a number of static methods that make it easy to throw an exception under conditions for any Exception class, including the standard Java exceptions and exceptions from libraries that are used in the project. Instead of:

 if (car == null)
 {
     throw new NullPointerException("Car may not be null.");
 }
 if (Double.isNaN(car.getPosition()))
 {
     throw new IllegalArgumentException("Position of car " + car + " is NaN.");
 }
 

we can write:

 Throw.whenNull(car, "Car may not be null.");
 Throw.when(Double.isNaN(car.getPosition()), IllegalArgumentException.class, "Position of car %s is NaN.", car);
 

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. All methods have a version where the first parameter is returned. Thereby, the Throw can be used as part of a super(...) call in a constructor.

Copyright (c) 2016-2019 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 Summary

Modifier and Type	Method and Description
static <T extends Throwable> void	when(boolean condition, Class<T> throwableClass, String message) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable> void	when(boolean condition, Class<T> throwableClass, String message, Object arg) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable> void	when(boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable> void	when(boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2, Object arg3) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable> void	when(boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2, Object arg3, Object... args) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable,O> O	when(O object, boolean condition, Class<T> throwableClass, String message) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable,O> O	when(O object, boolean condition, Class<T> throwableClass, String message, Object arg) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable,O> O	when(O object, boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable,O> O	when(O object, boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2, Object arg3) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <T extends Throwable,O> O	when(O object, boolean condition, Class<T> throwableClass, String message, Object arg1, Object arg2, Object arg3, Object... args) Throw a Throwable (such as an Exception or Error) if a condition is met, e.g.
static <O> O	whenNull(O object, String message) Throw a NullPointerException if object is null, e.g.
static <O> O	whenNull(O object, String message, Object arg) Throw a NullPointerException if object is null, e.g.
static <O> O	whenNull(O object, String message, Object arg1, Object arg2) Throw a NullPointerException if object is null, e.g.
static <O> O	whenNull(O object, String message, Object arg1, Object arg2, Object arg3) Throw a NullPointerException if object is null, e.g.
static <O> O	whenNull(O object, String message, Object arg1, Object arg2, Object arg3, Object... args) Throw a NullPointerException if object is null, e.g.

Methods inherited from class java.lang.Object

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

Method Detail

when

public static <T extends Throwable> void when(boolean condition,
                                              Class<T> throwableClass,
                                              String message)
                                       throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(Double.isNan(object.getValue()), IllegalArgumentException.class, "Value may not be NaN.");
 

Type Parameters:

T - the Throwable type

Parameters:

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable> void when(boolean condition,
                                              Class<T> throwableClass,
                                              String message,
                                              Object arg)
                                       throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(Double.isNan(object.getValue()), IllegalArgumentException.class, "Value may not be NaN for object %s.",
         object);
 

Type Parameters:

T - the Throwable type

Parameters:

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, with formatting identifiers

arg - Object; value to use for the formatting identifiers

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable> void when(boolean condition,
                                              Class<T> throwableClass,
                                              String message,
                                              Object arg1,
                                              Object arg2)
                                       throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s.", object, name);
 

Type Parameters:

T - the Throwable type

Parameters:

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, 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 - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable> void when(boolean condition,
                                              Class<T> throwableClass,
                                              String message,
                                              Object arg1,
                                              Object arg2,
                                              Object arg3)
                                       throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s and id %s.", object, name, id);
 

Type Parameters:

T - the Throwable type

Parameters:

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, 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 - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable> void when(boolean condition,
                                              Class<T> throwableClass,
                                              String message,
                                              Object arg1,
                                              Object arg2,
                                              Object arg3,
                                              Object... args)
                                       throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s, id %s and parent %s.", object, name, id, parent);
 

Type Parameters:

T - the Throwable type

Parameters:

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, 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 - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable,O> O when(O object,
                                             boolean condition,
                                             Class<T> throwableClass,
                                             String message)
                                      throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. This version of the method returns its first parameter, so it can be used inside a constructor. Use e.g., as follows:

 super(Throw.when(object, Double.isNan(object.getValue()), IllegalArgumentException.class, "Value may not be NaN."));
 

Type Parameters:

T - the Throwable type

O - the Object type to return

Parameters:

object - O; the object to return by this static method

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception

Returns:

the object that was passed as the first parameter

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable,O> O when(O object,
                                             boolean condition,
                                             Class<T> throwableClass,
                                             String message,
                                             Object arg)
                                      throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. This version of the method returns its first parameter, so it can be used inside a constructor. Use e.g., as follows:

 super(Throw.when(object, Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s.", object));
 

Type Parameters:

T - the Throwable type

O - the Object type to return

Parameters:

object - O; the object to return by this static method

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, with formatting identifiers

arg - Object; value to use for the formatting identifiers

Returns:

the object that was passed as the first parameter

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable,O> O when(O object,
                                             boolean condition,
                                             Class<T> throwableClass,
                                             String message,
                                             Object arg1,
                                             Object arg2)
                                      throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. This version of the method returns its first parameter, so it can be used inside a constructor. Use e.g., as follows:

 super(Throw.when(object, Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s.", object, name));
 

Type Parameters:

T - the Throwable type

O - the Object type to return

Parameters:

object - O; the object to return by this static method

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, with formatting identifiers

arg1 - Object; 1st value to use for the formatting identifiers

arg2 - Object; 2nd value to use for the formatting identifiers

Returns:

the object that was passed as the first parameter

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable,O> O when(O object,
                                             boolean condition,
                                             Class<T> throwableClass,
                                             String message,
                                             Object arg1,
                                             Object arg2,
                                             Object arg3)
                                      throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. This version of the method returns its first parameter, so it can be used inside a constructor. Use e.g., as follows:

 super(Throw.when(object, Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s and id %s.", object, name, id));
 

Type Parameters:

T - the Throwable type

O - the Object type to return

Parameters:

object - O; the object to return by this static method

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, 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:

the object that was passed as the first parameter

Throws:

T - the throwable to throw on true condition

T extends Throwable

when

public static <T extends Throwable,O> O when(O object,
                                             boolean condition,
                                             Class<T> throwableClass,
                                             String message,
                                             Object arg1,
                                             Object arg2,
                                             Object arg3,
                                             Object... args)
                                      throws T extends Throwable

Throw a Throwable (such as an Exception or Error) if a condition is met, e.g. for pre- and postcondition checking. This version of the method returns its first parameter, so it can be used inside a constructor. Use e.g., as follows:

 super(Throw.when(object, Double.isNan(object.getValue()), IllegalArgumentException.class,
         "Value may not be NaN for object %s with name %s, id %s and parent %s.", object, name, id, parent));
 

Type Parameters:

T - the Throwable type

O - the Object type to return

Parameters:

object - O; the object to return by this static method

condition - the condition to check; an exception will be thrown if this is true

throwableClass - Class<T>; the Throwable type to throw

message - String; the message to use in the exception, 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:

the object that was passed as the first parameter

Throws:

T - the throwable to throw on true condition

T extends Throwable

whenNull

public static <O> O whenNull(O object,
                             String message)
                      throws NullPointerException

Throw a NullPointerException if object is null, e.g. for pre- and postcondition checking. Use as follows:

 Throw.when(object.getValue(), "Value may not be null.");
 

Type Parameters:

O - the Object type to return

Parameters:

object - object to check; an exception will be thrown if this is null

message - String; the message to use in the exception

Returns:

the object that was passed as the first parameter

Throws:

NullPointerException - if object is null

whenNull

public static <O> O whenNull(O object,
                             String message,
                             Object arg)
                      throws NullPointerException

Throw a NullPointerException if object is null, e.g. for pre- and postcondition checking. Use as follows:

 Throw.whenNull(object.getValue(), "Value may not be null for object %s.", object);
 

Type Parameters:

O - the Object type to return

Parameters:

object - object to check; an exception will be thrown if this is null

message - String; the message to use in the exception, with formatting identifiers

arg - Object; value to use for the formatting identifiers

Returns:

the object that was passed as the first parameter

Throws:

NullPointerException - if object is null

whenNull

public static <O> O whenNull(O object,
                             String message,
                             Object arg1,
                             Object arg2)
                      throws NullPointerException

Throw a NullPointerException if object is null, e.g. for pre- and postcondition checking. Use as follows:

 Throw.whenNull(object.getValue(), "Value may not be null for object %s with name %s.", object, name);
 

Type Parameters:

O - the Object type to return

Parameters:

object - object to check; an exception will be thrown if this is null

message - String; the message to use in the exception, with formatting identifiers

arg1 - Object; 1st value to use for the formatting identifiers

arg2 - Object; 2nd value to use for the formatting identifiers

Returns:

the object that was passed as the first parameter

Throws:

NullPointerException - if object is null

whenNull

public static <O> O whenNull(O object,
                             String message,
                             Object arg1,
                             Object arg2,
                             Object arg3)
                      throws NullPointerException

Throw a NullPointerException if object is null, e.g. for pre- and postcondition checking. Use as follows:

 Throw.whenNull(object.getValue(), "Value may not be null for object %s with name %s and id %s.", object, name, id);
 

Type Parameters:

O - the Object type to return

Parameters:

object - object to check; an exception will be thrown if this is null

message - String; the message to use in the exception, 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:

the object that was passed as the first parameter

Throws:

NullPointerException - if object is null

whenNull

public static <O> O whenNull(O object,
                             String message,
                             Object arg1,
                             Object arg2,
                             Object arg3,
                             Object... args)
                      throws NullPointerException

Throw a NullPointerException if object is null, e.g. for pre- and postcondition checking. Use as follows:

 Throw.whenNull(object.getValue(), "Value may not be null for object %s with name %s, id %s and parent %s.", object,
         name, id, parent);
 

Type Parameters:

O - the Object type to return

Parameters:

object - object to check; an exception will be thrown if this is null

message - String; the message to use in the exception, 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:

the object that was passed as the first parameter

Throws:

NullPointerException - if object is null