Improve Javadoc of RestOperations#exchange for responses without a body

[metacubed]

Affects: spring-web:5.3.4

---

The various RestTemplate.exchange() methods do not mark the parameter Class<T> responseType as @Nullable. For example:
https://github.com/spring-projects/spring-framework/blob/v5.3.4/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java#L597

public <T> ResponseEntity<T> exchange(String url, HttpMethod method,
    @Nullable HttpEntity<?> requestEntity, /* >HERE< */ Class<T> responseType, Object... uriVariables)
    throws RestClientException {

        RequestCallback requestCallback = httpEntityCallback(requestEntity, responseType);
        ResponseExtractor<ResponseEntity<T>> responseExtractor = responseEntityExtractor(responseType);
        return nonNull(execute(url, method, requestCallback, responseExtractor, uriVariables));
}

This causes code analysis warnings for methods which do not return a response, such as DELETE, forcing developers to use Void.TYPE as the responseType instead of null.

---

The usages of that parameter explicitly expect null values as valid cases. For example:

In the HttpEntityRequestCallback class,

public HttpEntityRequestCallback(@Nullable Object requestBody, @Nullable Type responseType) {
    // ...
}

In the ResponseEntityResponseExtractor class,

public ResponseEntityResponseExtractor(@Nullable Type responseType) {
    if (responseType != null && Void.class != responseType) {
        this.delegate = new HttpMessageConverterExtractor<>(responseType, getMessageConverters(), logger);
    }
    else {
        this.delegate = null;
    }
}

[rstoyanchev]

Void.TYPE is actually more explicit and preferred. It ties into the method level generic type on RestOperations so we'd rather keep it the way it is and it doesn't seem that much more trouble vs null.

[metacubed]

I'm ok with that, @rstoyanchev. Do you think it's worth documenting the recommendation to use Void.TYPE for no-response scenarios?

[rstoyanchev]

Sure, I can add a mention in the Javadoc.