Do not bury exceptions - tooltwist/documentation GitHub Wiki

ToolTwist provides various levels of error handling, and one of the most important is exception handling.

Beware of code that prevents exceptions from bubbling up through the function hierarchy to where it can be handled properly. We call exceptions that are handled prematurely, rather than passing up through the hierarchy buried exceptions - they never reach the surface where they can be reported to the user or developer.

When writing the code used in production (e.g. view helpers, request handlers and interceptors). If exceptions are not handled correctly it becomes very difficult to debug problems in a live system.

As an example of bad coding, consider the following code in a view helper:

@Override
public XData preFetch(UimData ud) throws Exception {
	try {
		/* do something */
	} catch (SomeException e) {
		logger.error("Failed to do xyz.", e);
	}
	return null;
}

In this case, an error is written to the log file, but there is no other indication that a problem has occurred.

If the exception handling is simply removed, the exception passes back out from the preFetch() method and gets handled correctly.

@Override
public XData preFetch(UimData ud) throws Exception {
	/* do something */
	return null;
}

When ToolTwist detects an exception, a small dot also appears next to the "Powered by ToolTwist" icon, so a developer is aware an error occurred. In development mode clicking on the dot will provide full details of the problem, from the web browser, without the need to dig through log files. See Why the "Powered By Tooltwist" widget is important for more information.

If you wish to provide more useful information, then throw a new exception containing that information. You might wish to add the stack trace of the original exception.

@Override
public XData preFetch(UimData ud) throws Exception {
	try {
		/* do something */
	} catch (SomeException e) {
		MyAppException exception = new MyAppException("Failed to do xyz.", e);
		exception.setStackTrace(e.getStackTrace());
		throw exception;
	}
	return null;
}

Specific error messages

If you must bury an exception in order for the application to recover from the error, you can report the error to ToolTwist using the following code:

WbdSession.addError(ud.getCredentials(), this.getClass().getName(), e);

---