Convertitori di messaggi HTTP con Spring Framework

1. Panoramica

Questo articolo descrive come configurare HttpMessageConverters in Spring .

In poche parole, possiamo usare convertitori di messaggi per eseguire il marshalling e l'unmarshall di oggetti Java da e verso JSON, XML, ecc. Su HTTP.

2. Le basi

2.1. Abilita Web MVC

Per cominciare, l'applicazione Web deve essere configurata con il supporto Spring MVC. Un modo comodo e molto personalizzabile per farlo è utilizzare l' annotazione @EnableWebMvc :

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

Si noti che questa classe implementa WebMvcConfigurer , che ci consentirà di modificare l'elenco predefinito di convertitori Http con il nostro.

2.2. I convertitori di messaggi predefiniti

Per impostazione predefinita, le istanze di HttpMessageConverter seguenti sono pre-abilitate:

  • ByteArrayHttpMessageConverter : converte matrici di byte
  • StringHttpMessageConverter : converte le stringhe
  • ResourceHttpMessageConverter : converte org.springframework.core.io.Resource per qualsiasi tipo di flusso di ottetti
  • SourceHttpMessageConverter : converte javax.xml.transform.Source
  • FormHttpMessageConverter : converte i dati del modulo in / da una MultiValueMap .
  • Jaxb2RootElementHttpMessageConverter - converte gli oggetti Java in / da XML (aggiunto solo se JAXB2 è presente sul classpath)
  • MappingJackson2HttpMessageConverter - converte JSON (aggiunto solo se Jackson 2 è presente sul classpath)

  • MappingJacksonHttpMessageConverter - converte JSON (aggiunto solo se Jackson è presente nel classpath)
  • AtomFeedHttpMessageConverter - converte i feed Atom (aggiunto solo se Rome è presente sul classpath)
  • RssChannelHttpMessageConverter - converte i feed RSS (aggiunto solo se Rome è presente sul classpath)

3. Comunicazione client-server - Solo JSON

3.1. Negoziazione di contenuti di alto livello

Ogni implementazione di HttpMessageConverter ha uno o più tipi MIME associati.

Quando riceve una nuova richiesta, Spring utilizzerà l' intestazione " Accetta " per determinare il tipo di supporto con cui deve rispondere .

Quindi proverà a trovare un convertitore registrato che sia in grado di gestire quel tipo di supporto specifico. Infine, lo utilizzerà per convertire l'entità e inviare la risposta.

Il processo è simile per ricevere una richiesta che contiene informazioni JSON. Il framework utilizzerà l' intestazione " Content-Type " per determinare il tipo di media del corpo della richiesta .

Quindi cercherà un HttpMessageConverter in grado di convertire il corpo inviato dal client in un oggetto Java.

Chiariamolo con un rapido esempio:

  • il client invia una richiesta GET a / foos con l' intestazione Accept impostata su application / json - per ottenere tutte le risorse Foo come JSON
  • il Foo Spring Controller viene colpito e restituisce le corrispondenti entità Foo Java
  • Spring utilizza quindi uno dei convertitori di messaggi Jackson per eseguire il marshalling delle entità in JSON

Diamo ora un'occhiata alle specifiche di come funziona e come possiamo sfruttare le annotazioni @ResponseBody e @ RequestBody .

3.2. @ResponseBody

@ResponseBody su un metodo Controller indica a Spring che il valore di ritorno del metodo viene serializzato direttamente nel corpo della risposta HTTP . Come discusso in precedenza, l' intestazione " Accept " specificata dal client verrà utilizzata per scegliere il convertitore Http appropriato per il marshalling dell'entità.

Diamo un'occhiata a un semplice esempio :

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

Ora, il client specificherà l'intestazione "Accept" per application / json nella richiesta - esempio di comando 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; }

E l'http Response Body:

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

3.3. @RequestBody

We can use the @RequestBody annotation on the argument of a Controller method to indicate that the body of the HTTP Request is deserialized to that particular Java entity. To determine the appropriate converter, Spring will use the “Content-Type” header from the client request.

Let's look at an example:

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

Next, let's consume this with a JSON object – we're specifying “Content-Type to be application/json:

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

We get back a 200 OK – a successful response:

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

4. Custom Converters Configuration

We can also customize the message converters by implementing the WebMvcConfigurer interface and overriding the configureMessageConverters method:

@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.

Come sempre, il codice presentato in questo articolo è disponibile su Github.