Serveis web RESTful amb Spring. 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 Spring MVC per fer-ho.

El servei web que farem tornarà “Hello, World!!!” si no li passem cap paràmetre; si li passem un paràmetre anomenat name ens tornarà una salutació personalitzada canviant la paraula World pel nom especificat a name.

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 (el podeu anomenar “Springresthelloioc”) i el paquet per defecte on anirà el codi font; per exemple, cat.xtec.ioc.springresthelloioc.

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

Un cop creat el projecte cal que modifiqueu el pom.xml per afegir les dependències cap a Spring; afegiu les següent línies al fitxer pom.xml:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-webmvc</artifactId>
  <version>4.0.3.RELEASE</version>
</dependency>

També heu de crear el fitxer web.xml i configurar el servlet DispatcherServlet per tal que Spring MVC serveixi les peticions web; creeu el fitxer web.xml a la carpeta Web Pages/WEB-INF amb el següent contingut:

<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                                 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
 
    <display-name>Spring RESTful Hello World</display-name>
 
    <servlet>
        <servlet-name>DispatcherServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/spring/DispatcherServlet-servlet.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
 
    <servlet-mapping>
        <servlet-name>DispatcherServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>
</web-app>

Ens cal també crear el fitxer de configuració per a Spring; li hem indicat que el fitxer s’anomenarà DispatcherServlet-servlet.xml i serà a la ruta /WEB-INF/spring/. Creeu primer la carpeta /WEB-INF/spring/ i després el fitxer DispatcherServlet-servlet.xml amb el següent contingut:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context
                           http://www.springframework.org/schema/context/spring-context-4.0.xsd
                           http://www.springframework.org/schema/mvc
                           http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">
    <mvc:annotation-driven />
    <context:component-scan base-package="cat.xtec.ioc" />
 
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix" value="/WEB-INF/views/" />
        <property name="suffix" value=".jsp" />
    </bean>
 
</beans>

Si recarregueu el pom.xml fent clic amb el botó dret damunt el nom del projecte i prement l’opció Reload POM del menú contextual ja tindreu el projecte configurat i llest per començar a crear el servei web RESTful amb Spring.

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

Aquest servei web ha d’obtenir una representació del recurs en format JSON, i per tant haurà de respondre el 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:

{"id":1,"content":" Hello, World!!!"}

I a les peticions d’aquest tipus:

GET http://localhost:8080/resthelloioc/hello?name=User

ha de respondre amb:

{"id":1,"content":"Hello, User!"}

El servei web tornarà la informació en format JSON. A la sortida, el camp id és un identificador únic per a la salutació, i el camp content representa la salutació.

Un cop decidit el funcionament del nostre servei, el següent serà implementar la classe que modelarà la representació de la salutació, és a dir, la classe que modelarà el que torna el servei web.

Creeu una classe Java anomenada Greeting al paquet cat.xtec.ioc. springresthelloioc.domain amb el següent codi:

public class Greeting {
 
    private final long id;
    private final String content;
 
    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }
 
    public long getId() {
        return id;
    }
 
    public String getContent() {
        return content;
    }
}

Spring fa servir la llibreria Jackson per fer les transformacions entre el format JSON i la seva representació Java, i a l’inrevés.

El següent pas és crear el controlador Spring, que s’encarregarà de servir les peticions; per fer-ho, creeu una classe Java anomenada GreetingController al paquet cat.xtec.ioc.springresthelloioc.controller amb el següent codi:

package cat.xtec.ioc.springresthelloioc.controller;
 
import cat.xtec.ioc.springresthelloioc.domain.Greeting;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class GreetingController {
 
    private static final String template = "Hello, %s";
    private final AtomicLong counter = new AtomicLong();
 
    @RequestMapping(method =  RequestMethod.GET, value = "/hello")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World!!!") String name) {
        return new Greeting(counter.incrementAndGet(),
                            String.format(template, name));
    }
}

El codi del controlador és molt simple, però porta algunes particularitats que cal remarcar; fixeu-vos que:

• Hem anotat la classe amb @RestController per marcar la classe com un controlador REST on cada un dels seus mètodes tornarà un objecte del domini enlloc d’una vista. Aquesta és la diferència més gran entre un controlador MVC típic i un controlador per serveis web RESTful: el cos de la resposta HTTP es crea transformant un objecte del domini a JSON, i no es torna en format HTML.
• L’objecte Greeting que torna el mètode greeting cal que sigui transformat a JSON; Spring s’encarrega de fer això automàticament.
• Hem anotat el mètode greeting amb @RequestMapping indicant que les peticions a /hello les servirem amb aquest mètode.
• Hem anotat el mètode greeting amb RequestMethod.GET per indicar que respondrà a les peticions HTTP que es facin mitjançant el verb GET. Si no ho haguéssim fet, el mètode respondria a qualsevol dels verbs HTTP.
• Hem anotat el paràmetre del mètode greeting amb @RequestParam per indicar que el paràmetre name de la petició HTTP s’ha de vincular amb el paràmetre name del mètode. El paràmetre és opcional i, si no ve a la petició HTTP, farem servir “World!!!” com a valor per defecte.
• En la implementació simplement creem i retornem l’objecte Greeting, que modela la salutació.
• Com que hi ha la llibreria Jackson al classpath, Spring tria la conversió de l’objecte Greeting a JSON per defecte.

I aquesta és tota la feina que cal fer per implementar el servei web, Spring farà la resta. Ara tan sols 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.

Aquest procés és molt senzill, simplement cal que feu Clean and Build i després Run a NetBeans, i es farà el desplegament al servidor d’aplicacions que tingueu configurat per al projecte.

Si proveu ara accedint a l’URL localhost:8080/springresthelloioc/hello amb qualsevol navegador veureu que el servei web us torna la salutació en format JSON:

{"id":1,"content":"Hello, World!!!!"}

Proveu també especificant el paràmetre name, accedint a localhost:8080/springresthelloioc/hello?name=User, per exemple, i veureu que la salutació canvia:

{"id":2,"content":"Hello, User!"}

Amb això ja heu creat, configurat, desplegat i provat un servei web RESTful molt senzill amb Spring.

Aprofitarem les capacitats que proporcions Spring, i més concretament Spring MVC, per crear un conjunt de tests que van a cavall entre un test unitari i un test d’integració. Aquests tests us permetran provar els serveis web sense necessitat de tenir-los desplegats i executant-se a un servidor d’aplicacions. Testejarem amb Spring el típic exemple de “Hello, World!!!”.

El projecte té un servei web RESTful configurat a la classe GreetingController amb el següent codi:

package cat.xtec.ioc.springresthelloioc.controller;
 
import cat.xtec.ioc.springresthelloioc.domain.Greeting;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class GreetingController {
 
    private static final String template = "Hello, %s";
    private final AtomicLong counter = new AtomicLong();
 
    @RequestMapping(method =  RequestMethod.GET, value = "/hello")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World!!!") String name) {
        return new Greeting(counter.incrementAndGet(),
                            String.format(template, name));
    }
}

Aquest servei web és un servei web RESTful desenvolupat amb Spring que torna “Hello, World!!!” si no li passem cap paràmetre, i si li passem un paràmetre anomenat name torna una salutació personalitzada canviant la paraula World pel nom especificat a name.

El servei web torna la salutació en format JSON i respon a les peticions GET a /hello amb:

{"id":1,"content":" Hello, World!!!"}

I a les peticions GET a /hello?name=User amb:

{"id":1,"content":"Hello, User!"}

El test que escriurem utilitzarà les capacitats que té Spring MVC per fer test unitari dels endpoints configurats a un controlador RESTful. La principal diferència entre aquest tipus de tests i els tests d’integració és que en aquest cas no ens cal tenir el servei web que volem provar desplegat i executant-se a un servidor d’aplicacions.

Els tests unitaris amb el bastiment proporcionat per Spring MVC es basen en JUnit 4. JUnit és un framework de test que utilitza anotacions per identificar els mètodes que especifiquen un test. A JUnit, un test, ja sigui unitari o d’integració, és un mètode que s’especifica en una classe que només s’utilitza per al test. Això s’anomena una classe de test. Un mètode de test amb JUnit 4 es defineix amb l’anotació @org.junit.Test. En aquest mètode s’utilitza un mètode d’asserció en el qual es comprova el resultat esperat de l’execució de codi en comparació del resultat real.

Ara toca començar a crear els tests d’integració per provar el servei web. Per fer-ho, creeu un nou paquet dins de Test Packages anomenat, per exemple, cat.xtec.ioc.springresthelloioc.controller, i una classe Java anomenada GreetingControllerTest:

package cat.xtec.ioc.springresthelloioc.controller;
 
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.mock.http.MockHttpOutputMessage;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.context.WebApplicationContext;
 
import java.io.IOException;
import java.nio.charset.Charset;
import java.util.Arrays;
import static junit.framework.Assert.assertNotNull;
import static org.hamcrest.CoreMatchers.is;
 
import org.springframework.boot.test.SpringApplicationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
 
 
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = Application.class)
@WebAppConfiguration
public class GreetingControllerTest {
    private MediaType contentType = new MediaType(MediaType.APPLICATION_JSON.getType(),
            MediaType.APPLICATION_JSON.getSubtype(),
            Charset.forName("utf8"));
 
    private MockMvc mockMvc;
 
    private HttpMessageConverter mappingJackson2HttpMessageConverter;
 
    @Autowired
    private WebApplicationContext webApplicationContext;
 
    @Autowired
    void setConverters(HttpMessageConverter<?>[] converters) {
        this.mappingJackson2HttpMessageConverter = Arrays.asList(converters).stream()
            .filter(hmc -> hmc instanceof MappingJackson2HttpMessageConverter)
            .findAny()
            .orElse(null);
 
        assertNotNull("the JSON message converter must not be null",
                this.mappingJackson2HttpMessageConverter);
    }
 
    @Before
    public void setup() throws Exception {
        this.mockMvc = webAppContextSetup(webApplicationContext).build();
 
    }
 
 
    protected String json(Object o) throws IOException {
        MockHttpOutputMessage mockHttpOutputMessage = new MockHttpOutputMessage();
        this.mappingJackson2HttpMessageConverter.write(
                o, MediaType.APPLICATION_JSON, mockHttpOutputMessage);
        return mockHttpOutputMessage.getBodyAsString();
    }
}

Fixeu-vos que:

• Anotem la classe amb @RunWith(SpringJUnit4ClassRunner.class) per indicar que es tracta d’un test unitari que s’executarà amb l’executor de JUnit que porta Spring.
• Anotem la classe amb @SpringApplicationConfiguration(classes = Application.class) per indicar que crearem una classe que carregui la configuració Spring. Aquesta és una de les diverses maneres de fer-ho, també es podria carregar la configuració amb fitxers XML.
• Anotem la classe amb @WebAppConfiguration per indicar a JUnit que es tracta d’un test unitari per a Spring MVC i que s’ha d’executar amb un context d’aplicació web i no d’aplicació stand-alone.
• Anotem un mètode anomenat setup amb @Before per indicar a JUnit que aquest mètode s’executi cada cop que es creï la classe de test. En aquest mètode creem un objecte de tipus MockMvc que serà el que ens proporcionarà tota la infraestructura necessària per fer els tests sense haver de desplegar l’aplicació a cap servidor d’aplicacions.
• El mètode json és un mètode que ens torna la representació en format JSON d’un objecte.
• S’han configurat tots els conversors que es requereixen per parsejar les peticions i les respostes.

Per tal que Spring pugui carregar la configuració cal una classe anomenada Application al paquet cat.xtec.ioc.springresthelloioc.controller amb el següent codi:

package cat.xtec.ioc.springresthelloioc.controller;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
 
@SpringBootApplication
public class Application {
 
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Aquesta classe ja la teniu creada al projecte de partida.

El primer test que farem serà un test que comprovi que la petició /hello sense cap paràmetre torna la representació JSON de la salutació “Hello, World!!!”; per fer-ho, creeu un mètode anomenat greetingShouldReturnHelloWorldWithoutName dins la classe GreetingControllerTest amb el següent codi:

@Test
public void greetingShouldReturnHelloWorldWithoutName() throws Exception {
    mockMvc.perform(get("/hello"))                
            .andExpect(status().isOk())
            .andExpect(content().contentType(contentType))
            .andExpect(jsonPath("$.content", is("Hello, World!!!")));        
}

Si analitzem el codi veiem diverses coses importants: la primera és que hem anotat el mètode greetingShouldReturnHelloWorldWithoutName amb l’anotació @Test per indicar que es tracta d’un mètode de test.

També que fa servir l’objecte MockMVC que heu creat per fer una petició de tipus GET a l’ URI /hello; comproveu que el resultat de la petició sigui un 200 (OK), que el content type sigui JSON i que tingui al camp content la salutació per defecte ”Hello, World!!!”.

Ja podem executar el test que hem creat fent Test File (vegeu la figura) al menú contextual de la classe de test.

Si tot ha anat bé veureu el resultat a la finestra de Test (vegeu la figura).

Tot i que el resultat de l’execució dels test es pot veure a la finestra de sortida de NetBeans, és molt més còmode visualitzar-ho a la finestra de resultats de tests que proporciona també NetBeans; per mostrar aquesta finestra aneu al menú Window / IDE Tools / Test Results (vegeu la figura).

A Netbeans, els tests es poden executar de forma individual, és a dir, classe per classe o tots els del projecte. Si voleu executar tots els tests d’un projecte, primer heu de designar com a projecte principal el projecte “Springtestresthelloioc”, tal com podeu veure en la figura.

El segon test que farem serà un test que comprovi que la petició /hello?name=User torna la representació JSON de la salutació “Hello, User” ; per fer-ho, creeu un mètode anomenat greetingShouldReturnHelloNameWithName dins la classe GreetingControllerTest amb el següent codi:

@Test
public void greetingShouldReturnHelloNameWithName() throws Exception {
    mockMvc.perform(get("/hello?name=User"))                
            .andExpect(status().isOk())
            .andExpect(content().contentType(contentType))
            .andExpect(jsonPath("$.content", is("Hello, User")));        
}

El codi és molt similar al primer test; executeu-lo de la mateixa manera i comproveu que el test s’executa correctament (vegeu la figura).

Aquest dos exemples us donen la base per tal que pugueu fer tots els tests unitaris que se us acudeixin per als serveis web RESTful que desenvolupeu amb Spring i així tenir-los totalment provats.

Veurem els conceptes referents a la creació de serveis web RETSful amb Spring desenvolupant un servei web RESTful que permeti fer operacions sobre equips de futbol i els jugadors que els integren. Farem les operacions típiques CRUD amb els jugadors, una operació que mostra el llistat d’equips, una que mostra els jugadors d’un equip i una altra que mostra les dades d’un equip.

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

• llistar tots els equips
• consulta de les dades d’un equip
• llistar tots els jugadors d’un equip
• consulta d’un jugador d’un equip (operació Read CRUD)
• creació d’un jugador en un equip (operació Create CRUD)
• actualització de les dades d’un jugador d’un equip (operació Update CRUD)
• esborrar un jugador d’un equip (operació Delete CRUD)

Per fer-ho emprareu una aplicació web ja desenvolupada que segueix una arquitectura per capes i hi afegireu una capa de serveis on creareu i publicareu el servei web de gestió d’equips catàleg com a servei web RESTful. La representació dels recursos que fareu servir en tot l’exemple serà JSON.

L’aplicació de la qual partireu s’anomena “Springrestteamsioc” i servirà per veure com podeu 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ó a l’aplicació.

El projecte consta de quatre capes:

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

Com que l’aplicació d’exemple no ha de proporcionar interfície gràfica, fareu servir la capa de presentació com la capa on publicareu els serveis RESTful; seria igualment vàlid fer-ho a una capa de serveis independent.

El model de domini ja el teniu implementat i és molt senzill: hi ha una entitat Team que representa un equip i una entitat Player que representa els jugadors d’un equip. Entre Team i Player hi ha una associació 1:N per indicar que un jugador pertany a un equip i que un equip està format per N jugadors (vegeu la figura).

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

{ 
  "id":1,
  "name":"F.C. Barcelona",
  "foundationYear":"1899"
}

I la representació JSON d’un jugador és la següent:

{
  "id":1,
  "name":"Lionel Messi",
  "goals":472,
  "age":29,
  "teamId":1
}

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 els equips:

• llistar tots els equips
• consulta de les dades d’un equip
• llistar tots els jugadors d’un equip
• consulta d’un jugador d’un equip
• creació d’un jugador en un equip
• actualització de les dades d’un jugador d’un equip
• esborrar un jugador d’un equip

La capa de persistència també la teniu implementada i conté dos objectes repositori que permeten mapar les dades de les fonts de dades amb els objectes del domini. En el nostre cas, per simplicitat, farem servir repositoris in memory que tindran una llista precarregada amb els equips i els jugadors de cada equip.

Un cop fet, creareu una classe que exposarà les operacions que voleu realitzar sobre els equips; anomenareu la classe TeamsController, la creareu al paquet cat.xtec.ioc.controller i l’anotareu amb @RestController:

package cat.xtec.ioc.controller;
 
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class TeamsController {
}

Simplement heu anotat la classe amb @RestController per marcar la classe com un controlador REST on cada un dels seus mètodes tornarà un objecte del domini enlloc d’una vista. Aquesta és la diferència més gran entre un controlador MVC típic i un controlador per a serveis web RESTful: el cos de la resposta HTTP es crea transformant un objecte del domini a JSON i no es torna en format HTML.

Un cop creada la classe cal que hi afegiu una referència al repositori dels equips fent que Spring el carregui amb el seu mòdul d’injecció de dependències:

@Autowired
private TeamRepository teamRepository;
 
public TeamsController() {
}
 
public TeamsController(TeamRepository teamRepository) {
    this.teamRepository = teamRepository;
}

I ja podeu començar a codificar el primer servei que voleu oferir; per exemple, la consulta de tots els equips. Per fer-ho, creeu un mètode anomenat getAll amb el següent codi:

@RequestMapping(method =  RequestMethod.GET, value = "/teams")
public @ResponseBody List<Team> getAll() {
    return this.teamRepository.getAll();        
}

Hem anotat el mètode amb l’anotació @RequestMapping(method = RequestMethod.GET, value = ”/teams”) per indicar que aquest mètode respondrà a peticions HTTP de tipus GET a l’URL /teams.

Hem anotat el mètode amb @ResponseBody per indicar a Spring que torni el resultat en un format que sigui entenedor per al client a partir de les capçaleres HTTP que envia amb la petició. Per defecte, es torna en format JSON.

Tornem la llista d’equips com una llista d’objectes Java de tipus Team i Spring s’encarregarà de transformar-los a format JSON.

Per provar si funciona, desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/springrestteamsioc/teams; si tot ha anat bé, veureu la representació JSON dels equips al navegador:

[
{"id":1,"name":"F.C.Barcelona","foundationYear":"1899"},
{"id":2,"name":"Real Madrid","foundationYear":"1902"}
]

Passem a crear ara el servei de consulta de les dades d’un equip; per fer-ho, creeu un mètode anomenat getById amb el següent codi:

@RequestMapping(value = "/teams/{id}", method = RequestMethod.GET)
 public @ResponseBody Team getById(@PathVariable int id) {
    return this.teamRepository.get(id);
}

El codi és molt similar a la consulta d’equips, però com a particularitat cal comentar que ara tornem un objecte Java de tipus Team que Spring convertirà a JSON abans de tornar-lo al client i que hem anotat el mètode amb l’anotació @RequestMapping(value = ”/teams/{id}”, method = RequestMethod.GET) per indicar que la informació de l’equip la tornarem quan ens arribin peticions GET a l’URI /teams/{id}; és a dir, el que posem darrere de /teams serà l’identificador de l’equip que volem consultar.

El paràmetre que rep el mètode s’ha anotat amb l’anotació @PathVariable int id. Aquesta és la forma que proporciona Spring per extreure els paràmetres d’una petició. En aquest cas estem extraient un paràmetre del path i el passem com a int al mètode getById.

Spring MVC proporciona un ampli conjunt d’anotacions per fer aquesta tasca fàcil, entre elles @PathParam, @RequestParam, @CookieValue, @RequestHeader, etc.

Per exemple, podríem utilitzar @RequestParam(“id”) per extreure un paràmetre que vingués en una petició d’aquesta forma: localhost:8080/springrestteamsioc/teams?id=2.

Per provar si funciona desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/springrestteamsioc/teams/1; si tot ha anat bé, veureu la representació JSON de l’equip consultat al navegador:

[{ 
  "id":1,
  "name":"F.C. Barcelona",
  "foundationYear":"1899"
}]

Ja heu creat les dues operacions que volíeu per als equips, ara començareu amb les operacions que voleu oferir per als jugadors d’un equip. Aquestes operacions les podríeu posar el mateix controlador on heu posat les operacions per als equips, però per fer un codi més net i que respecti al màxim el principi de disseny SRP (de l’anglès Single Responsability Principle) ho fareu en un controlador diferent.

Creeu una classe que exposarà les operacions que voleu realitzar sobre els jugadors dels equips; anomenareu la classe PlayerController, la creareu al paquet cat.xtec.ioc.controller i l’anotareu amb @RestController:

package cat.xtec.ioc.controller;
 
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
 
@RestController
@RequestMapping("/teams/{teamId}/players")
public class PlayerController {
}

Simplement heu anotat la classe amb @RestController per marcar la classe com un controlador REST on cada un dels seus mètodes tornarà un objecte del domini enlloc d’una vista.

També heu anotat la classe amb @RequestMapping(”/teams/{teamId}/players”) per indicar que tots els mètodes del controlador s’han d’accedir amb aquest format. Amb això, tots els mètodes del controlador podran extreure del path l’identificador de l’equip i no us caldrà repetir-ho a cada un d’ells.

Un cop creada la classe, cal que hi afegiu una referència al repositori dels jugadors dels equips fent que Spring el carregui amb el seu mòdul d’injecció de dependències:

@Autowired
private PlayerRepository playerRepository;
 
public PlayerController() {
}
 
public PlayerController(PlayerRepository playerRepository) {
    this.playerRepository = playerRepository;
}

Creeu primer la funcionalitat que permeti la consulta de tots els jugadors d’un equip. Per fer-ho, creeu un mètode anomenat getTeamPlayers amb el següent codi:

@RequestMapping(method = RequestMethod.GET)
public @ResponseBody List<Player> getTeamPlayers(@PathVariable int teamId) {
    return this.playerRepository.getByTeam(teamId);
}

Heu anotat el mètode amb l’anotació @RequestMapping(method = RequestMethod.GET) per indicar que aquest mètode respondrà a peticions HTTP de tipus GET i ho farà a l’URI per defecte que heu configurat al controlador (/teams/{teamId}/players).

Heu anotat el mètode amb @ResponseBody per indicar a Spring que torni el resultat en un format que sigui comprensible per al client a partir de les capçaleres HTTP que el client envia amb la petició. Per defecte, es torna en format JSON.

Torneu la llista d’equips com una llista d’objectes Java de tipus Player i Spring s’encarregarà de transformar-los a format JSON.

Per provar si funciona, desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/springrestteamsioc/teams/1/players; si tot ha anat bé, veureu la representació JSON dels jugadors del FC Barcelona al navegador:

[
{"id":1,"name":"LionelMessi","goals":472,"age":29,"teamId":1},
{"id":2,"name":"Luis Suarez","goals":100,"age":29,"teamId":1}}
]

Passareu a crear ara el servei de consulta de les dades d’un jugador d’un equip (l’operació Read de CRUD); per fer-ho, creeu un mètode anomenat getById amb el següent codi:

@RequestMapping(value = "{playerId}", method = RequestMethod.GET)
public @ResponseBody Player getById(@PathVariable int teamId, @PathVariable int playerId) {
    return this.playerRepository.get(teamId, playerId);
}

El codi és molt similar a la consulta dels jugadors d’un equip; com a particularitat, cal comentar que ara tornem un objecte Java de tipus Player que Spring convertirà a JSON abans de tornar-lo al client i que hem anotat el mètode amb l’anotació @RequestMapping(value = ”{playerId}”, method = RequestMethod.GET) per indicar que la informació del jugador la tornarem quan ens arribin peticions GET a l’URI /teams/{teamId}/players/{playerId}; és a dir, el que posem darrere de /teams serà l’identificador de l’equip al qual pertany el jugador, i el que posem darrere de players serà l’identificador del jugador que volem consultar.

Els paràmetres que rep el mètode s’han anotat amb les anotacions @PathVariable int teamId i @PathVariable int playerId, respectivament. Aquesta és la forma que proporciona Spring per extreure els paràmetres d’una petició. En aquest cas, estem extraient dos paràmetres del path i els passem com a int al mètode getById.

Per provar si funciona, desplegueu el projecte fent Run a NetBeans i accediu amb un navegador a l’URL localhost:8080/springrestteamsioc/teams/1/players/1; si tot ha anat bé, veureu la representació JSON del jugador “Lionel Messi” del “FC Barcelona” al navegador:

[{ 
  {"id":1,
   "name":"Lionel Messi",
   "goals":472,
   "age":29,
   "teamId":1}
 }
]

Un cop fetes les dues operacions de consulta sobre els jugadors d’un equip passareu ara a crear el servei que permeti donar d’alta un jugador d’un equip (l’operació Create de CRUD); per fer-ho, creeu un mètode anomenat create amb el següent codi:

@RequestMapping(method = RequestMethod.POST)
public @ResponseBody ResponseEntity<Player> create(@PathVariable int teamId, @RequestBody Player player) {
    player.setTeamId(teamId);
    this.playerRepository.add(player);
    return new ResponseEntity<>(player, HttpStatus.CREATED);
}

Heu anotat el mètode amb l’anotació @RequestMapping(method = RequestMethod.POST) per indicar que aquest mètode respondrà a peticions HTTP de tipus POST i ho farà a l’URI per defecte que heu configurat al controlador (/teams/{teamId}/players).

La resposta que tornem és de tipus ResponseEntity<Player> per tal que hi puguem afegir la representació del jugador creat i el codi HTTP (en aquest cas un codi 201, CREATED, per indicar que el recurs s’ha creat satisfactòriament).

Fixeu-vos que tan sols amb aquesta informació Spring és capaç, quan rep una petició POST a l’URI /teams/{teamId}/players amb una representació JSON d’un jugador, de crear un objecte de tipus Player i passar-lo al mètode create.

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

La sintaxi de cURL per fer peticions és molt senzilla; per exemple, per consultar tots els equips feu un command prompt:

curl localhost:8080/springrestteamsioc/teams

Per provar la funcionalitat que permet afegir un jugador al FC Barcelona desplegueu el projecte fent Run a NetBeans i feu una petició POST a l’URL localhost:8080/springrestteamsioc /teams/1/players especificant la informació del jugador amb JSON; això ho podeu fer amb cURL i la següent comanda:

curl -H "Content-Type: application/json" -X POST -d "{\"id\":\"3\",\"name\":\"Neymar da Silva Santos\",\"age\":\"24\",\"goals\":\"100\"}" http://localhost:8080/springrestteamsioc/teams/1/players

Fixeu-vos: li diem que farem una petició POST amb el paràmetre -X, li especifiquem el format JSON del jugador amb el paràmetre -d i li 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 els jugadors del FC Barcelona amb:

curl localhost:8080/springrestteamsioc/teams/1/players

Si tot ha anat bé, veureu que Neymar s’ha afegit com a jugador del FC Barcelona:

[
 {"id":1,"name":"Lionel Messi","goals":472,"age":29,"teamId":1},
 {"id":2,"name":"Luis Suarez","goals":100,"age":29,"teamId":1},
 {"id":3,"name":"Neymar da Silva Santos","goals":100,"age":24,"teamId":1}
]

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

@RequestMapping(method = RequestMethod.PUT)
public @ResponseBody ResponseEntity<Player> update(@PathVariable int teamId, @RequestBody Player player) {
    player.setTeamId(teamId);
    this.playerRepository.update(player);
    return new ResponseEntity<>(player, HttpStatus.OK);
}

Les consideracions en aquest cas són les mateixes que hem vist per al cas de la creació d’un jugador, 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 jugador desplegueu el projecte fent Run a NetBeans i feu una petició PUT a l’URL localhost:8080/springrestteamsioc /teams/1/players especificant la nova informació del jugador; això ho podeu fer amb cURL i la següent comanda:

curl -H "Content-Type: application/json" -X PUT -d "{\"id\":\"3\",\"name\":\"Neymar da Silva Santos\",\"age\":\"24\",\"goals\":\"120\"}" http://localhost:8080/springrestteamsioc/teams/1/players

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

curl http://localhost:8080/springrestteamsioc/teams/1/players/3

Si tot ha anat bé, veureu que el nombre de gols que ha marcat Neymar ha passat de 100 a 120:

[ 
 {"id":3,"name":"Neymar da Silva Santos","goals":120,"age":24,"teamId":1}
]

Creem ara el servei que permeti esborrar un jugador d’un equip (l’operació Delete de CRUD); per fer-ho, creeu un mètode anomenat delete amb el següent codi:

@RequestMapping(value = "{playerId}", method = RequestMethod.DELETE)
public @ResponseBody ResponseEntity<Player> delete(@PathVariable int teamId, @PathVariable int playerId) {     
    this.playerRepository.delete(teamId, playerId);
    return new ResponseEntity<>(HttpStatus.OK);
}

Les consideracions en aquest cas són les mateixes que hem vist per al cas de la consulta d’un jugador d’un equip, i l’únic que canvia és que fareu servir el verb DELETE en lloc del verb GET.

Per provar la funcionalitat que permet esborrar un jugador d’un equip desplegueu el projecte fent Run a NetBeans i feu una petició DELETE a l’URL localhost:8080/springrestteamsioc/{teamId}/players/{playerId} especificant l’equip al qual pertany el jugador i l’identificador del jugador que volem esborrar; això ho podeu fer amb cURL i la següent comanda (per exemple, per esborrar el jugador Neymar del FC Barcelona):

curl -X DELETE localhost:8080/springrestteamsioc/teams/1/players/3

Executeu la comanda anterior i després consulteu els jugadors del FC Barcelona amb:

curl localhost:8080/springrestteamsioc/teams/1/players/

Si tot ha anat bé, veureu que Neymar ja no és jugador del FC Barcelona:

[
 {"id":1,"name":"Lionel Messi","goals":472,"age":29,"teamId":1},
 {"id":2,"name":"Luis Suarez","goals":100,"age":29,"teamId":1}
]

I amb això ja heu codificat i provat el servei web RESTful que us permet treballar amb els equips i els seus jugadors. El codi final de la classe TeamController és el següent:

package cat.xtec.ioc.controller;
 
import cat.xtec.ioc.domain.Team;
import cat.xtec.ioc.domain.repository.TeamRepository;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class TeamsController {
 
    @Autowired
    private TeamRepository teamRepository;
 
    public TeamsController() {
    }
 
    public TeamsController(TeamRepository teamRepository) {
        this.teamRepository = teamRepository;
    }
 
    @RequestMapping(method = RequestMethod.GET, value = "/teams")
    public @ResponseBody
    List<Team> getAll() {
        return this.teamRepository.getAll();
    }
 
    @RequestMapping(value = "/teams/{id}", method = RequestMethod.GET)
    public @ResponseBody
    Team getById(@PathVariable int id) {
        return this.teamRepository.get(id);
    }
}

I el de la classe PlayerController és el següent:

package cat.xtec.ioc.controller;
 
import cat.xtec.ioc.domain.Player;
import cat.xtec.ioc.domain.repository.PlayerRepository;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@RequestMapping("/teams/{teamId}/players")
public class PlayerController {
 
    @Autowired
    private PlayerRepository playerRepository;
 
    public PlayerController() {
    }
 
    public PlayerController(PlayerRepository playerRepository) {
        this.playerRepository = playerRepository;
    }
 
    @RequestMapping(method = RequestMethod.GET)
    public @ResponseBody
    List<Player> getTeamPlayers(@PathVariable int teamId) {
        return this.playerRepository.getByTeam(teamId);
    }
 
    @RequestMapping(value = "{playerId}", method = RequestMethod.GET)
    public @ResponseBody
    Player getById(@PathVariable int teamId, @PathVariable int playerId) {
        return this.playerRepository.get(teamId, playerId);
    }
 
    @RequestMapping(method = RequestMethod.POST)
    public @ResponseBody
    ResponseEntity<Player> create(@PathVariable int teamId, @RequestBody Player player) {
        player.setTeamId(teamId);
        this.playerRepository.add(player);
        return new ResponseEntity<>(player, HttpStatus.CREATED);
    }
 
    @RequestMapping(method = RequestMethod.PUT)
    public @ResponseBody
    ResponseEntity<Player> update(@PathVariable int teamId, @RequestBody Player player) {
        player.setTeamId(teamId);
        this.playerRepository.update(player);
        return new ResponseEntity<>(player, HttpStatus.OK);
    }
 
    @RequestMapping(value = "{playerId}", method = RequestMethod.DELETE)
    public @ResponseBody
    ResponseEntity<Player> delete(@PathVariable int teamId, @PathVariable int playerId) {
        this.playerRepository.delete(teamId, playerId);
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

En aquest apartat heu vist les bases per al desenvolupament dels serveis web RESTful amb Spring i les heu treballat de forma pràctica mitjançant exemples.

Concretament, heu après:

• Les nocions bàsiques dels serveis web RESTful amb Spring.
• Desenvolupar, desplegar i provar un servei web RESTful senzill amb Spring.
• Fer tests unitaris dels serveis web RESTful amb Spring.
• Desenvolupar, desplegar i provar un servei web RESTful complex amb Spring que inclou operacions CRUD sobre un recurs.

Per aprofundir en aquests conceptes i veure quins són els conceptes que hi ha darrere de HATEOAS (de l’anglès Hypermedia as the Engine of Application State) us recomanem la realització de l’ activitat associada a aquest apartat.