Iniezione dei Parametri in JAX-RS

Nell’articolo Primi Passi con JAX-RS abbiamo mostrato come creare una applicazione JAX-RS di base utilizzabile sia in modalità standalone che come web application. Inoltre è stato mostrato un primo semplice esempio di servizio REST ed un client per invocarlo. Nel presente articolo approfondiamo i diversi aspetti del framework.

Per testare il codice riportato nell’articolo si consiglia l’utilizzo dell’estensione chrome Advanced Rest Client.

URI Matching

Il binding di una URI con la specifica risorsa avviene attraverso l’utilizzo dell’annotazione @Path. Ogni classe POJO  annotata con @Path è automaticamente riconosciuta come root resource class. I metodi della classe per essere riconosciuti come servizi REST devono a loro volta essere annotati con una delle annotazioni identificative dei metodi HTTP, e opzionalmente essere annotati con @Path e quindi diventare delle sotto-risorse.

Per default con Jersey il life-cycle di una root resource è per-request, ovvero la classe associata è istanziata ogni volta che l’url richiesto corrisponde a quello risorsa. Questo se da un lato semplifica la programmazione non dovendo gestire situazioni di accesso concorrente, dall’altro sono la principale causa di carenza nelle performace. Per modificare il comportamento di default è possibile utilizzare una delle seguenti annotazioni:

@RequestScoped  Comportamento di default applicato anche in assenza di annotazioni. La risorsa è istanziata ad ogni nuova richiesta e se utilizzata più volte nella stessa richiesta non viene istanziata di nuovo.
 @PerLookup  In questo caso la risorsa è generata di nuovo ad ogni utilizzo anche se all’interno della stessa request.
 @Singleton  La risorsa è unica per applicazione.

Iniezione dei Parametri

Nel post Post to Post Links II error: No post found with slug "primi-passi-con-jax-rs-parte-1" abbiamo visto un esempio molto semplice di passaggio di parametri al servizio REST attraverso l’estrazione porzioni di stringa dall’URI legato alla risorsa. Riepiloghiamo in questa sezione i vari modi in cui JAX-RS consente il passaggio dei parametri dal client al server.

@PathParam

Abbiamo già visto come l’annotazione consente di iniettare il valore estratto dall’URI in un parametro di un risorse method. La stessa annotazione è però utilizzabile anche per:

  • iniettare il valore in una variabile di istanza della classe:
  • iniettare il valore come parametro del costruttore della classe:

Tali opportunità non sono ovviamente utilizzabili nel caso in cui la root resource class sia definita come singleton.

Ovviamente la stessa tecnica è utilizzabile per l’iniezione di parametri multipli, come nel seguente esempio.

@QueryParam

Attraverso tale annotazione è possibile iniettare i valori estratti dalla parte di URI che corrisponde alle query string. Ad esempio la string JavaBoss nell’url https://www.google.it?q=JavaBoss. Come nel caso precedente, anche questa annotazione è utilizzabile sia a livello di metodo che a livello di variabile di istanza della classe o di un suo costruttore.

L’esempio seguente è attivato eseguendo la GET sull’urlo http://localhost:8080/myapp/parameter?from=1&to=10.

Nel caso in cui i parametri nella query string siano opzionali è possibile utilizzare l’annotazione @DefaulValue nel modo seguente:

Rendendo di fatto il metodo attivabile anche per l’url http://localhost:8080/myapp/parameter?to=10.

@Context

Tale annotazione è utilizzabile per ottenere informazioni di contesto relative ad una request o response corrente. In particolare è possibile iniettare la classe UriInfo che consente la manipolazione dell’URI associata alla request e quindi l’estrazione delle query string come nell’esempio seguente:

@MatrixParam

Oltre all’utilizzo delle query string, un altro modo per inviare parametri attraverso una URI sono i matrix parameter. SI tratta sostanzialmente di porzioni di URI del tipo “;name1=value1;name2=value2″ presente in una qualsiasi posizione. Un esempio di URI con matrix parameter è: http://example.com/apples;order=random;color=blue/2006/archive?year=2016.

Il seguente resource method estrae i parametri autore e country da un URI del tipo http://localhost:8080/myapp/parameter;author=JavaBoss;country=Italy.

@FormParam

JAX-RS consente di iniettare parametri in un resource method estraendoli da un form attraverso l’utilizzo di tale annotazione. Ad esempio il metodo:

può essere invocato utilizzando una form del tipo:

Manipolazione dell’Header

JAX-RS consente di accedere agli header parameter della request attraverso due possibili modalità. La prima prevede l’utilizzo dell’annotazione @HeaderParam e la specifica del parametro richiesto. Un elenco degli header param standard è presente in questa pagina wiki. Ovviamente l’utente può utilizzare il proprio header parameter custom.

Una seconda modalità consiste nell’utilizzare l’annotazione @Context per recuperare l’oggetto HttpHeaders attraverso il quale recuperare i parametri richiesti.

Download Codice Sorgente

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