Serveis web RESTful amb Java EE7. Escrivint serveis web

Veurem els diferents conceptes bàsics dels serveis web RESTful amb el típic exemple que sempre trobeu als manuals: farem un “Hello World!!!” i el publicarem com a servei web RESTful utilitzant l’API que JAX-RS que proporciona Java EE 7 per fer-ho.

Com que es tracta d’un exemple molt senzill, no ens cal cap projecte de partida; simplement, creeu a NetBeans un nou projecte Maven de tipus Web Application. Per fer-ho, feu File / New Project i us apareixerà l’assistent de creació de projectes. A l’assistent, seleccioneu Maven i Web Application, tal com es veu en la figura.

En la següent pantalla (vegeu la figura) triarem el nom del projecte i el paquet per defecte on anirà el codi font. El podeu anomenar “Resthelloioc” i posar el codi font a cat.xtec.ioc.resthelloioc.

En la següent pantalla (vegeu la figura) de l’assistent deixeu els valors per defecte i polseu Finish.

Ja tenim el projecte que ens servirà de base creat. Ara cal que codifiqueu el servei web RESTful que ens ha de tornar la salutació “Hello World!!!”; per fer-ho ens cal decidir primer dues coses: amb quin dels verbs HTTP ha de respondre el servei web i quin URI farem servir per cridar-lo.

Aquest servei web el que ha de fer és obtenir una representació del recurs en format HTML; per tant, haurà de respondre al verb GET.

La decisió sobre quin URI utilitzar és força arbitrària en aquest cas; utilitzarem, per exemple, /hello.

Per tant, a les peticions d’aquest tipus:

GET http://localhost:8080/resthelloioc/hello

Ha de respondre amb:

Hello World!!!

Un cop decidit el funcionament del nostre servei, el següent que us cal fer és codificar una classe Java que implementi la funcionalitat demanada.

Creeu una classe Java que implementarà aquesta funcionalitat, anomeneu-la HelloWorldService i la creeu al paquet cat.xtec.ioc.resthelloioc.service.

Anoteu la classe amb l’anotació @Path(“/hello”) i hi creeu un mètode anomenat, per exemple, sayHello, i l’anoteu amb @GET i @Produces(“text/html”).

package cat.xtec.ioc.resthelloioc.service;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
@Path("/hello") 
public class HelloWorldService {
    @GET
    @Produces("text/html")
    public String sayHello() {
        return "Hello World!!!";
    }    
}

Fixeu-vos que:

• Hem anotat la classe amb @Path(“/hello”) per indicar que respondrà a les peticions que arribin a l’URL localhost:8080/resthelloworld/hello.
• Hem anotat el mètode sayHello amb @GET per indicar que respondrà a les peticions HTTP que es facin mitjançant el verb GET.
• Hem anotat el mètode sayHello amb @Produces(“text/html”) per indicar que respondrà a les peticions HTTP en les quals a la capçalera s’indiqui “text/html” com a tipus MIME, i ho farà produint HTML com a representació del recurs.

I aquesta és tota la feina que ens cal fer per implementar el servei web, JAX-RS farà la resta. Ara tan sols ens manca fer-ne el desplegament al servidor d’aplicacions i provar-lo.

Un cop creat el servei web cal que el desplegueu per tal de fer-lo accessible als clients i poder-lo provar.

El procés de desplegament del servei web es fa desplegant l’aplicació Java EE que el conté mitjançant els mecanismes normals de desplegament de qualsevol aplicació Java EE.

El desplegament del servei web com a part de l’aplicació Java EE que el conté és molt senzill: simplement cal que feu Clean and Build i després Run a NetBeans (vegeu la figura) i es farà el desplegament al servidor d’aplicacions que tingueu configurat per al projecte.

Si ho feu i el proveu accedint a l’URL que hem configurat: localhost:8080/resthelloioc/hello veureu que el desplegament falla (vegeu la figura).

Això és degut al fet que ens cal indicar quines són les classes que ha de tractar com a recursos REST. Això es pot fer de moltes maneres, i una d’elles és crear una classe de configuració anomenada ApplicationConfig al paquet cat.xtec.ioc.resthelloioc.service amb el següent codi:

package cat.xtec.ioc.resthelloioc.service;
 
import javax.ws.rs.core.Application;
 
@javax.ws.rs.ApplicationPath("rest")
public class ApplicationConfig extends Application {
 
}

On s’indica que cal afegir “/rest” (o el que vulgueu posar) abans del nom del servei web per cridar-lo.

Si proveu ara accedint a l’URL localhost:8080/resthelloioc/rest/hello veureu que el servei web us torna la salutació (vegeu la figura).

Si utilitzeu les eines de debug de Google Chrome, per exemple, podreu veure la petició HTTP feta i la resposta rebuda (vegeu la figura).

Veurem els conceptes referents a la creació de serveis web RETSful amb Java EE 7 desenvolupant un servei web RESTful que permeti treballar sobre un catàleg de llibres. Hi farem les operacions típiques CRUD i dues operacions de cerca: la que ens tornarà tots els llibres i una que ens permetrà fer cerques per títol.

Concretament, el servei web que farem tindrà les següents operacions:

• Consulta d’un llibre mitjançant l’ISBN (operació Read CRUD).
• Creació d’un llibre al catàleg (operació Create CRUD).
• Actualització de les dades d’un llibre (operació Update CRUD).
• Esborrar un llibre del catàleg (operació Delete CRUD).
• Llistar tots els llibres del catàleg.
• Cercar llibres per títol.

Per fer-ho farem servir una aplicació web ja desenvolupada que segueixi una arquitectura per capes i hi afegireu una capa de serveis on creareu i publicareu el servei web de gestió del catàleg com a servei web RESTful. La representació que farem servir per als llibres en tot l’exemple serà JSON.

L’aplicació de la qual partirem s’anomena “Restbooksioc” i ens servirà per veure com podem exposar algunes funcionalitats de la capa de serveis d’una aplicació mitjançant serveis web RESTful. Es tracta d’un projecte Spring MVC senzill que segueix una arquitectura típica per capes per tal d’aconseguir una alta reusabilitat, un baix acoblament i una alta cohesió en l’aplicació.

El projecte consta de quatre capes:

• capa de presentació
• capa de domini
• capa de serveis
• capa de persistència

En l’exemple no farem servir la capa de presentació, ja que l’objectiu no és proporcionar una interfície d’usuari a l’aplicació sinó publicar els mètodes de negoci com a serveis web.

El model de domini ja el teniu implementat i és molt senzill, només hi ha una entitat Book que representa els llibres del catàleg (vegeu la figura).

La representació en JSON d’un recurs llibre és la següent:

{	
  "isbn":"9788425343537",
  "author":"Ildefonso Falcones",
  "title":"La catedral del mar"
}

Per fer la transformació entre objectes Java i JSON i a l’inrevés cal que importeu Jersey i Jackson com a artefactes al pom.xml. Aquesta tasca ja l’hem fet per vosaltres a la configuració inicial del projecte; les línies afegides al pom.xml són aquestes:

<dependency>            
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-server</artifactId>
  <version>2.22.1</version>
</dependency>
<dependency>
  <groupId>com.sun.jersey</groupId>
  <artifactId>jersey-json</artifactId>
  <version>1.19</version>
  </dependency>        
<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson</artifactId>
  <version>2.22.1</version>
</dependency>

La capa de serveis serà la que treballarem i haurà de proporcionar un servei web RESTful que permeti als clients fer les següents operacions sobre un catàleg de llibres:

• Llistar tots els llibres del catàleg.
• Consulta d’un llibre mitjançant l’ISBN.
• Creació d’un llibre al catàleg.
• Actualització de les dades d’un llibre.
• Esborrar un llibre del catàleg.
• Cercar llibres per títol.

La capa de persistència també la teniu implementada i conté l’objecte repositori que permet mapar les dades de la font de dades amb l’objecte de domini. En el nostre cas, per simplicitat, farem servir un repositori in memory que tindrà una llista precarregada amb els llibres del catàleg.

java.lang.NoClassDefFoundError: 
Could not initialize class org.eclipse.persistence.jaxb.BeanValidationHelper

Primer ens cal indicar quines són les classes que ha de tractar com a recursos REST. Això es pot fer de moltes maneres, una d’elles és crear una classe de configuració anomenada ApplicationConfig al paquet cat.xtec.ioc.service amb el següent codi:

package cat.xtec.ioc.service;
 
import javax.ws.rs.core.Application;
 
@javax.ws.rs.ApplicationPath("rest")
public class ApplicationConfig extends Application {
 
}

On s’indica que cal afegir “/rest” (o el que vulgueu posar) abans del nom del servei web per cridar-lo.

Un cop fet, crearem una classe que exposarà les operacions que volem; anomenarem la classe BooksRestService, la crearem al paquet cat.xtec.ioc.service i l’anotarem amb @Path(”/books”) i amb @Singleton.

@Path("/books")
@Singleton
public class BooksRestService {    
 
}

Fixeu-vos que:

• L’anotació @Path(”/books”) indica que el recurs estarà accessible a l’URI /books. Accedirem, doncs, als recursos amb l’URL localhost:8080/restbooksioc/rest/books.
• L’anotació @Singleton ens cal, pel fet que estem utilitzant una repositori in memory i necessitem que el servei web no s’inicialitzi cada vegada que es fa una petició, per tal de no perdre els canvis que anem fent al catàleg de llibres. Si féssiu servir una font de dades persistent no us caldria aquesta anotació, ja que els canvis persistirien a cada petició.

Un cop creada la classe cal que hi afegiu una referència al repositori del catàleg de llibres amb el següent codi:

private BookRepository bookRepository = new InMemoryBookRepository();

I ja podem començar a codificar el primer servei que volem oferir; per exemple, la consulta de tots els llibres del catàleg. Per fer-ho creeu un mètode anomenat getAll amb el següent codi:

@GET
@Produces(MediaType.APPLICATION_JSON)
public List<Book> getAll() {
    return this.bookRepository.getAll();
}

Fixeu-vos que:

• Hem anotat el mètode amb l’anotació @GET per indicar que aquest mètode respondrà a peticions HTTP de tipus GET.
• Hem anotat el mètode amb @Produces(MediaType.APPLICATION_JSON) per indicar que el resultat del mètode serà del tipus MIME “application/json”, ja que tornarem la llista de llibres en format JSON.

Per provar si funciona, desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/restbooksioc/rest/books; si tot ha anat bé veureu la representació JSON del catàleg de llibres al navegador:

[{"isbn":"9788425343537","author":"Ildefonso Falcones","title":"La catedral del mar"},
{"isbn":"9788467009477","author":"Jose Maria Peridis Perez","title":"La luz y el misterio de las catedrales"}]

Passem a crear ara el servei de consulta de llibres per ISBN (l’operació Read de CRUD); per fer-ho, creeu un mètode anomenat find amb el següent codi:

@GET
@Path("{isbn}")
@Produces(MediaType.APPLICATION_JSON)
public Book find(@PathParam("isbn") String isbn) {
    return this.bookRepository.get(isbn);
}

Hem anotat el mètode amb l’anotació @GET per indicar que aquest mètode respondrà a peticions HTTP de tipus GET.

Hem anotat el mètode amb @Produces(MediaType.APPLICATION_JSON) per indicar que el resultat del mètode serà del tipus MIME “application/json”, ja que tornarem la informació del llibre en format JSON.

Hem anotat el mètode amb l’anotació @Path(“{isbn}”) per indicar que la informació del llibre la tornarem quan ens arribin peticions GET a l’URI /books/{isbn}; és a dir, el que posem darrere de /books serà l’ISBN del llibre que volem consultar. Les anotacions @Path dels mètodes sempre s’afegeixen a l’anotació de l’arrel del recurs que heu definit a la classe.

El paràmetre que rep el mètode s’ha anotat amb l’anotació @PathParam(“isbn”). Aquesta és la forma que proporciona JAX-RS per extreure els paràmetres d’una petició. En aquest cas estem extraient un paràmetre del path, de l’URI, i el passem com a String al mètode find.

JAX-RS proporciona un ampli conjunt d’anotacions per fer aquesta tasca fàcil, entre elles destaquem @PathParam, @QueryParam, @MatrixParam, @CookieParam, @HeaderParam i @FormParam.

Per exemple, podríem utilitzar @QueryParam(“year”) per extreure un paràmetre que vingués en una petició d’aquesta forma: localhost:8080/restbooksioc/rest/books?year=2016.

Per provar si funciona, desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/restbooksioc/rest/books/9788425343537; si tot ha anat bé, veureu la representació JSON del llibre consultat al navegador:

[{"isbn":"9788425343537","author":"Ildefonso Falcones","title":"La catedral del mar”}]

Creem ara el servei que permeti donar d’alta un llibre al catàleg (l’operació Create de CRUD); per fer-ho, creeu un mètode anomenat create amb el següent codi:

@POST
@Consumes(MediaType.APPLICATION_JSON)
public void create(Book book) {
    this.bookRepository.add(book);
}

Hem anotat el mètode amb l’anotació @POST per indicar que aquest mètode respondrà a peticions HTTP de tipus POST.

Hem anotat el mètode amb @Consumes(MediaType.APPLICATION_JSON) per indicar que la informació del llibre que es vol donar d’alta vindrà en format JSON.

Fixeu-vos que tan sols amb aquesta informació JAX-RS és capaç, quan rep una petició POST a l’ URI /books amb una representació JSON d’un llibre, de crear un objecte de tipus Book i passar-lo al mètode create. No és fantàstic?

Ara tocaria provar aquesta funcionalitat, però tenim un problema: com podem enviar peticions POST sense fer una aplicació web amb un formulari? Per fer una petició GET tan sols hem de posar l’URL al navegador i ja ho tenim, però per fer peticions POST ens caldrà alguna utilitat extra. La nostra proposta és que feu servir cURL, que és una eina molt útil per fer peticions HTTP de diferents tipus i és multiplataforma. Si feu servir Linux possiblement ja la tingueu instal·lada al sistema; en cas que utilitzeu, Windows la podeu descarregar en el següent enllaç: curl.haxx.se/download.html, o bé aconseguir un .msi que us faciliti la instal·lació.

La sintaxi de cURL per fer peticions és molt senzilla; per exemple, per consultar tots els llibres del catàleg feu un command prompt:

curl localhost:8080/restbooksioc/rest/books

Per provar la funcionalitat que permet afegir un llibre al catàleg desplegueu el projecte fent Run a NetBeans i feu una petició POST a l’URL localhost:8080/restbooksioc/rest/books especificant la informació del llibre amb JSON; això ho podeu fer amb cURL i la següent comanda:

curl -H "Content-Type: application/json" -X POST -d "{\"isbn\":\"9788499301518\",\"author\":\"J.K. Rowling\",\"title\":\"Harry Potter y la piedra filosofal\"}" http://localhost:8080/restbooksioc/rest/books

Fixeu-vos-hi: li diem que farem una petició POST amb el paràmetre -X, li especifiquem el format JSON del llibre amb el paràmetre -d i indiquem que el format és JSON especificant-ho a la capçalera amb el paràmetre -H.

Executeu la comanda anterior i després consulteu el llistat de llibres amb:

curl localhost:8080/restbooksioc/rest/books

Si tot ha anat bé, veureu que el nou llibre s’ha afegit al catàleg de llibres:

[{"isbn":"9788499301518","author":"J.K. Rowling","title":"Harry Potter y la piedra filosofal"},
{"isbn":"9788425343537","author":"Ildefonso Falcones","title":"La catedral del mar"},
{"isbn":"9788467009477","author":"Jose Maria Peridis Perez","title":"La luz y el misterio de las catedrales"}]

Creem ara el servei que permeti modificar la informació d’un llibre del catàleg (l’operació Update de CRUD); per fer-ho, creeu un mètode anomenat update amb el següent codi:

@PUT
@Consumes(MediaType.APPLICATION_JSON)
public void edit(Book book) {
    this.bookRepository.update(book);
}

Les consideracions en aquest cas són les mateixes que hem vist per al cas de la creació de llibres, l’únic que canvia és que farem servir el verb PUT en lloc del verb POST.

Per provar la funcionalitat que permet modificar la informació d’un llibre del catàleg desplegueu el projecte fent Run a NetBeans i feu una petició PUT a l’URL localhost:8080/restbooksioc/rest/books especificant la nova informació del llibre amb JSON; això ho podeu fer amb cURL i la següent comanda:

curl -H "Content-Type: application/json" -X PUT -d "{\"isbn\":\"9788425343537\",\"author\":\" Ildefonso Falcones\",\"title\":\" LA CATEDRAL DEL MAR \"}" http://localhost:8080/restbooksioc/rest/books

Executeu la comanda anterior i després consulteu la informació del llibre que heu modificat amb:

curl localhost:8080/restbooksioc/rest/books/9788425343537

Si tot ha anat bé, veureu que el títol del llibre ha canviat a majúscules:

{"isbn":"9788425343537","author":" Ildefonso Falcones","title":" LA CATEDRAL DEL MAR "}

Creem ara el servei que permeti esborrar un llibre del catàleg (l’operació Delete de CRUD); per fer-ho, creeu un mètode anomenat remove amb el següent codi:

@DELETE
@Path("{isbn}")
public void remove(@PathParam("isbn") String isbn) {
    this.bookRepository.delete(isbn);
}

Les consideracions en aquest cas són les mateixes que hem vist per al cas de la consulta de llibres per ISBN, l’únic que canvia és que farem servir el verb DELETE en lloc del verb GET.

Per provar la funcionalitat que permet esborrar un llibre del catàleg desplegueu el projecte fent Run a NetBeans i feu una petició DELETE a l’URL localhost:8080/restbooksioc/rest/books especificant l’ISBN del llibre que volem esborrar; això ho podeu fer amb cURL i la següent comanda:

curl -X DELETE http://localhost:8080/restbooksioc/rest/books/9788425343537

Executeu la comanda anterior i després consulteu el llistat de llibres amb:

curl localhost:8080/restbooksioc/rest/books

Si tot ha anat bé, veureu que el llibre ja no el teniu al catàleg de llibres:

[{"isbn":"9788467009477","author":"Jose Maria Peridis Perez","title":"La luz y el misterio de las catedrales"}]

Finalment, codificarem una operació que ens permeti cercat llibres per títol; per fer-ho, creeu un mètode anomenat findByTitle amb el següent codi:

@GET
@Path("findByTitle/{title}")
@Produces(MediaType.APPLICATION_JSON)
public List<Book> findByTitle(@PathParam("title") String title) {
    return this.bookRepository.findByTitle(title);
}

Les consideracions en aquest cas són les mateixes que hem vist per al cas d’un llibre per ISBN, l’únic que canvia és que l’anotació @Path ara comença amb findByTitle i després té el paràmetre {title} per indicar que la consulta de llibres per títol la tornarem quan ens arribin peticions GET a l’URI /books/findByTitle/{title}, és a dir, el que posarem darrere del /books/findByTitle/ serà el títol que volem cercar.

Per provar la funcionalitat que permet cercar un llibre del catàleg per títol desplegueu el projecte fent Run a NetBeans i feu una petició GET a l’URL localhost:8080/restbooksioc/rest/books/findByTitle especificant el títol que volem cercar; això ho podeu fer amb cURL i la següent comanda (cercarem tots els llibres que tenen la paraula “catedral” al títol):

curl http://localhost:8080/restbooksioc/rest/books/findByTitle/catedral

Executeu la comanda anterior i, si tot ha anat bé, veureu que us torna els dos llibres del catàleg que tenen la paraula “catedral” al títol:

[{"isbn":"9788467009477","author":"Jose Maria Peridis Perez","title":"La luz y el misterio de las catedrales"},
{"isbn":"9788425343537","author":"Ildefonso Falcones","title":"La catedral del mar"}] 

I amb això ja heu codificat i provat el servei web RESTful que us permet treballar amb el catàleg de llibres.

El codi final de la classe BooksRestService és el següent:

@Path("/books")
@Singleton
public class BooksRestService {
 
    private BookRepository bookRepository = new InMemoryBookRepository();   
 
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Book> getAll() {
        return this.bookRepository.getAll();
    }
 
    @GET
    @Path("{isbn}")
    @Produces(MediaType.APPLICATION_JSON)
    public Book find(@PathParam("isbn") String isbn) {
        return this.bookRepository.get(isbn);
    }
 
    @GET
    @Path("findByTitle/{title}")
    @Produces(MediaType.APPLICATION_JSON)
    public List<Book> findByTitle(@PathParam("title") String title) {
        return this.bookRepository.findByTitle(title);
    }
 
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public void create(Book book) {
        this.bookRepository.add(book);
    }
 
    @PUT
    @Consumes(MediaType.APPLICATION_JSON)
    public void edit(Book book) {
        this.bookRepository.update(book);
    }
 
    @DELETE
    @Path("{isbn}")
    public void remove(@PathParam("isbn") String isbn) {
        this.bookRepository.delete(isbn);
    }
}

En aquest apartat heu vist les bases pel desenvolupament dels serveis web RESTful amb Java EE 7 i les heu treballat de forma pràctica mitjançant exemples.

Concretament, heu après:

• Les nocions bàsiques dels serveis web RESTful amb Java EE.
• A desenvolupar, desplegar i provar un servei web RESTful senzill amb Java EE.
• A desenvolupar, desplegar i provar un servei web RESTful complex amb Java EE que inclou operacions CRUD sobre un recurs.

Per aprofundir en aquests conceptes i veure com us pot ajudar NetBeans en la creació i el consum de serveis web RESTful us recomanem la realització de les activitats associades a aquest apartat.