Package com.linecorp.armeria.server

Interface ServerErrorHandler

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@UnstableApi
@FunctionalInterface
public interface ServerErrorHandler

Provides the error responses in case of unexpected exceptions or protocol errors. Implement this interface to customize Armeria's error responses.

 ServerErrorHandler errorHandler = (ctx, cause) -> {
     if (cause instanceof IllegalArgumentException) {
         return HttpResponse.of(HttpStatus.BAD_REQUEST);
     }

     // You can return a different response using the path.
     if ("/outage".equals(ctx.path())) {
         return HttpResponse.of(HttpStatus.INTERNAL_SERVER_ERROR,
                                MediaType.PLAIN_TEXT, "Oops, something went wrong.");
     }

     // Return null to let ServerErrorHandler.ofDefault() handle the exception.
     return null;
 }

 Server.builder().errorHandler(errorHandler)...
 

Recording a service exception (or not)

By default, an exception raised by a service or a decorator is captured and recorded into RequestLog.responseCause(). You can keep Armeria from recording it while sending the desired response by returning a failed response whose cause is an HttpStatusException or HttpResponseException:

 ServerErrorHandler errorHandler = (ctx, cause) -> {
     if (cause instanceof IllegalArgumentException) {
         // IllegalArgumentException is captured into RequestLog#responseCause().
         return HttpResponse.of(HttpStatus.BAD_REQUEST);
     }

     if (cause instanceof NotFoundException) {
         // NotFoundException is NOT captured into RequestLog#responseCause().
         return HttpResponse.ofFailure(HttpStatusException.of(HttpStatus.NOT_FOUND));
     }
     ...
 }
 

See Also:

• ServerBuilder.errorHandler(ServerErrorHandler)
• ServiceErrorHandler

Method Summary

Modifier and Type	Method	Description
default ServiceErrorHandler	asServiceErrorHandler()	Transforms this ServerErrorHandler into a ServiceErrorHandler.
static ServerErrorHandler	ofDefault()	Returns the default ServerErrorHandler.
default @Nullable AggregatedHttpResponse	onProtocolViolation(ServiceConfig config, @Nullable RequestHeaders headers, HttpStatus status, @Nullable String description, @Nullable Throwable cause)	Returns an AggregatedHttpResponse for the protocol error signified by the given HttpStatus, message, and Throwable.
@Nullable HttpResponse	onServiceException(ServiceRequestContext ctx, Throwable cause)	Returns an HttpResponse for the given Throwable raised by a service.
default ServerErrorHandler	orElse(ServerErrorHandler other)	Returns a newly created ServerErrorHandler that tries this ServerErrorHandler first and then the specified ServerErrorHandler when the first call returns null.
default @Nullable AggregatedHttpResponse	renderStatus(ServiceConfig config, @Nullable RequestHeaders headers, HttpStatus status, @Nullable String description, @Nullable Throwable cause)	Returns an AggregatedHttpResponse generated from the given HttpStatus, message and Throwable.

Method Details

ofDefault

static ServerErrorHandler ofDefault()

Returns the default ServerErrorHandler. This handler is also used as the final fallback when the handler customized with ServerBuilder.errorHandler(ServerErrorHandler) returns null. For example, the following handler basically delegates all error handling to the default handler:

 Server
   .builder()
   .errorHandler((ctx, cause) -> null)
   ...
 

onServiceException

@Nullable
@Nullable HttpResponse onServiceException(ServiceRequestContext ctx,
 Throwable cause)

Returns an HttpResponse for the given Throwable raised by a service. This method is invoked once for each request failed with a service-level exception.

Parameters:

ctx - the ServiceRequestContext of the current request.

cause - the Throwable raised by the service that handled the current request.

Returns:

an HttpResponse to send to the client, or null to let the next handler specified with orElse(ServerErrorHandler) handle the event.

onProtocolViolation

@Nullable
default @Nullable AggregatedHttpResponse onProtocolViolation(ServiceConfig config,
 @Nullable
 @Nullable RequestHeaders headers,
 HttpStatus status,
 @Nullable
 @Nullable String description,
 @Nullable
 @Nullable Throwable cause)

Returns an AggregatedHttpResponse for the protocol error signified by the given HttpStatus, message, and Throwable. This method is invoked once for each request failed at the protocol level.

Parameters:

config - the ServiceConfig that provides the configuration properties.

headers - the received RequestHeaders, or null in case of severe protocol violation.

status - the desired HttpStatus of the error response.

description - an optional human-readable description of the error.

cause - an optional exception that may contain additional information about the error, such as ContentTooLargeException.

Returns:

an AggregatedHttpResponse to send to the client, or null to let the next handler specified with orElse(ServerErrorHandler) handle the event.

renderStatus

@Nullable
default @Nullable AggregatedHttpResponse renderStatus(ServiceConfig config,
 @Nullable
 @Nullable RequestHeaders headers,
 HttpStatus status,
 @Nullable
 @Nullable String description,
 @Nullable
 @Nullable Throwable cause)

Returns an AggregatedHttpResponse generated from the given HttpStatus, message and Throwable. When null is returned, the next ServerErrorHandler in the invocation chain will be used as a fallback (See orElse(ServerErrorHandler) for more information).

Note: This method can be invoked by Armeria in combination with the other methods in ServerErrorHandler or even independently, and thus should not be used for counting HttpStatusExceptions or collecting stats. Use onServiceException(ServiceRequestContext, Throwable) and onProtocolViolation(ServiceConfig, RequestHeaders, HttpStatus, String, Throwable) instead.

Parameters:

config - the ServiceConfig that provides the configuration properties.

headers - the received RequestHeaders, or null in case of severe protocol violation.

status - the desired HttpStatus of the error response.

description - an optional human-readable description of the error.

cause - an optional exception that may contain additional information about the error, such as ContentTooLargeException.

Returns:

an AggregatedHttpResponse, or null to let the next handler specified with orElse(ServerErrorHandler) handle the event.

orElse

default ServerErrorHandler orElse(ServerErrorHandler other)

Returns a newly created ServerErrorHandler that tries this ServerErrorHandler first and then the specified ServerErrorHandler when the first call returns null.

 ServerErrorHandler handler = (ctx, cause) -> {
     if (cause instanceof FirstException) {
         return HttpResponse.of(200);
     }
     return null;
 }
 assert handler.onServiceException(ctx, new FirstException()) != null;
 assert handler.onServiceException(ctx, new SecondException()) == null;
 assert handler.onServiceException(ctx, new ThirdException()) == null;

 ServerErrorHandler combinedHandler = handler.orElse((ctx, cause) -> {
     if (cause instanceof SecondException) {
         return HttpResponse.of(200);
     }
     return null;
 });

 assert handler.onServiceException(ctx, new FirstException()) != null;
 assert handler.onServiceException(ctx, new SecondException()) != null;
 assert handler.onServiceException(ctx, new ThirdException()) == null;

 // The default handler never returns null.
 ServerErrorHandler nonNullHandler = combinedHandler.orElse(ServerErrorHandler.ofDefault());
 assert handler.onServiceException(ctx, new FirstException()) != null;
 assert handler.onServiceException(ctx, new SecondException()) != null;
 assert handler.onServiceException(ctx, new ThirdException()) != null;
 

asServiceErrorHandler

default ServiceErrorHandler asServiceErrorHandler()

Transforms this ServerErrorHandler into a ServiceErrorHandler.