What is the restTemplate.exchange() method for?

Question

Actually what does the restTemplate.exchange() method do?

@RequestMapping(value = "/getphoto", method = RequestMethod.GET)
public void getPhoto(@RequestParam("id") Long id, HttpServletResponse response) {

    logger.debug("Retrieve photo with id: " + id);

    // Prepare acceptable media type
    List<MediaType> acceptableMediaTypes = new ArrayList<MediaType>();
    acceptableMediaTypes.add(MediaType.IMAGE_JPEG);

    // Prepare header
    HttpHeaders headers = new HttpHeaders();
    headers.setAccept(acceptableMediaTypes);
    HttpEntity<String> entity = new HttpEntity<String>(headers);

    // Send the request as GET
    ResponseEntity<byte[]> result = 
        restTemplate.exchange("http://localhost:7070/spring-rest-provider/krams/person/{id}", 
                              HttpMethod.GET, entity, byte[].class, id);

    // Display the image
    Writer.write(response, result.getBody());
}

score 27 · Answer 1 · edited Oct 07 '21 at 07:34

27

The method documentation is pretty straightforward:

Execute the HTTP method to the given URI template, writing the given request entity to the request, and returns the response as ResponseEntity.

URI Template variables are expanded using the given URI variables, if any.

Consider the following code extracted from your own question:

ResponseEntity<byte[]> result = 
    restTemplate.exchange("http://localhost:7070/spring-rest-provider/krams/person/{id}", 
                          HttpMethod.GET, entity, byte[].class, id);

We have the following:

A GET request will be performed to the given URL sending the HTTP headers that are wrapped in the HttpEntity instance.
The given URL contains a template variable ({id}). It will be replaced with the value given in the last method parameter (id).
The response entity will be returned as a byte[] wrapped into a ResponseEntity instance.

edited Oct 07 '21 at 07:34

Community

1
1

answered Feb 16 '17 at 10:55

cassiomolin

124,154
35
280
359

1

Is this method synchronous or asynchronous? Based on the description, it is synchronous. I was wondering how does it handle requests that return a Future from a server. – animageofmine May 22 '18 at 13:59
2

`RestTemplate` is synchronous. See the [documentation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html). – cassiomolin May 22 '18 at 14:03
2

Your explanation was quite helpful. But OP is right, the original text is essentially circular reasoning. It is only understandable by people who already understand it. I ended up here because I'm trying to port a script that uses exchange(), and that documentation is hopeless. – Jason Oct 17 '19 at 22:58

score 15 · Answer 2 · edited Oct 07 '21 at 08:14

TL;DR: Q: What is a request-response pair called? A: An "exchange".

The term exchange is used, almost incidentally, in the official technical documentation of HTTP to refer to an HTTP request combined with the corresponding response.

However looking at the answers to the following questions, it is clear that while this may have represented a de facto standard for some people, many other were not aware of it, or hadn't adopted it.

The documentation doesn't bother to mention the etymology of the name -- probably assuming that it's obvious.

Notice, however, that there are many different RestTemplate HTTP request methods listed and only a small fraction of them are named exchange. The list is primarily made up of HTTP method-specific names such as delete, put, getForEntity, postForObject, et cetera. Technically speaking, all of these methods perform exchanges in the same sense, but the more focused convenience methods are limited to a specific subset of the possible exchange functionality and parameter+return types.

To put it simply, the set of exchange functions are the most general/capable methods provided by RestTemplate, so you can use exchange when none of the other methods provides a complete enough parameter set to meet your needs.

For example:

Sending GET request with Authentication headers using restTemplate, in which the OP has noticed that "...the only way to send Headers such as accept and Authorization is by using the exchange method..."

score 4 · Answer 3 · answered Dec 17 '18 at 08:36

The more generic exchange API requires a HttpMethod parameter and a request object for completeness. Compare:

ResponseEntity<Foo> response = 
restTemplate.exchange(url, HttpMethod.GET, request, Foo.class);

ResponseEntity<Foo> response = 
restTemplate.getForEntity(url, Foo.class);

score 1 · Answer 4 · answered Jul 14 '14 at 17:16

1

The exchange method executes the HTTP method against the specified URI template, passing in the parameters for replacement. In this case it gets an image for a person entity for its Id parameter and returns the byte array for it.

answered Jul 14 '14 at 17:16

Matt T.

539
3
6

What is the restTemplate.exchange() method for?

4 Answers4

Linked