Gestione Tipi non Primitivi in JAX-RS

Terminiamo la serie di articoli su JAX-RS iniziata con i post Primi Passi con JAX-RS e Iniezione dei Parametri in JAX-RS approfondendo alcune caratteristiche avanzate del framework.

Request e Response XML

Tutti i servizi REST di esempio che sono stati presentati negli articoli precedenti accettavano come parametri formali dei tipi primitivi ed analogamente restituivano sempre un tipo primitivo. Vediamo ora come utilizzare il framework per la gestione di oggetti complessi. Innanzitutto deve essere scelto il modo in cui l’oggetto deve essere serializzato al fine di essere trasferito dal client al server e viceversa. Una possibilità è quella di utilizzare l’XML e per farlo avremo bisogno di utilizzare la specifica JAXB (Java Architecture for XML Binding).

Procediamo quindi definendo la classe Message come segue:

ed la root resource class MessageService:

La prima differenza rispetto agli esempi precedenti è la presenza dell’annotazione @Produces che è utilizzata per indicare il MIME type del tipo restituito dal servizio. Il valore di default è “text/plain” quindi testo “semplice”; nel nostro caso però deve essere “application/xml“. Jersey fornisce la classe di utilità MediaType in cui sono codificati tutti i possibili MIME type.

Se proviamo ad avviare il servizio ed accediamo all’url http://localhost:8080/myapp/messages noteremo sul log l’errore: MessageBodyWriter not found for media type=application/xml, che indica che JAX-RS non trova il convertitore adatto per il tipo MIME specificato. Come anticipato precedentemente abbiamo bisogno di utilizzare JAXB per eseguire la serializzazione, che fortunatamente è già inserito in Jersey. Per attivarlo dobbiamo semplicemente annotare la classe Message con @XmlRootElement:

Eseguito nuovamente il test si otterrà:

Implementiamo ora il resource method che consente di inserire un nuovo messaggio. In questo caso per coerenza utilizzeremo il metodo HTTP POST e l’annotation @Consumes per indicare il MIME type di dell’oggetto passato al metodo come parametro formale:

Se utilizzate ARC di chrome per eseguire il test assicuratevi di specificare “application/xml” come content type ed inserire l’XML del messaggio nel modo mostrato nell’immagine seguente.

ARC post message

Status Code Created

Analizzando meglio il servizio addMessage ci rendiamo conto che lo status code restituito, in assenza di errori, è il 200. Il protocollo HTTP prevede però uno specifico status code 201 per la creazione di nuove risorse. Inoltre l’URI della risorsa dovrebbe essere inserito nell’header della response alla proprietà Location. Vediamo come farlo nella seguente versione del metodo:

Utilizzando l’oggetto Response, che implementa il pattern builder, è possibile inserire lo status code Status.CREATED ovvero 201 e l’header Location. L’URI corrispondente alla risorsa creata è invece ottenuta a partire dall’oggetto UriInfo, iniettato nel metodo attraverso l’annotazione @Context, il quale implementa un UriBuilder che è utilizzato per apporre al path assoluto della risorsa corrente, l’id del messaggio creato. L’URI così generato sarà quindi sarà del tipo http://localhost:8080/myapp/messages/102.

Si noti che l’oggetto Response fornisce un metodo di utilità che consente di realizzare quanto detto in modo compatto:

Request e Response JSON

Nello stesso modo è possibile utilizzare JSON come tecnologia di serializzazione degli oggetti trasferiti tra server e client. Per farlo è sufficiente specificare il media type “application/json” e inserire nel pom la dipendenza al modulo Jersey MOXy. Se avete generato il progetto con maven sarà sufficiente decommentarlo:

L’output ottenuto invocando il GET sulla risorsa /messages sarà quindi:

Download di File

Vediamo ora come sia possibile implementare un servizio REST in modo che restituisca al client un file quando invocato. Per farlo è necessario:

  1. Configurare opportunamente il MIME type attraverso l’annotazione @Produces in funzione del tipo di file restituito;
  2. Configurare nell’header della  response la proprietà Content-Disposition in modo da indicare il nome del file ed istruire il browser ad aprire la pop up di download.

Nel caso di file di testo il metodo apparirà quindi come segue:

Per altre tipologie di file i MIME type da utilizzare sono:

Immagini image/png
PDF application/pdf
Excel application/vnd.ms-excel

Upload di File

Per eseguire l’upload di un file verso un servizio REST il MIME type definito nell’annotazione @Consumes del servizio deve essere “multipart/form-data“. Nel progetto va anche inserita la dependency Jersey per la gestione di tali tipologie di formati:

Il metodo di upload sara quindi così definito:

Download Codice Sorgente

Il progetto completo degli esempi riportati nell’articolo è disponibile qui restful-ws.

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.

As you found this post useful...

Follow us on social media!