How can I wrap a JSON response in Spring

Question

Suppose I have two sets of controllers in Spring:

• /jsonapi1/*
• /jsonapi2/*

both of which return objects that are to be interpretted as JSON text.

I'd like some kind of filter to wrap the responses from one set of these controllers so that:

1. the original response is contained within another object.

   For example, if /jsonapi1/count returns:

   {"num_humans":123, "num_androids":456}
   

   then the response should be wrapped and returned as follows:

   { "status":0,
     "content":{"num_humans":123, "num_androids":456}
   }
   

2. if an exception happens in the controller, then filter should catch the exception and report it as follows

   { "status":5,
     "content":"Something terrible happened"
   }
   

3. The responses from the other controllers are returned unchanged.

We're currently customizing a MappingJackson2HttpMessageConverter passed to WebMvcConfigurerAdapter.configureMessageConverters in order to perform the above tasks. Works great except that it doesn't seem possible for this approach to be selective about the URLs (or controller classes) it applies to.

Is it possible to apply these kinds of wrappers to individual controller classes or URLs?

---

Update: Servlet filters look like a solution. Is it possible chose which filter gets applied to which controller methods, or which URLs?

Answer 1

I was struggling on this for multiple days. The solution by @Misha didn't work for me. I was able to finally get this working using ControllerAdvice and ResponseBodyAdvice.

ResponseBodyAdvice allows to inject custom transformation logic on the response returned by a controller but before it is converted to HttpResponse and committed.

This is how my controller method looks:

@RequestMapping("/global/hallOfFame")
    public List<HallOfFame> getAllHallOfFame() {
        return hallOfFameService.getAllHallOfFame();
}

Now i wanted to add some standard fields around the response like devmessage and usermessage. That logic goes into the ResponseAdvice:

@ControllerAdvice
public class TLResponseAdvice implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
            Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request,
        ServerHttpResponse response) {
        // TODO Auto-generated method stub
        final RestResponse<Object> output = new RestResponse<>();
        output.setData(body);
        output.setDevMessage("ResponseAdviceDevMessage");
        output.setHttpcode(200);
        output.setStatus("Success");
        output.setUserMessage("ResponseAdviceUserMessage");
        return output;
    }
}

The entity classes look like this:

@Setter // All lombok annotations
@Getter
@ToString
public class RestResponse<T> {

    private String status;
    private int httpcode;
    private String devMessage;
    private String userMessage;

    private T data;
}

@Entity
@Data // Lombok
public class HallOfFame {

    @Id
    private String id;
    private String name;
}

To handle exceptions, simply create another ControllerAdvice with ExceptionHandler. Use the example in this link.

Advantages of this solution:

1. It keeps your controllers clean. You can support any return type from your controller methods.
2. Your controller return type class does not need to extend some base class as required by the AOP approach.
3. You do not need to hack your way through Spring filters by using HttpServletResponseWrappers. They come up with a performance penalty.

EDIT - 17th September 2019

To handle exceptions use @ExceptionHandler. Refer code below.

@ExceptionHandler(Exception.class)
@ResponseBody
public MyResponseEntity<Object> handleControllerException(HttpServletRequest request, Throwable ex) {
    // default value
    int httpCode = HttpStatus.INTERNAL_SERVER_ERROR.value();

    if(ex instanceof ResourceNotFoundException) {
        httpCode = HttpStatus.NOT_FOUND.value();
    }
    ...
 }

Answer 2

The way I understand your question, you have exactly three choices.

Option #1

Manually wrap your objects in simple SuccessResponse, ErrorResponse, SomethingSortOfWrongResponse, etc. objects that have the fields you require. At this point, you have per-request flexibility, changing the fields on one of the response wrappers is trivial, and the only true drawback is code repetition if many of the controller's request methods can and should be grouped together.

Option #2

As you mentioned, and filter could be designed to do the dirty work, but be wary that Spring filters will NOT give you access to request or response data. Here's an example of what it might look like:

@Component
public class ResponseWrappingFilter extends GenericFilterBean {

    @Override
    public void doFilter(
        ServletRequest request,
        ServletResponse response,
        FilterChain chain) {

        // Perform the rest of the chain, populating the response.
        chain.doFilter(request, response);

        // No way to read the body from the response here. getBody() doesn't exist.
        response.setBody(new ResponseWrapper(response.getStatus(), response.getBody());
    }
} 

If you find a way to set the body in that filter, then yes, you could easily wrap it up. Otherwise, this option is a dead end.

Option #3

A-ha. So you got this far. Code duplication is not an option, but you insist on wrapping responses from your controller methods. I'd like to introduce the true solution - aspect-oriented programming (AOP), which Spring supports fondly.

If you're not familiar with AOP, the premise is as follows: you define an expression that matches (like a regular expression matches) points in the code. These points are called join points, while the expressions that match them are called pointcuts. You can then opt to execute additional, arbitrary code, called advice, when any pointcut or combination of pointcuts are matched. An object that defines pointcuts and advice is called an aspect.

It's great for expressing yourself more fluently in Java. The only drawback is weaker static type checking. Without further ado, here's your response-wrapping in aspect-oriented programming:

@Aspect
@Component
public class ResponseWrappingAspect {

    @Pointcut("within(@org.springframework.stereotype.Controller *)")
    public void anyControllerPointcut() {}

    @Pointcut("execution(* *(..))")
    public void anyMethodPointcut() {}

    @AfterReturning(
        value = "anyControllerPointcut() && anyMethodPointcut()",
        returning = "response")
    public Object wrapResponse(Object response) {

        // Do whatever logic needs to be done to wrap it correctly.
        return new ResponseWrapper(response);
    }

    @AfterThrowing(
        value = "anyControllerPointcut() && anyMethodPointcut()",
        throwing = "cause")
    public Object wrapException(Exception cause) {

        // Do whatever logic needs to be done to wrap it correctly.
        return new ErrorResponseWrapper(cause);
    }
}

The final result will be the non-repeating response wrapping that you seek. If you only want some or one controller receive this effect, then update the pointcut to match methods only within instances of that controller (rather than any class holding the @Controller annotation).

You'll need to include some AOP dependencies, add the AOP-enabling annotation in a configuration class, and make sure something component-scans the package this class is in.

Answer 3

Simplest way i manage custom responses from controllers is by utilising the Map variable.

so your code ends up looking like:

public @ResponseBody Map controllerName(...) {

Map mapA = new HashMap();

mapA.put("status", "5");
mapA.put("content", "something went south");

return mapA;

}

beauty of is is that you can configure it any thousand ways. Currently i use for object transmition, custom exception handling and data reporting, too easy.

Hope this helps