org.josef.util

Class CDebug

java.lang.Object

org.josef.util.CDebug

@Status(stage=PRODUCTION,
        unitTests=PARTIAL)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public final class CDebug
extends Object

Class that aids in debugging.
As soon as a method is called, its parameters should be checked. When for example a setter is called and null is passed without a check, a NullPointerException may occur much later in a very different place, making it difficult to find out that this was caused by passing null to this setter. This class helps you, among other things, check method parameters. For example:

 public void method(final String value) {
     CDebug.checkParameterNotEmpty(value, ParameterName.VALUE);
     ...
 }

The method above checks that the supplied parameter is neither null nor empty. Many more methods like the one above exist!

These methods are different from assert methods because they throw standard runtime exceptions instead of an Error like the assert statements. As a rule of thumb, public methods should use the check...(...) methods from this class and private methods should use assertions.
Note: Some expressions may take a lot of time to evaluate. To prevent this use the following construction:

 if (CDebug.isDebugEnabled()) {
     CDebug.checkParameterTrue(expensive_expression(), ParameterName.MESSAGE);
 }
 

This construction prevents the expensive_expression() from being evaluated when debug mode is disabled.
Note: debug mode is disabled by default. To enable debug mode you can call the setDebug(boolean) method with a value of true or use -Ddebug=true as a VM argument.

Version:

3.0 $Revision: 6483 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
static void	checkParameterNotEmpty(Collection<?> collectionParameter, String parameterName) Checks that the supplied collectionParameter reference is not empty.
static void	checkParameterNotEmpty(double[] arrayParameter, String parameterName) Checks that the supplied arrayParameter reference is not empty.
static void	checkParameterNotEmpty(Object[] arrayParameter, String parameterName) Checks that the supplied arrayParameter reference is not empty.
static void	checkParameterNotEmpty(String parameter, String parameterName) Checks that the supplied String parameter reference is not empty.
static void	checkParameterNotNull(Object parameter, String parameterName) Checks that the supplied parameter reference is not null.
static void	checkParameterTrue(boolean expression, String message) Checks that the supplied boolean value (expression) is true.
static String	getStackTrace(Throwable throwable) Gets the stack trace from the supplied throwable.
static void	invariant(boolean expression) Checks that the supplied boolean invariant is true.
static void	invariant(boolean expression, String message) Checks that the supplied boolean invariant is true.
static boolean	isDebugEnabled() Determines whether debug mode is enabled (true) or disabled (false).
static void	postcondition(boolean expression) Checks that the supplied boolean postcondition is true.
static void	postcondition(boolean expression, String message) Checks that the supplied boolean postcondition is true.
static void	precondition(boolean expression) Checks that the supplied boolean precondition is true.
static void	precondition(boolean expression, String message) Checks that the supplied boolean precondition is true.
static void	setDebug(boolean debug) Enables or disables the josef debug mode.

Methods inherited from class java.lang.Object

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

Method Detail

isDebugEnabled

public static boolean isDebugEnabled()

Determines whether debug mode is enabled (true) or disabled (false).
Use this method in your code to skip the evaluation of time consuming expressions.

Returns:

True when josef debug mode is enabled, false when disabled.

setDebug

public static void setDebug(boolean debug)

Enables or disables the josef debug mode.
Note: This method does not change the behavior of any method in this class, it only changes the behavior of your methods that use the isDebugEnabled() method.

Parameters:

debug - Supply true to enable josef debug mode, supply false to disable the josef debug mode.

precondition

public static void precondition(boolean expression)

Checks that the supplied boolean precondition is true.
Example: CDebug.precondition(x >= 0);

Parameters:

expression - Boolean expression to check.

Throws:

IllegalStateException - When the precondition fails.

precondition

public static void precondition(boolean expression,
                                String message)

Checks that the supplied boolean precondition is true.
Example: CDebug.precondition(x % 2 == 0, "x should be even but is 1!");

Parameters:

expression - Boolean expression to check.

message - Message to write when the precondition fails.

Throws:

IllegalStateException - When the precondition fails.

invariant

public static void invariant(boolean expression)

Checks that the supplied boolean invariant is true.
Example: CDebug.invariant(x >= 0);

Parameters:

expression - Boolean expression to check.

Throws:

IllegalStateException - When the invariant is broken.

invariant

public static void invariant(boolean expression,
                             String message)

Checks that the supplied boolean invariant is true.
Example: CDebug.invariant(x % 2 == 0, "x should be even but is 1!");

Parameters:

expression - Boolean expression to check.

message - Message to write when the invariant is broken.

Throws:

IllegalStateException - When the invariant is broken.

postcondition

public static void postcondition(boolean expression)

Checks that the supplied boolean postcondition is true.
Example: CDebug.postcondition(x >= 0);

Parameters:

expression - Boolean expression to check.

Throws:

IllegalStateException - When the postcondition fails.

postcondition

public static void postcondition(boolean expression,
                                 String message)

Checks that the supplied boolean postcondition is true.
Example: CDebug.postcondition(x % 2 == 0, "x should be even but is 1!");

Parameters:

expression - Boolean expression to check.

message - Message to write when the postcondition fails.

Throws:

IllegalStateException - When the postcondition fails.

checkParameterTrue

public static void checkParameterTrue(boolean expression,
                                      String message)

Checks that the supplied boolean value (expression) is true.
Example: CDebug.checkParameterTrue(text.length() > 3, "Input text is too short!");

Parameters:

expression - Boolean expression to check.

message - Message to write when the check fails.

Throws:

IllegalArgumentException - When the supplied boolean expression is false.

checkParameterNotNull

public static void checkParameterNotNull(Object parameter,
                                         String parameterName)

Checks that the supplied parameter reference is not null.
Example: CDebug.checkParameterNotNull(root, ParameterName.ROOT);

Parameters:

parameter - Parameter reference to check that it is not null.

parameterName - Name of the parameter.

Throws:

NullPointerException - When the supplied parameter is null.

checkParameterNotEmpty

public static void checkParameterNotEmpty(String parameter,
                                          String parameterName)

Checks that the supplied String parameter reference is not empty.
Example: CDebug.checkParameterNotEmpty(name, ParameterName.NAME);

Parameters:

parameter - String parameter reference to check that it is not empty.

parameterName - Name of the String reference.

Throws:

IllegalArgumentException - When the supplied parameter is empty.

NullPointerException - When the supplied parameter is null.

checkParameterNotEmpty

public static void checkParameterNotEmpty(Object[] arrayParameter,
                                          String parameterName)

Checks that the supplied arrayParameter reference is not empty.
Example: CDebug.checkParameterNotEmpty(countries, ParameterName.COUNTRIES);

Parameters:

arrayParameter - Array parameter reference to check that it is not empty.

parameterName - Name of the array reference.

Throws:

IllegalArgumentException - When the supplied arrayParameter is empty.

NullPointerException - When the supplied arrayParameter is null.

checkParameterNotEmpty

public static void checkParameterNotEmpty(double[] arrayParameter,
                                          String parameterName)

Checks that the supplied arrayParameter reference is not empty.
Example: CDebug.checkParameterNotEmpty(values, ParameterName.VALUES);

Parameters:

arrayParameter - Array parameter reference to check that it is not empty.

parameterName - Name of the array reference.

Throws:

IllegalArgumentException - When the supplied arrayParameter is empty.

NullPointerException - When the supplied arrayParameter is null.

checkParameterNotEmpty

public static void checkParameterNotEmpty(Collection<?> collectionParameter,
                                          String parameterName)

Checks that the supplied collectionParameter reference is not empty.
Example: CDebug.checkParameterNotEmpty(countries, ParameterName.COUNTRIES);

Parameters:

collectionParameter - Collection parameter reference to check that it is not empty.

parameterName - Name of the Collection reference.

Throws:

IllegalArgumentException - When the supplied collectionParameter is empty.

NullPointerException - When the supplied collectionParameter is null.

getStackTrace

public static String getStackTrace(Throwable throwable)

Gets the stack trace from the supplied throwable.

Parameters:

throwable - The throwable containing the stack trace.

Returns:

Stack trace of the supplied throwable.

Throws:

NullPointerException - When the supplied throwable is null.