In this blog post I would like to explain the differences between @ControllerAdvice and @RestControllerAdvice, because oftentimes, these two lead to confusion.

On the other hand, if you are not sure what are these two used for, then I recommend you to check out my previous article, where you can learn how to handle exceptions efficiently when creating Spring Boot REST API with @RestControllerAdvice and @ExceptionHandler.

2. What Is @ControllerAdvice?

Let’s start by describing what exactly the @ControllerAdvice is?

Basically, it’s been introduced in Spring 3.2 and is a specialized @Component that allows us to declare @ExceptionHandler, @InitBinder, or @ModelAttribute methods to be shared among @Controller classes.

To put it another way, we can treat it as an annotation driven interceptor, whose methods will apply to the whole application (not just to an individual controller).

3. What Is @RestControllerAdvice?

On the other hand, the @RestControllerAdvice is a syntactic sugar for @ControllerAdvice and @ResponseBody annotations.

To illustrate, let’s see it’s definition:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @interface RestControllerAdvice

Basically, the @ResponseBody indicates a method return value should be bound to the web response body. To put it simply, it allows us to implement methods without wrapping them with ResponseEntity<T> (or HttpEntity<T>):

fun withResponseEntity(): ResponseEntity<SomeClass> =
  ResponseEntity.ok(
    SomeClass()
  )

@ResponseBody
fun withResponseBody(): SomeClass =
  SomeClass()

Additionally, since Spring 4.0, it can be used on the type level, so it will be inherited by all methods of an annotated class.

4. @ControllerAdvice vs @RestControllerAdvice in Practice

With all of that being said, let’s analyze a few examples to better understand these differences.

Firstly, let’s create the Exceptions.kt file with a few custom exceptions:

class CustomExceptionOne : RuntimeException()
class CustomExceptionTwo : RuntimeException()
class CustomExceptionThree : RuntimeException()
class CustomExceptionFour : RuntimeException()
class CustomExceptionFive : RuntimeException()

Nextly, let’s add the ExampleResponse class carrying messages for API consumers:

data class ExampleResponse(val message: String)

Finally, let’s implement the ExampleController class:

@RestController
class ExampleController {

  @GetMapping("/one")
  fun endpointOne(): ExampleResponse {
    throw CustomExceptionOne()
    return ExampleResponse("Message")
  }

  @GetMapping("/two")
  fun endpointTwo(): ExampleResponse {
    throw CustomExceptionTwo()
    return ExampleResponse("Message")
  }

  @GetMapping("/three")
  fun endpointThree(): ExampleResponse {
    throw CustomExceptionThree()
    return ExampleResponse("Message")
  }

  @GetMapping("/four")
  fun endpointFour(): ExampleResponse {
    throw CustomExceptionFour()
    return ExampleResponse("Message")
  }

  @GetMapping("/five")
  fun endpointFive(): ExampleResponse {
    throw CustomExceptionFive()
    return ExampleResponse("Message")
  }

}

These are just a few test endpoints, which will be helpful to better understand @ControllerAdvice and @RestControllerAdvice in our examples.  Whatsoever, we can clearly see that each method throws its own, custom exception before returning ExampleResponse instance.

Without a doubt, querying any of these endpoints at this point will result in 500 Internal Server Error.

5. @ControllerAdvice Examples

5.1. Plain @ControllerAdvice

Undoubtedly, we don’t want our clients to see this type of responses and we should handle such cases in our code.

As the first step, let’s create the ErrorResponse, which will be used to return information for properly handled exceptions:

data class ErrorResponse(val message: String)

Following, let’s create the ExampleControllerAdvice:

@ControllerAdvice
class ExampleControllerAdvice {

  @ExceptionHandler(CustomExceptionOne::class)
  fun handleExceptionOne(): ErrorResponse =
    ErrorResponse("Handled exception one!")

}

As we can see, the class is marked as a @ControllerAdvice. Moreover, the method annotated with @ExceptionHandler should be invoked each time a CustomExceptionOne is thrown returning ErrorResponse instance.

Let’s check this assumption with cURL command:

curl localhost:8080/one

# Console Output:
javax.servlet.ServletException: Circular view path [one]...

# Response Body: 
{
  "timestamp": "2022-01-01T01:01:01.839+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/one"
}

Well, this is not the response we were expecting. We can clearly see, that the exception was not caught properly leading to the ServletException.

5.2. @ControllerAdvice with ResponseEntity

But how can we solve this issue?

We’ve got a few possibilities, so let’s see the first one:

@ExceptionHandler(CustomExceptionTwo::class)
fun handleExceptionTwo(): ResponseEntity<ErrorResponse> =
  ResponseEntity.ok(
    ErrorResponse("Handled exception two!")
  )

This time, instead of returning ErrorResponse instance, we wrap it with the ResponseEntity<T>.

Let’s test our dedicated endpoint then:

curl localhost:8080/two

# Console Output:
empty

# Response Body: 
{
  "message": "Handled exception two!"
}

Obviously, this time handler works as expected returning the desired message. Whatsoever, empty console output indicates that no exception remain unhandled in this case.

5.3. @ResponseBody On Method Level

On the other hand, if we don’t want to return ResponseEntity, we can simply put @ResponseBody annotation to work:

@ExceptionHandler(CustomExceptionThree::class)
@ResponseBody
fun handleExceptionThree(): ErrorResponse =
  ErrorResponse("Handled exception three!")

Similarly, let’s check this handler:

curl localhost:8080/three

# Console Output:
empty

# Response Body: 
{
  "message": "Handled exception three!"
}

Again, the exception is handled perfectly.

5.4. @ResponseBody On Class Level

Although annotating methods with @ResponseBody is necessary in some cases, this approach would be better oftentimes.

To avoid unnecessary redundancy, we can simply put this annotation at the class level and it will be applied to all methods:

@ControllerAdvice
@ResponseBody
class ExampleControllerAdviceAnnotated {

  @ExceptionHandler(CustomExceptionFour::class)
  fun handleExceptionFour(): ErrorResponse =
    ErrorResponse("Handled exception four!")
}

Let’s check again:

curl localhost:8080/four

# Console Output:
empty

# Response Body: 
{
  "message": "Handled exception four!"
}

Similarly, we can see desired message in the response body.

6. @RestControllerAdvice Example

And finally we come to the point,that @RestControllerAdvice is a @ControllerAdvice with @ResponseBody (just like above).

Let’s implement our last example:

@RestControllerAdvice
class ExampleRestControllerAdvice {

  @ExceptionHandler(CustomExceptionFive::class)
  fun handleExceptionFive(): ErrorResponse =
    ErrorResponse("Handled exception five!")
}

Following, let’s query the necessary endpoint:

curl localhost:8080/five

# Console Output:
empty

# Response Body: 
{
  "message": "Handled exception five!"
}

Identically, the exception has been caught successfully by the dedicated handler.

7. @ControllerAdvice vs @RestControllerAdvice Summary

And that would be all for this comparison article on @ControllerAdvice vs @RestControllerAdvice. I believe, that after reading it you will have no more doubts about the differences between these two.

As always, if you would like to see the source code for this post, please check out this GitHub repository.

Finally, if you enjoy this type of content, please let me know in the comments section below, or by the contact form.

Previous articles, you might be interested in:

• REST API With Ktor, Ktorm and PostgreSQL
• Exception Handling with @RestControllerAdvice and @ExceptionHandler
• 16 IntelliJ Shortcuts That Will Boost Your Productivity

The post @ControllerAdvice vs @RestControllerAdvice appeared first on Codersee blog- Kotlin on the backend.

In this article, I would like to show you several ways we can handle exceptions with @RestControllerAdvice and @ExceptionHandler in a Spring Boot REST API.

Exceptions are nothing else than exceptional events indicating the standard program flow has been affected in any way. Sooner or later, some of them will appear in our applications and it’s our job to handle them in the best possible way.

When creating REST APIs with Spring Boot, a huge amount of work is done by the framework to prevent the application from stopping. Nevertheless, returning 500 Internal Server Error responses to clients is not the best practice and in this tutorial we will see how can we fix that.

2. @RestControllerAdvice and @ExceptionHandler

Let’s start by describing what exactly @RestControllerAdvice and @ExceptionHandler are.

@RestControllerAdvice is a syntactic sugar for @ControllerAdvice and @ResponseBody annotations. The first one, @ControllerAdvice, has been introduced in Spring 3.2 and allows us to write a code, which will be applied globally to all controllers. It can be used to add model enhancements methods, binder initialization methods, and what’s important for us today- to handle exceptions. In simple words, it allows us to implement some logic only once, instead of duplicating it across the app. Additionally, classes annotated with it do not have to be injected or declared explicitly in controllers, improving the decoupling of our logic.

On the other hand, the @ResponseBody indicates that our methods’ return values should be bound to the web response body. To put it simply- our handler methods returning some ExampleClass will be treated as ResponseEntity<ExampleClass> out of the box. As I have said, the @RestControllerAdvice combines it with the @ControllerAdvice, so that we do not have to annotate our methods explicitly.

Finally, the @ExceptionHandler is an annotation used to mark that the given method should be invoked when a specific exception is thrown.

[elementor-template id=”9007393″]

3. Simple @ExceptionHandler

With all of that being said, let’s create the Exceptions.kt file and add exceptions classes:

class FirstCustomException(message: String) : RuntimeException(message)
class SecondCustomException(message: String) : RuntimeException(message)

@ResponseStatus(HttpStatus.BAD_REQUEST)
class ThirdCustomException(message: String) : RuntimeException(message)

class FourthCustomException(message: String) : RuntimeException(message)

As we can see, they are pretty much the same, except the ThirdCustomException, which is marked as 400 Bad Request.

As the next step, let’s create a controller class with the first method:

@RestController
class ExampleController {

  @GetMapping("/example-exception-one")
  fun getExampleExceptionOne(): ExampleResponseBody {
    throw FirstCustomException("First exception message")
    return ExampleResponseBody(message = "ok")
  }
  
  data class ExampleResponseBody(val message: String)
}

We can clearly see, that the exception is thrown and the ExampleResponseBody instance will be never returned.

Whatsoever, if we run the application and perform a GET request, we will see the Internal Server Error:

{
  "timestamp": "2022-01-14T07:08:10.061+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/example-exception-one"
}

As the next step, let’s add the ExampleAdvice class:

@RestControllerAdvice
class ExampleAdvice {

  @ExceptionHandler(FirstCustomException::class)
  fun handleFirstCustomException() {
    println("FirstCustomException handler")
  }
}

This time, the class is annotated with the @RestControllerAdvice and it contains a method which will print some text to the output. The most important thing is that the function is annotated with the @ExceptionHandler indicating, which exception should be handled by it. Moreover, it allows us to specify multiple exceptions, for example:

@ExceptionHandler(value = [ExceptionOne::class, ExceptionTwo::class])

But let’s get back to our example, rerun the application and test the endpoint once again. This time, the 200 OK response has been returned along with the desired message printed to the console:

# Console:
FirstCustomException handler
# Response:
Status: 200 OK
Body: empty

Unfortunately, the response body is empty, which may cause problems (and we will see better approaches in the next examples). Besides that, we can clearly see that the handler is working, as expected.

4. Map Status Code With @ResponseStatus

As the next example, let’s see how can we map the status code returned by our handler. Let’s add a new method within the controller:

@GetMapping("/example-exception-two")
fun getExampleExceptionTwo(): ExampleResponseBody {
  throw SecondCustomException("Second exception message")
  return ExampleResponseBody(message = "ok")
}

It’s almost exactly the same as the previous one.

Nextly, let’s implement a new exception handler:

@ResponseStatus(HttpStatus.FAILED_DEPENDENCY)
@ExceptionHandler(SecondCustomException::class)
fun handleSecondCustomException() {
  println("SecondCustomException handler")
}

This time, we’ve additionally marked it with the @ResponseStatus annotation and the desired HTTP status.

Similarly, let’s test our new endpoint:

# Console:
SecondCustomException handler
# Response:
Status: 200 OK
Body: empty

We can clearly see that the new handler has been triggered and the 424 Failed Dependency has been returned. Not an ideal solution, but still better, then the previous one.

5. Read Exception Message and Re-throw Exception

For the record, in the beginning, we’ve annotated the ThirdCustomException with @ResponseStatus:

@ResponseStatus(HttpStatus.BAD_REQUEST)
class ThirdCustomException(message: String) : RuntimeException(message)

It means, that it will be translated to 400 Bad Request each time it is thrown (so that we won’t have to mark our handler method).

Nevertheless, let’s focus on the another approach, which resolves the issue with empty response body. Just like previously, let’s start by adding the necessary controller:

@GetMapping("/example-exception-three")
fun getExampleExceptionThree(): ExampleResponseBody {
  throw ThirdCustomException("Third exception message")
  return ExampleResponseBody(message = "ok")
}

As the next step, let’s implement a new exception handler:

@ExceptionHandler(ThirdCustomException::class)
fun handleThirdCustomException(ex: ThirdCustomException) {
  println("ThirdCustomException handler. Exception message: ${ex.message}")
  throw ex
}

As we can see, except marking our methods with annotation, we additionally inject the exception instance. This approach might be really helpful when we would like to log the exception details. It’s worth mentioning, that handler methods allow us to inject plenty of information, so I highly recommend you to check out the documentation (we’ll cover one more in the next example).

Finally, let’s test the endpoint:

# Console:
ThirdCustomException handler. Exception message: Third exception message

# Response:
Status: 400 Bad Request
Body:
{
  "timestamp": "2022-01-18T01:01:01.111+00:00",
  "status": 400,
  "error": "Bad Request",
  "path": "/example-exception-three"
}

As we can see, the console output contains the exception message, which might be really helpful in the real-life scenarios. Additionally, the response body is not empty anymore providing more information to the API client.

6. Return Custom Object

I’ve mentioned in the beginning that @RestControllerAdvice is a @ControllerAdvice enhanced with the @ResponseBody annotation.

Let’s add the below code:

@GetMapping("/example-exception-four")
fun getExampleExceptionFour(): ExampleResponseBody {
  throw FourthCustomException("Fourth exception message")
  return ExampleResponseBody(message = "ok")
}

As the next step, let’s implement a new handler along with a custom data class:

@ExceptionHandler(FourthCustomException::class)
fun handleFourthCustomException(
  req: HttpServletRequest,
  ex: FourthCustomException
): ExceptionResponseBody {
  println("FourthCustomException handler. Request details: [${req.getHeader("custom-header")}]")
  return ExceptionResponseBody(errorMessage = ex.message)
}

data class ExceptionResponseBody(val errorMessage: String?)

If we query this endpoint passing ‘passed value’ as a value of ‘custom-header’ header, we should see the following result:

# Console:
FourthCustomException handler. Request details: [passed value]

# Response:
Status: 200 OK
Body:
{
  "errorMessage": "Fourth exception message"
}

Unquestionably, the desired value has been obtained correctly. Moreover, the instance of ExceptionResponseBody has been serialized to JSON and sent as a request body with 200 OK status.

This strategy might be really useful, if we would like to extract some custom format for our errors.

7. @RestControllerAdvice and @ExceptionHandler Summary

And that would be all for this tutorial covering @RestControllerAdvice and @ExceptionHandler. We went through a few practical examples describing how to use these two can help you when working with Spring Boot.

If you would like to see the source code for this article, please refer to this GitHub repository. Also, I’ve created one more article related to @RestControllerAdvice, which you can find right here.

Finally, if you find this kind of articles useful, or have any suggestions, please let me know in the comments section, or through the contact form.

Previous articles, you might be interested in:

• 16 IntelliJ Shortcuts That Will Boost Your Productivity
• SOLID Principles with Kotlin Examples
• How to Generate a PDF in a Spring Boot REST API with Apache PDFBox and Kotlin

The post Exception Handling with @RestControllerAdvice and @ExceptionHandler appeared first on Codersee blog- Kotlin on the backend.