For the latest stable version, please use Spring Shell 3.4.1!

@ExceptionResolver

@ShellComponent classes can have @ExceptionResolver methods to handle exceptions from component methods. These are meant for annotated methods.

The exception may match against a top-level exception being propagated (e.g. a direct IOException being thrown) or against a nested cause within a wrapper exception (e.g. an IOException wrapped inside an IllegalStateException). This can match at arbitrary cause levels.

For matching exception types, preferably declare the target exception as a method argument, as the preceding example(s) shows. When multiple exception methods match, a root exception match is generally preferred to a cause exception match. More specifically, the ExceptionDepthComparator is used to sort exceptions based on their depth from the thrown exception type.

Alternatively, the annotation declaration may narrow the exception types to match, as the following example shows:

@ExceptionResolver({ RuntimeException.class })
CommandHandlingResult errorHandler(Exception e) {
	// Exception would be type of RuntimeException,
	// optionally do something with it
	return CommandHandlingResult.of("Hi, handled exception\n", 42);
}
@ExceptionResolver
CommandHandlingResult errorHandler(RuntimeException e) {
	return CommandHandlingResult.of("Hi, handled custom exception\n", 42);
}

@ExceptionResolver can also return String which is used as an output to console. You can use @ExitCode annotation to define return code.

@ExceptionResolver
@ExitCode(code = 5)
String errorHandler(Exception e) {
	return "Hi, handled exception";
}

@ExceptionResolver with void return type is automatically handled as handled exception. You can then also define @ExitCode and use Terminal if you need to write something into console.

@ExceptionResolver
@ExitCode(code = 5)
void errorHandler(Exception e, Terminal terminal) {
	PrintWriter writer = terminal.writer();
	String msg =  "Hi, handled exception " + e.toString();
	writer.println(msg);
	writer.flush();
}

Method Arguments

@ExceptionResolver methods support the following arguments:

Method argument Description

Exception type

For access to the raised exception. This is any type of Exception or Throwable.

Terminal

For access to underlying JLine terminal to i.e. get its terminal writer.

Return Values

@ExceptionResolver methods support the following return values:

Return value Description

String

Plain text to return to a shell. Exit code 1 is used in this case.

CommandHandlingResult

Plain CommandHandlingResult having message and exit code.

void

A method with a void return type is considered to have fully handled the exception. Usually you would define Terminal as a method argument and write response using terminal writer from it. As exception is fully handled, Exit code 0 is used in this case.