Realizzare un servizio REST con JAX-RS 2.0 e Jersey 2.0

DOMANDA:

Come realizzo un servizio REST 2.0 e un client per testarlo?

RISPOSTA:

Per addentrarsi nel mondo REST consiglio di leggere il post REST 2.0: Definizione e configurazione con il framework Jersey. Il post spiega brevemente i concetti REST e cosa occorre per configurare un ambiente che lo utilizzi. La lettura servirà anche per conoscere quali sono i jar da includere nei progetti che stiamo per realizzare.

In questo post creeremo un Servizio REST che risponderà, con un semplice "echo", alle richieste di un Client.

Partiamo con la programmazione del Servizio.

Creiamo un nuovo Dynamic Web Project in Eclipse denominato RESTfulService e ricordiamoci di selezionare, nell'ultimo step del wizard, di creazione la checkbox "Generate web.xml deployment descriptor". 

Questa opzione ci permetterà di avere a disposizione un web.xml di base creato da Eclipse da modificare secondo le nostre preferenze (ovviamente non è un passo obbligatorio, ma di sicuro ci permette di risparmiare tempo e fatica).

Dividiamo la costruzione del servizio in due parti:

1. Configurazione
2. Creazione del servizio di Echo

1 - Configurazione.

Per prima cosa dobbiamo personalizzare il web.xml appena creato da Eclipse in questo modo:

<web-app version="3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemalocation="http://java.sun.com/xml/ns/javaee
 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <servlet>
  <servlet-name>JerseyWeb</servlet-name>
  <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
  <init-param>
   <param-name>javax.ws.rs.Application</param-name>
   <param-value>echo.application.EchoApplication</param-value>
  </init-param>
  <init-param>
   <param-name>jersey.config.xml.security.disable</param-name>
   <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
 </servlet>

 <servlet-mapping>
  <servlet-name>JerseyWeb</servlet-name>
  <url-pattern>/*</url-pattern>
 </servlet-mapping>
  
 </web-app>

Creiamo ora la classe echo.application.EchoApplication referenziata nella riga in evidenza del web.xml.

La classe EchoApplication (necessaria per configurare il gestore della nostra architettura REST).

package echo.application;

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.core.Application;

import echo.resource.EchoResource;

public class EchoApplication extends Application {

     @Override
     public Set<Class<?>> getClasses() {
         Set<Class<?>> classes = new HashSet<Class<?>>();
         classes.add(EchoResource.class);
         return classes;
     }
}

2 - Servizio REST: echo.resource.EchoResource.

package echo.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

@Path("/echo")
public class EchoResource {
  @GET
  @Produces("text/plain")
  public String echo(@QueryParam("echo_msg") String echoString) {
    return echoString;
  }   
}

Come potete notare, la classe EchoResource fa un forte uso delle Annotation. Vediamole nel dettaglio:

• @Path definisce l'endpoint della nostra risorsa (o servizio). Questo url insieme al context path della nostra web application forma l'endpoint completo (nel nostro esempio http://localhost:8080/RESTfulService/echo). Grazie a questo endpoint, il servizio sarà invocabile a quell'indirizzo dal client.
• @GET indica quale metodo del protocollo HTTP sarà utilizzato per invocare il metodo echo
• @Produces indica il content-type della risposta (da notare la s della terza persona del verbo to produce)
• @QueryParam indica semplicemente che l'attributo echoString deve essere mappato sul parametro in query string "echo_msg"

Realizzazione del Client

Creiamo un semplice Java Project da Eclipse. Questo progetto conterrà il client del nostro servizio e sarà una Java Application standard.

Di seguito il codice del client REST EchoClient che invia la stringa di cui il servizio fornirà l'echo in risposta:

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;

public class EchoClient {
 
  public static void main(String [] args){
    // Recupero instance di Client
    Client client = ClientBuilder.newClient();
  
    // Creo un WebTarget con l'endpoint del servizio REST 
    WebTarget target = client.target("http://localhost:8080/RESTfulService/echo");
    //Aggiungo un parametro alla richiesta REST
    //Il parametro rappresenta il messaggio di cui fare l'echo
    target=target.queryParam("echo_msg", "ciao");
  
    // Invocazione del servizio
    Response res = target.request("text/plain").get();
  
    // Visualizzato l'intera risposta e il suo contenuto
    System.out.println(res);
    System.out.println(res.readEntity(String.class));
  }
}

Notiamo il WebTarget che punta all'url definita precedentemente con l'Annotation @Path

Eseguiamo ora il deploy della nostra web application RESTfulService (creando il war ed installandolo nella cartella di pubblicazione del server - ad esempio webapps in Tomcat) e lanciamo il client appena creato.

L'output del client sarà il seguente:

ScopedJaxrsResponse{ClientResponse{method=GET, uri=http://localhost:8080/RESTfulService/echo?echo_msg=ciao, status=200, reason=OK}}
ciao