Convertisseurs de messages HTTP avec Spring Framework

1. Vue d'ensemble

Cet article décrit comment configurer HttpMessageConverters au printemps .

En termes simples, nous pouvons utiliser des convertisseurs de messages pour marshall et unmarshall Java Objects vers et depuis JSON, XML, etc. via HTTP.

2. Les bases

2.1. Activer Web MVC

Pour commencer, l'application Web doit être configurée avec la prise en charge de Spring MVC. Un moyen pratique et très personnalisable de le faire est d'utiliser l' annotation @EnableWebMvc :

@EnableWebMvc @Configuration @ComponentScan({ "com.baeldung.web" }) public class WebConfig implements WebMvcConfigurer { ... }

Notez que cette classe implémente WebMvcConfigurer - ce qui nous permettra de changer la liste par défaut des convertisseurs Http avec la nôtre.

2.2. Les convertisseurs de messages par défaut

Par défaut, les instances HttpMessageConverter suivantes sont pré-activées:

  • ByteArrayHttpMessageConverter - convertit les tableaux d'octets
  • StringHttpMessageConverter - convertit les chaînes
  • ResourceHttpMessageConverter - convertit org.springframework.core.io.Resource pour tout type de flux d'octets
  • SourceHttpMessageConverter - convertit javax.xml.transform.Source
  • FormHttpMessageConverter - convertit les données du formulaire vers / depuis un MultiValueMap .
  • Jaxb2RootElementHttpMessageConverter - convertit les objets Java vers / depuis XML (ajouté uniquement si JAXB2 est présent sur le chemin de classe)
  • MappingJackson2HttpMessageConverter - convertit JSON (ajouté uniquement si Jackson 2 est présent sur le chemin de classe )

  • MappingJacksonHttpMessageConverter - convertit JSON (ajouté uniquement si Jackson est présent sur le chemin de classe )
  • AtomFeedHttpMessageConverter - convertit les flux Atom (ajouté uniquement si Rome est présent sur le chemin de classe )
  • RssChannelHttpMessageConverter - convertit les flux RSS (ajouté uniquement si Rome est présent sur le chemin de classe )

3. Communication client-serveur - JSON uniquement

3.1. Négociation de contenu de haut niveau

Chaque implémentation HttpMessageConverter a un ou plusieurs types MIME associés.

Lors de la réception d'une nouvelle demande, Spring utilisera l'en- tête « Accept » pour déterminer le type de média avec lequel il doit répondre .

Il essaiera ensuite de trouver un convertisseur enregistré capable de gérer ce type de support spécifique. Enfin, il l'utilisera pour convertir l'entité et renvoyer la réponse.

Le processus est similaire pour recevoir une requête contenant des informations JSON. Le framework utilisera l'en - tête « Content-Type » pour déterminer le type de support du corps de la requête .

Il recherchera ensuite un HttpMessageConverter capable de convertir le corps envoyé par le client en objet Java.

Clarifions cela avec un exemple rapide:

  • le client envoie une requête GET à / foos avec l'en- tête Accept défini sur application / json - pour obtenir toutes les ressources Foo au format JSON
  • le contrôleur Foo Spring est touché et renvoie les entités Java Foo correspondantes
  • Spring utilise ensuite l'un des convertisseurs de message Jackson pour rassembler les entités en JSON

Regardons maintenant les détails de son fonctionnement - et comment nous pouvons tirer parti des annotations @ResponseBody et @ RequestBody .

3.2. @ResponseBody

@ResponseBody sur une méthode Controller indique à Spring que la valeur de retour de la méthode est sérialisée directement dans le corps de la réponse HTTP . Comme indiqué ci-dessus, l'en- tête « Accept » spécifié par le client sera utilisé pour choisir le convertisseur HTTP approprié pour rassembler l'entité.

Regardons un exemple simple :

@GetMapping("/{id}") public @ResponseBody Foo findById(@PathVariable long id) { return fooService.findById(id); }

Maintenant, le client spécifiera l'en-tête «Accept» à application / json dans la requête - exemple de commande curl :

curl --header "Accept: application/json" //localhost:8080/spring-boot-rest/foos/1

La classe Foo :

public class Foo { private long id; private String name; }

Et le corps de réponse Http:

{ "id": 1, "name": "Paul", }

3.3. @RequestBody

Nous pouvons utiliser l' annotation @RequestBody sur l'argument d'une méthode Controller pour indiquer que le corps de la requête HTTP est désérialisé vers cette entité Java particulière . Pour déterminer le convertisseur approprié, Spring utilisera l'en-tête «Content-Type» de la demande du client.

Regardons un exemple:

@PutMapping("/{id}") public @ResponseBody void update(@RequestBody Foo foo, @PathVariable String id) { fooService.update(foo); }

Ensuite, consommons ceci avec un objet JSON - nous spécifions "Content-Type " pour être application / json :

curl -i -X PUT -H "Content-Type: application/json" -d '{"id":"83","name":"klik"}' //localhost:8080/spring-boot-rest/foos/1

Nous obtenons un 200 OK - une réponse réussie:

HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Length: 0 Date: Fri, 10 Jan 2014 11:18:54 GMT

4. Configuration des convertisseurs personnalisés

Nous pouvons également personnaliser les convertisseurs de messages en implémentant l' interface WebMvcConfigurer et en remplaçant la méthode configureMessageConverters :

@EnableWebMvc @Configuration @ComponentScan({ "com.baeldung.web" }) public class WebConfig implements WebMvcConfigurer { @Override public void configureMessageConverters( List
    
      converters) { messageConverters.add(createXmlHttpMessageConverter()); messageConverters.add(new MappingJackson2HttpMessageConverter()); } private HttpMessageConverter createXmlHttpMessageConverter() { MarshallingHttpMessageConverter xmlConverter = new MarshallingHttpMessageConverter(); XStreamMarshaller xstreamMarshaller = new XStreamMarshaller(); xmlConverter.setMarshaller(xstreamMarshaller); xmlConverter.setUnmarshaller(xstreamMarshaller); return xmlConverter; } }
    

In this example, we're creating a new converter – the MarshallingHttpMessageConverter – and using the Spring XStream support to configure it. This allows a great deal of flexibility since we're working with the low-level APIs of the underlying marshalling framework – in this case XStream – and we can configure that however we want.

Note that this example requires adding the XStream library to the classpath.

Also be aware that by extending this support class, we're losing the default message converters which were previously pre-registered.

We can of course now do the same for Jackson – by defining our own MappingJackson2HttpMessageConverter. We can now set a custom ObjectMapper on this converter and have it configured as we need to.

In this case, XStream was the selected marshaller/unmarshaller implementation, but others like CastorMarshaller can be used as well.

At this point – with XML enabled on the back end – we can consume the API with XML Representations:

curl --header "Accept: application/xml" //localhost:8080/spring-boot-rest/foos/1

4.1. Spring Boot Support

If we're using Spring Boot we can avoid implementing the WebMvcConfigurer and adding all the Message Converters manually as we did above.

We can just define different HttpMessageConverter beans in the context, and Spring Boot will add them automatically to the autoconfiguration that it creates:

@Bean public HttpMessageConverter createXmlHttpMessageConverter() { MarshallingHttpMessageConverter xmlConverter = new MarshallingHttpMessageConverter(); // ... return xmlConverter; }

5. Using Spring’s RestTemplate With Http Message Converters

As well as with the server side, Http Message Conversion can be configured in the client side on the Spring RestTemplate.

We're going to configure the template with the “Accept” and “Content-Type” headers when appropriate. Then we'll try to consume the REST API with full marshalling and unmarshalling of the Foo Resource – both with JSON and with XML.

5.1. Retrieving the Resource With No Accept Header

@Test public void testGetFoo() { String URI = “//localhost:8080/spring-boot-rest/foos/{id}"; RestTemplate restTemplate = new RestTemplate(); Foo foo = restTemplate.getForObject(URI, Foo.class, "1"); Assert.assertEquals(new Integer(1), foo.getId()); }

5.2. Retrieving a Resource With application/xml Accept Header

Let's now explicitly retrieve the Resource as an XML Representation. We're going to define a set of Converters and set these on the RestTemplate.

Because we're consuming XML, we're going to use the same XStream marshaller as before:

@Test public void givenConsumingXml_whenReadingTheFoo_thenCorrect() { String URI = BASE_URI + "foos/{id}"; RestTemplate restTemplate = new RestTemplate(); restTemplate.setMessageConverters(getMessageConverters()); HttpHeaders headers = new HttpHeaders(); headers.setAccept(Arrays.asList(MediaType.APPLICATION_XML)); HttpEntity entity = new HttpEntity(headers); ResponseEntity response = restTemplate.exchange(URI, HttpMethod.GET, entity, Foo.class, "1"); Foo resource = response.getBody(); assertThat(resource, notNullValue()); } private List
    
      getMessageConverters() { XStreamMarshaller marshaller = new XStreamMarshaller(); MarshallingHttpMessageConverter marshallingConverter = new MarshallingHttpMessageConverter(marshaller); List
     
       converters = ArrayList
      
       (); converters.add(marshallingConverter); return converters; }
      
     
    

5.3. Retrieving a Resource With application/json Accept Header

Similarly, let's now consume the REST API by asking for JSON:

@Test public void givenConsumingJson_whenReadingTheFoo_thenCorrect() { String URI = BASE_URI + "foos/{id}"; RestTemplate restTemplate = new RestTemplate(); restTemplate.setMessageConverters(getMessageConverters()); HttpHeaders headers = new HttpHeaders(); headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON)); HttpEntity entity = new HttpEntity(headers); ResponseEntity response = restTemplate.exchange(URI, HttpMethod.GET, entity, Foo.class, "1"); Foo resource = response.getBody(); assertThat(resource, notNullValue()); } private List
    
      getMessageConverters() { List
     
       converters = new ArrayList
      
       (); converters.add(new MappingJackson2HttpMessageConverter()); return converters; }
      
     
    

5.4. Update a Resource With XML Content-Type

Finally, let's also send JSON data to the REST API and specify the media type of that data via the Content-Type header:

@Test public void givenConsumingXml_whenWritingTheFoo_thenCorrect() { String URI = BASE_URI + "foos/{id}"; RestTemplate restTemplate = new RestTemplate(); restTemplate.setMessageConverters(getMessageConverters()); Foo resource = new Foo(4, "jason"); HttpHeaders headers = new HttpHeaders(); headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON)); headers.setContentType((MediaType.APPLICATION_XML)); HttpEntity entity = new HttpEntity(resource, headers); ResponseEntity response = restTemplate.exchange( URI, HttpMethod.PUT, entity, Foo.class, resource.getId()); Foo fooResponse = response.getBody(); Assert.assertEquals(resource.getId(), fooResponse.getId()); }

What's interesting here is that we're able to mix the media types – we're sending XML data but we're waiting for JSON data back from the server. This shows just how powerful the Spring conversion mechanism really is.

6. Conclusion

In this tutorial, we looked at how Spring MVC allows us to specify and fully customize Http Message Converters to automatically marshall/unmarshall Java Entities to and from XML or JSON. This is, of course, a simplistic definition, and there is so much more that the message conversion mechanism can do – as we can see from the last test example.

We have also looked at how to leverage the same powerful mechanism with the RestTemplate client – leading to a fully type-safe way of consuming the API.

Comme toujours, le code présenté dans cet article est disponible à l'adresse over sur Github.