YAML configuration

The escalations block sits under the step that throws the exception. Each entry maps the fully-qualified exception class name to the name of the handler step to invoke.

service:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.MethodService
  escalations:
    net.officefloor.tutorial.springrestexceptionhttpserver.MockException: handler

handler:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.MethodExceptionHandler

When service throws MockException, OfficeFloor routes execution to the handler step rather than letting the exception propagate further.

Service method

The service method simply declares and throws the exception:

public class MethodService {
    public void service() throws MockException {
        throw new MockException("thrown");
    }
}

Handler method

The handler receives the thrown exception via the @Parameter annotation, which binds the escalation object as a method parameter. From there it can inspect the exception and write a response using ObjectResponse:

public class MethodExceptionHandler {
    public void handle(@Parameter MockException ex, ObjectResponse<String> response) {
        response.send("Method handled: " + ex.getMessage());
    }
}

The @Parameter annotation is provided by OfficeFloor and signals that the parameter value is passed from the previous step's output — in the escalation case this is the thrown exception.

YAML configuration

The composition block at the top of the YAML file holds the shared escalation mappings:

composition:
  escalations:
    net.officefloor.tutorial.springrestexceptionhttpserver.MockException: handler

service:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.CompositionService

handler:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.CompositionExceptionHandler

Any step in the composition that throws MockException — whether it is service or any other step added later — is automatically routed to the handler step.

Service and handler methods

The service class is identical in structure to the method-escalation example:

public class CompositionService {
    public void service() throws MockException {
        throw new MockException("thrown");
    }
}

The handler class is also the same pattern, just producing a different response to illustrate which level caught the exception:

public class CompositionExceptionHandler {
    public void handle(@Parameter MockException ex, ObjectResponse<String> response) {
        response.send("Composition handled: " + ex.getMessage());
    }
}

The key difference from method escalation is entirely in the YAML — the Java classes are written the same way regardless of which level handles the escalation.

File naming

Create one YAML file per exception type inside officefloor/escalation/. The file name must be the fully qualified class name of the exception, with a .yml extension:

officefloor/escalation/
  net.officefloor.tutorial.springrestexceptionhttpserver.EscalationException.yml
  net.officefloor.tutorial.springrestexceptionhttpserver.EscalationNotFoundException.yml

OfficeFloor discovers all files in that directory on startup and registers each one as a global escalation handler. When the same handler class provides methods for multiple exception types, the method property identifies which method handles each file's exception.

Exception types

This tutorial defines two exception types handled globally:

public class EscalationException extends Exception {

    public EscalationException(String message) {
        super(message);
    }
}

public class EscalationNotFoundException extends Exception {

    public EscalationNotFoundException(String message) {
        super(message);
    }
}

YAML configuration — one file per exception type

Each escalation YAML file names the handler class and the specific method to call via the method property:

File: officefloor/escalation/net.officefloor.tutorial.springrestexceptionhttpserver.EscalationException.yml

handle:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.GlobalExceptionHandler
  method: handleBadRequest

File: officefloor/escalation/net.officefloor.tutorial.springrestexceptionhttpserver.EscalationNotFoundException.yml

handle:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.GlobalExceptionHandler
  method: handleNotFound

The REST endpoint YAMLs require no escalation configuration — the global handlers wire automatically:

service:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.EscalationService

service:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.EscalationNotFoundService

Service methods

The services simply throw their respective exceptions:

public class EscalationService {
    public void service() throws EscalationException {
        throw new EscalationException("thrown");
    }
}

public class EscalationNotFoundService {
    public void service() throws EscalationNotFoundException {
        throw new EscalationNotFoundException("entity not found");
    }
}

Handler class

One handler class provides a dedicated method for each exception type. Each method receives its exception via @Parameter and returns a ResponseEntity carrying the HTTP status code and a ProblemDetail body:

public class GlobalExceptionHandler {

    public void handleBadRequest(
            @Parameter EscalationException ex,
            ObjectResponse<ResponseEntity<ProblemDetail>> response) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setDetail(ex.getMessage());
        response.send(ResponseEntity.badRequest().body(pd));
    }

    public void handleNotFound(
            @Parameter EscalationNotFoundException ex,
            ObjectResponse<ResponseEntity<ProblemDetail>> response) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        pd.setDetail(ex.getMessage());
        response.send(ResponseEntity.status(HttpStatus.NOT_FOUND).body(pd));
    }
}

Priority: method escalation takes precedence over composition escalation, which in turn takes precedence over global escalation. An endpoint can always override the global handler by declaring its own escalation in the YAML.

YAML configuration

The YAML for this endpoint needs no escalation configuration at all:

service:
  class: net.officefloor.tutorial.springrestexceptionhttpserver.SpringAdviceService

Service method

The service method throws the exception in the same way as before:

public class SpringAdviceService {
    public void service() throws MockException {
        throw new MockException("thrown");
    }
}

ExceptionControllerAdvice

The @RestControllerAdvice class provides the @ExceptionHandler method. Spring resolves the HTTP response status via @ResponseStatus:

@RestControllerAdvice
public class ExceptionControllerAdvice {

    @ExceptionHandler(MockException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String handleMockException(MockException ex) {
        return "Spring handled: " + ex.getMessage();
    }
}

Because this is a standard Spring mechanism, all the usual Spring features apply — returning ResponseEntity, reading the HttpServletRequest, accessing Spring beans, and so on.

Note: @RestControllerAdvice exception handling works in both MockMvc tests and in a real deployed server. No special configuration is required.