Exception Handling inside GrpcService

<- Back to Index

This section describes how you can handle exceptions inside GrpcService layer without cluttering up your code.

Table of Contents

• Proper exception handling
• Detailed explanation
  • Priority of mapped exceptions
  • Sending Metadata in response
  • Overview of returnable types

Additional Topics

• Getting Started
• Configuration
• Contextual Data
• Exception Handling
• Testing the Service
• Server Events
• Security

Proper exception handling

If you are already familiar with spring’s error handling, you should see some similarities with the exception handling for gRPC.

An explanation for the following class:

@GrpcAdvice
public class GrpcExceptionAdvice {


    @GrpcExceptionHandler
    public Status handleInvalidArgument(IllegalArgumentException e) {
        return Status.INVALID_ARGUMENT.withDescription("Your description").withCause(e);
    }

    @GrpcExceptionHandler(ResourceNotFoundException.class)
    public StatusException handleResourceNotFoundException(ResourceNotFoundException e) {
        Status status = Status.NOT_FOUND.withDescription("Your description").withCause(e);
        Metadata metadata = ...
        return status.asException(metadata);
    }

}

• @GrpcAdvice marks a class to be checked up for exception handling methods
• @GrpcExceptionHandler marks the annotated method to be executed, in case of the specified exception being thrown
  • f.e. if your application throws IllegalArgumentException, then the handleInvalidArgument(IllegalArgumentException e) method will be executed
• The method must either return a io.grpc.Status, StatusException, or StatusRuntimeException
• If you handle server errors, you might want to log the exception/stacktrace inside the exception handler

Note: Cause is not transmitted from server to client - as stated in official docs So we recommend adding it to the Status/StatusException to avoid the loss of information on the server side.

Detailed explanation

Priority of mapped exceptions

Given this method with specified exception in the annotation and as a method argument

@GrpcExceptionHandler(ResourceNotFoundException.class)
public StatusException handleResourceNotFoundException(ResourceNotFoundException e) {
    // your exception handling
}

If the GrpcExceptionHandler annotation contains at least one exception type, then only those will be considered for exception handling for that method. The method parameters must be “compatible” with the specified exception types. If the annotation does not specify any handled exception types, then all method parameters are being used instead.

(“Compatible” means that the exception type in annotation is either the same class or a superclass of one of the listed method parameters)

Sending Metadata in response

In case you want to send metadata in your exception response, let’s have a look at the following example.

@GrpcExceptionHandler
public StatusRuntimeException handleResourceNotFoundException(IllegalArgumentException e) {
    Status status = Status.INVALID_ARGUMENT.withDescription("Your description");
    Metadata metadata = ...
    return status.asRuntimeException(metadata);
}

If you do not need Metadata in your response, just return your specified Status.

Overview of returnable types

Here is a small overview of possible mapped return types with @GrpcExceptionHandler and if custom Metadata can be returned:

Return Type	Supports Custom Metadata
Status	✗
StatusException	✔
StatusRuntimeException	✔

Additional Topics

• Getting Started
• Configuration
• Contextual Data
• Exception Handling
• Testing the Service
• Server Events
• Security

---

<- Back to Index