Spring REST

Spring Framework 3.x trae la posibilidad de crear servicios web REST de manera muy simple.

Un ejemplo

Vamos a realizar una aplicación que responda a las siguientes URL:
/persona/todos   : devuelve todas las personas
/persona/123     : devuelve la persona cuyo id es 123
Tendremos que seguir 3 pasos:
  1. Configurar el servlet de Spring
  2. Crear la clase que atenderá y resolverá estas peticiones
  3. Configurar Spring

El servlet de Spring

Lo primero es configurar el servlet de Spring que se encargará de tomas las peticiones y redireccionarla a las clases correspondientes. La clase que se encarga de esto es org.springframework.web.servlet.DispatcherServlet. Un archivo web.xml de ejemplo sería:
 version="1.0" encoding="UTF-8"?>
 version="2.5" 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_2_5.xsd">
    json-con-spring-mvc



characterEncodingFilter
org.springframework.web.filter.CharacterEncodingFilter

encoding
UTF-8


forceEncoding
true




characterEncodingFilter
/*



Spring MVC Dispatcher Servlet
org.springframework.web.servlet.DispatcherServlet

contextConfigLocation

WEB-INF/applicationContext-clasico.xml


1



Spring MVC Dispatcher Servlet
/app/*




30



index.jsp

En este ejemplo, el servlet de Spring queda atendiendo todas las URL que empiecen con "/app".

El controller

La clase que toma las peticiones HTTP es una clase Java anotada con @Controller. Esta clase asocia las URL con métodos. Los objetos que devuelven los métodos son luego procesador por conversores, que representan la respuesta de distinta manera (XML, JSON, etc.)
Para esto, creamos una clase de la siguiente forma:
package com.dosideas.jsonconspringmvc;
 
import java.util.ArrayList;
import java.util.Collection;
import org.springframework.stereotype.Controller;
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.ResponseBody;
 
@Controller
@RequestMapping(value="/persona")
public class PersonaController {
 
    @RequestMapping(value="/{id}")
    public @ResponseBody Persona get(@PathVariable Long id) {
        Persona p = new Persona("Invasor " + id, "Zim " + id);
        return p;
    }
 
    @RequestMapping(value="/todos")
    public @ResponseBody Collection<Persona> getTodos() {
        Collection<Persona> personas = new ArrayList<Persona>();
        for (int i = 0; i < 10; i++) {
            Persona p = new Persona("Invasor " + i, "Zim" + i);
            personas.add(p);
        }
 
        return personas;
    }
}
El objeto Persona es un POJO que tiene dos atributos: nombre y apellido. Los tags @RequestMapping se encargan de asociar la clase y cada uno de sus métodos con una URL en particular.

La configuración

Lo último que nos queda configurar es Spring con un archivo clásico (el cual es referenciado por el servlet):
 version="1.0" encoding="UTF-8"?>
 xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xmlns:tx="http://www.springframework.org/schema/tx"
       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-3.0.xsd
       http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.xsd
       http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
       http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
 
     base-package="com.dosideas.jsonconspringmvc"/>
 
     />
 
El tag mvc:annotation-driven se encarga de configurar automáticamente para emepezar a recibir y responder peticiones usando los controladores encontrados.
Más aún, la configuración predeterminada se encarga de realizar negociación de contenido: la respuesta se formatea de acuerdo a las capacidades del cliente. Por ejemplo, si en el classpath tenemos agregado las librerías de Jackson (un parser JSON), se habilitará el soporte JSON correspondiente. Si están agregadas las librerías de JAXB2, se habilitará el soporte XML.

Probando

Podemos crear una prueba JUnit para acceder a nuestro servicio:
package com.dosideas.jsonconspringmvc;
 
import java.io.IOException;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.HttpMethod;
import org.apache.commons.httpclient.HttpClient;
import org.junit.Test;
import static org.junit.Assert.*;
 
public class HttpTest {
 
    @Test
    public void personaTodosJSON() throws IOException {
        HttpClient httpclient = new HttpClient();
        HttpMethod method = new GetMethod("http://localhost:8084/json-con-spring-mvc/app/persona/todos");
        method.addRequestHeader("accept", "application/json");
 
        httpclient.executeMethod(method);
        String resultado = method.getResponseBodyAsString();
        System.out.println(resultado);
 
        assertNotNull(resultado);
        assertTrue(resultado.startsWith("[{\""));
    }
 
    @Test
    public void personaPorIdJSON() throws IOException {
        HttpClient httpclient = new HttpClient();
        HttpMethod method = new GetMethod("http://localhost:8084/json-con-spring-mvc/app/persona/34421");
        method.addRequestHeader("accept", "application/json");
 
        httpclient.executeMethod(method);
        String resultado = method.getResponseBodyAsString();
        System.out.println(resultado);
 
        assertNotNull(resultado);
        assertTrue(resultado.startsWith("{\""));
        assertTrue(resultado.contains("34421"));
    }
 
    @Test
    public void personaPorIdXML() throws IOException {
        HttpClient httpclient = new HttpClient();
        HttpMethod method = new GetMethod("http://localhost:8084/json-con-spring-mvc/app/persona/34421");
        method.addRequestHeader("accept", "application/xml");
 
        httpclient.executeMethod(method);
        String resultado = method.getResponseBodyAsString();
        System.out.println(resultado);
 
        assertNotNull(resultado);
        assertTrue(resultado.startsWith("\"1.0\""
));
assertTrue(resultado.contains("34421"));
}

}

Manejo de errores

Es posible personalizar las excepciones para que devuelvan códigos de estado HTTP personalizados, usando la anotación @ResponseStatus en la excepción lanzada.
@ResponseStatus(value=HttpStatus.NOT_FOUND, reason="No se encontró el recurso pedido")
public class NotFoundException extends RuntimeException { ... }
 
.....
@Controller
@RequestMapping(value="/persona")
public class PersonaController {
    @RequestMapping(value="/id/{id}")
    public @ResponseBody Persona findById(@PathVariable long id) {
       Contact contact = personaService.findById(id);
       if (contact == null) {
           throw new NotFoundException();
       } else {
           return contact;
       }
    }
}
Otra forma de personalizar las excepciones, es interceptar las excepciones del controller(@Controller) y personalizarla en el mismo controller. Para esto debemos crear un método handleException por cada excepción que deseemos personalizar.
@Controller
@RequestMapping(value="/persona")
public class PersonaController {
    @RequestMapping(value="/id/{id}")
    public @ResponseBody Persona findById(@PathVariable long id) {
       Contact contact = personaService.findById(id);
       if (contact == null) {
           throw new NotFoundException();
       } else {
           return contact;
       }
    }
 
    @ResponseStatus(HttpStatus.NOT_FOUND)
    @ExceptionHandler(NotFoundException.class)
    @ResponseBody
    public Map<String, String> handleException(NotFoundException exception) {
        return Collections.singletonMap("message", "No se encontró el recurso pedido");
    }
}
Y agregar lo siguiente en el applicationContext.xml
 version="1.0" encoding="UTF-8"?>
 xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xmlns:tx="http://www.springframework.org/schema/tx"
       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-3.0.xsd
       http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.xsd
       http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
       http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
 
     base-package="com.dosideas.jsonconspringmvc"/>
 
     />
     class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver">
         name="messageConverters">
     
          class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter" />
     



Al utilizar este interceptor se debe personalizar las excepciones en todos los controladores, caso contrario la excepción no es customizada y retorna un status code 500. La propiedad "messageConverters", define que conversor utilizar en el ResponseBody, en nuestro caso lo estamos pasando a Json.
En caso de que se quiera utilizar los 2 métodos, el de @ResponseStatus y el de @ExceptionHandler, se deben registrar los 2 Handler en el applicationContext.xml con el orden de ejecución.
...
 class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver">
     name="order" value="1"/>
     name="messageConverters">
        
             class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter" />
       




class="org.springframework.web.servlet.mvc.annotation.ResponseStatusExceptionResolver" >
name="order" value="2"/>

...

Manejo de la respuesta

La anotación @ResponseStatus puede usarse para personalizar el código HTTP de cualquier respuesta, al ubicarla en el método. Por ejemplo, los métodos que devuelven void pueden usar esta anotación para indicar que no hay contenido (es útil si, por ejemplo, se parsea el contenido con algunas librerías como JQuery).
@RequestMapping(value="/delete/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable long id) {
        contactService.delete(id);
    }

Descargar un proyecto de ejemplo

Les dejamos para descargar un proyecto de ejemplo de REST con Spring MVC donde tienen todos los fuentes necesarios para abrir y ejecutar el ejemplo de esta página.

No hay comentarios:

Publicar un comentario en la entrada