rest jersey

41
Servicios REST con Eclipse y JAX-RS Software como Servicio y Distribuido – 2011/2012 Diego Sevilla Ruiz DITEC Facultad de Informática Murcia, noviembre de 2011 Diego Sevilla Ruiz (DITEC Facultad de Informática) Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 1 / 41

Upload: wrangler2626

Post on 13-Oct-2014

69 views

Category:

Documents


9 download

TRANSCRIPT

Page 1: Rest Jersey

Servicios REST con Eclipse y JAX-RSSoftware como Servicio y Distribuido – 2011/2012

Diego Sevilla Ruiz

DITECFacultad de Informática

Murcia, noviembre de 2011

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 1 / 41

Page 2: Rest Jersey

Índice

1 Introducción

2 Proyecto Eclipse

3 JAX-RS (Jersey)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 2 / 41

Page 3: Rest Jersey

Índice

1 Introducción

2 Proyecto Eclipse

3 JAX-RS (Jersey)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 3 / 41

Page 4: Rest Jersey

Introducción

En esta práctica:1 Descargaremos y configuraremos Eclipse (en Linux) para ejecutar

proyectos REST (JAX-RS/Jersey)2 Crearemos un proyecto Web dinámico3 Lo configuraremos para que soporte Jersey (implementación de

JAX-RS)4 Estudiaremos los fundamentos de JAX-RS

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 4 / 41

Page 5: Rest Jersey

Descarga de Software

En este caso en Linux:Descargar Tomcat 6.0http://tomcat.apache.org/download-60.cgi (.tar.gz ó .zip)Implementación de JAX-RS (Jersey)http://download.java.net/maven/2/com/sun/jersey/jersey-archive/1.4/jersey-archive-1.4.zipEclipse IDE para JavaEEhttp://www.eclipse.org/downloads/

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 5 / 41

Page 6: Rest Jersey

Configuración Eclipse – Entorno servidorWindow → Preferences → Server → Runtime Environment

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 6 / 41

Page 7: Rest Jersey

Configuración Eclipse – Entorno servidor (ii)

Add... → Apache Tomcat 6.0 → Next...

Añadir el directorio donde reside el servidor TomcatDiego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 7 / 41

Page 8: Rest Jersey

Índice

1 Introducción

2 Proyecto Eclipse

3 JAX-RS (Jersey)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 8 / 41

Page 9: Rest Jersey

Proyecto EclipseFile → New → Project. . . → Web → Dynamic Web Project

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 9 / 41

Page 10: Rest Jersey

Proyecto Eclipse (ii)

Copiar los .jar del .zip deJersey en el dir.WebContent/WEB-INF/lib

La configuración delproyecto automáticamenteusa también el directorioWEB-INF/lib para buscarlos servlets de Tomcat

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 10 / 41

Page 11: Rest Jersey

Proyecto Eclipse – Clase Java

En el subdirectorio Java Resources: src, crear el archivo Hello.java

1 package es.um.scsyd.RestTest.first;

3 import javax.ws.rs.GET;import javax.ws.rs.Path;

5 import javax.ws.rs.Produces;import javax.ws.rs.core.MediaType;

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 11 / 41

Page 12: Rest Jersey

Proyecto Eclipse – Clase Java (ii)

POJO: Plain Old Java Object, no implementa interfaces, no tiene extends

// POJO , no interface no extends2

//Sets the path to base URL + /hello4 @Path("/hello")

public class Hello {6

// This method is called if TEXT_PLAIN is request8 @GET

@Produces(MediaType.TEXT_PLAIN)10 public String sayPlainTextHello () {

return "Hello Jersey";12 }

Anotaciones@Path@GET@Produces

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 12 / 41

Page 13: Rest Jersey

Proyecto Eclipse – Clase Java (iii)

// This method is called if XML is request2 @GET

@Produces(MediaType.TEXT_XML)4 public String sayXMLHello () {

return "<?xml version =\"1.0\"? >" + "<hello > HelloJersey" + "</hello >";

6 }

8 // This method is called if HTML is request@GET

10 @Produces(MediaType.TEXT_HTML)public String sayHtmlHello () {

12 return "<html > " + "<title >" + "Hello Jersey" + "</title >"

+ "<body ><h1>" + "Hello Jersey" + "</h1 ></body >" + "</html > ";

14 }

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 13 / 41

Page 14: Rest Jersey

Activar el servlet Jersey

Fichero: WebContent/WEB-INF/web.xml(dentro de la etiqueta <web-app>)

<servlet >2 <servlet -name >Jersey REST Service </servlet -name >

<servlet -class >com.sun.jersey.spi.container.servlet.ServletContainer </servlet -class >

4 <init -param ><param -name >com.sun.jersey.config.property.

packages </param -name >6 <param -value >es.um.scsyd.RestTest.first </param -

value ></init -param >

8 <load -on-startup >1</load -on-startup ></servlet >

10 <servlet -mapping ><servlet -name >Jersey REST Service </servlet -name >

12 <url -pattern >/rest/*</url -pattern ></servlet -mapping >

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 14 / 41

Page 15: Rest Jersey

Ejecutar el servicioPara ejecutar el servicio: web.xml → Run As... → Run on Server

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 15 / 41

Page 16: Rest Jersey

Ejecutar el servicio (ii)Servicio en funcionamiento (perspectiva JavaEE)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 16 / 41

Page 17: Rest Jersey

Ejecutar el servicio (iii)

En la perspectiva JavaEE:La esquina inferior derecha muestra el servidor funcionando

http://localhost:8080/es.um.scsyd.RestTest/rest/hello

El servidor se inicia en el puerto 8080Contiene el nombre del proyecto (es.um.scsyd.RestTest)La base del servicio (rest/* )El @Path del fichero Java (/hello)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 17 / 41

Page 18: Rest Jersey

Proyecto Eclipse – Cliente

En el subdirectorio Java Resources: src, crear el archivoTestClient.java

1 package es.um.scsyd.RestTest.first;

3 import java.net.URI;

5 import javax.ws.rs.core.MediaType;import javax.ws.rs.core.UriBuilder;

7

import com.sun.jersey.api.client.Client;9 import com.sun.jersey.api.client.ClientResponse;

import com.sun.jersey.api.client.WebResource;11 import com.sun.jersey.api.client.config.ClientConfig;

import com.sun.jersey.api.client.config.DefaultClientConfig;

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 18 / 41

Page 19: Rest Jersey

Proyecto Eclipse – Cliente (ii)

public class TestClient {2 public static void main(String [] args) {

ClientConfig config = new DefaultClientConfig ();4 Client client = Client.create(config);

WebResource service = client.resource(getBaseURI ());6 // Fluent interfaces

System.out.println(service.path("rest").path("hello").accept(8 MediaType.TEXT_PLAIN).get(ClientResponse.class).toString ());

// Get plain text10 System.out.println(service.path("rest").path("hello").accept(

MediaType.TEXT_PLAIN).get(String.class));12 // Get XML

System.out.println(service.path("rest").path("hello").accept(14 MediaType.TEXT_XML).get(String.class));

// The HTML16 System.out.println(service.path("rest").path("hello").accept(

MediaType.TEXT_HTML).get(String.class));18 }

20 private static URI getBaseURI () {return UriBuilder.fromUri(

22 "http :// localhost :8080/ es.um.scsyd.RestTest").build();}

24 }

TestClient.java (botón derecho) → Run As... → Java Application

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 19 / 41

Page 20: Rest Jersey

Proyecto Eclipse – Cliente (iii)Salida

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 20 / 41

Page 21: Rest Jersey

Índice

1 Introducción

2 Proyecto Eclipse

3 JAX-RS (Jersey)

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 21 / 41

Page 22: Rest Jersey

JAX-RS (Jersey)

JAX-RS es una especificación de Sun (Oracle) para implementarservicios REST usando clases Java + anotacionesSe define en el documento de especificación JSR-3111

Jersey2 es la implementación de referencia, aunque hay otras, comoApache CXF

1https://jsr311.dev.java.net/.2https://jersey.dev.java.net/.

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 22 / 41

Page 23: Rest Jersey

Recursos como clases

Basados en el concepto de POJO (Plain Old Java Object)Clases sin extends ni implements (Martin Fowler)Término heredado de C/C++: Plain Old Data (POD)Tiene sentido, son clases de datos

Tiene que existir una clase recurso raízTambién tiene sentido, ya que las URIs son jerárquicasTiene que tener una anotación @Path en la clase o en un método

⇒ Especifica el path inicialMétodos con anotaciones @GET, @PUT, etc.

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 23 / 41

Page 24: Rest Jersey

Resumen de anotacionesAnnotation Descripción@Path The @Path annotation’s value is a relative URI path indicating where

the Java class will be hosted, for example, /helloworld. You can alsoembed variables in the URIs to make a URI path template. For example,you could ask for the name of a user, and pass it to the applicationas a variable in the URI, like this, /helloworld/{username}. @Pathannotations in operations are made relative to the @Path annotation intheir containing class.

@GET The @GET annotation is a request method designator and corresponds tothe similarly named HTTP method. The Java method annotated with thisrequest method designator will process HTTP GET requests.

@POST The @POST annotation is a request method designator and correspondsto the similarly named HTTP method. The Java method annotated withthis request method designator will process HTTP POST requests.

@PUT The @PUT annotation is a request method designator and corresponds tothe similarly named HTTP method. The Java method annotated with thisrequest method designator will process HTTP PUT requests.

@DELETE The @DELETE annotation is a request method designator and correspondsto the similarly named HTTP method. The Java method annotated withthis request method designator will process HTTP DELETE requests.

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 24 / 41

Page 25: Rest Jersey

Resumen de anotaciones (ii)

Annotation Descripción@HEAD The @HEAD annotation is a request method designator and corresponds

to the similarly named HTTP method. The Java method annotated withthis request method designator will process HTTP HEAD requests.

@PathParam The @PathParam annotation is a type of parameter that you can extractfor use in your resource class. URI path parameters are extracted fromthe request URI, and the parameter names correspond to the URI pathtemplate variable names specified in the @Path class-level annotation.

@QueryParam The @QueryParam annotation is a type of parameter that you can extractfor use in your resource class. Query parameters are extracted from therequest URI query parameters.

@Consumes The @Consumes annotation is used to specify the MIME media types ofrepresentations a resource can consume that were sent by the client.

@Produces The @Produces annotation is used to specify the MIME media types ofrepresentations a resource can produce and send back to the client, forexample, "text/plain".

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 25 / 41

Page 26: Rest Jersey

Resumen de anotaciones (iii)

Annotation Descripción@Provider The @Provider annotation is used for anything that is of in-

terest to the JAX-RS runtime, such as MessageBodyReader andMessageBodyWriter. For HTTP requests, the MessageBodyReader isused to map an HTTP request entity body to method parameters. Onthe response side, a return value is mapped to an HTTP response entitybody using a MessageBodyWriter. If the application needs to supplyadditional metadata, such as HTTP headers or a different status code, amethod can return a Response that wraps the entity, and which can bebuilt using Response.ResponseBuilder.

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 26 / 41

Page 27: Rest Jersey

Parámetros de URL

@Path("/users /{ username}")2 public class UserResource {

@GET4 @Produces("text/xml")

public String getUser(@PathParam("username")String userName) {

6 ...}

8 }

El patrón {username} implica una variable (parámetro) de la URLA través de la anotación @PathParam se asocia la anotación con unparámetro del métodoLa expresión regular por defecto para el parámetro es «[^/]+?»,pero se puede especificar otra:

@Path("users /{ username: [a-zA-Z][a-zA-Z_0 -9]}")

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 27 / 41

Page 28: Rest Jersey

Métodos implementados por defecto

@HEADImplementado automáticamente llamando al método etiquetado con@GET, e ignorando la respuesta

@OPTIONSRetorna en la cabecera Allow el conjunto de métodos que soporta elrecursoJersey retornará también una descripción WADL (Web ApplicationDescription Language)3

3https://wadl.dev.java.net/.Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 28 / 41

Page 29: Rest Jersey

Gestión de peticiones y respuestas

Los métodos con anotaciones:Pueden retornar void, un tipo Java, o javax.ws.rs.core.ResponseSi retornan un Response, pueden utilizar el patrón builder con laclase ResponseBuilderSi quieren modificar los headers HTTP, tienen que retornar un objetoResponseLa conversión entre tipos Java y respuestas se realiza con dos clases:

MessageBodyReader para PUT y POST (lectura)MessageBodyWriter para GET (productor)Si no se especifica una conversión automática (se verá después)

El tipo Java retornado tiene que tener un constructor con un String

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 29 / 41

Page 30: Rest Jersey

Parámetros de las peticiones

La anotación @QueryParam permite extraer información de la partede pregunta de la URL:

http://xxx/recurso?abc...

Anotaciones adicionales: @DefaultValue:1 @Path("smooth")

@GET3 public Response smooth(

@DefaultValue("2") @QueryParam("step") int step ,5 @DefaultValue("true") @QueryParam("min -m")

boolean hasMin ,@DefaultValue("true") @QueryParam("max -m")

boolean hasMax ,7 ...

Las clases de @QueryParam pueden ser las estándar de Java, o todasaquellas que tengan un constructor que acepta un StringTambién @MatrixParam, @HeaderParam, @CookieParam y@FormParam

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 30 / 41

Page 31: Rest Jersey

Información de contexto

Si es necesario obtener el mapa de asociaciones de parámetros depetición (query) y cadenas, se puede utilizar la anotación @Context:

1 @GETpublic String get(@Context UriInfo ui) {

3 MultivaluedMap <String , String > queryParams =ui.getQueryParameters ();

5 MultivaluedMap <String , String > pathParams =ui.getPathParameters ();

7 }

Y también las cabeceras HTTP:1 @GET

public String get(@Context HttpHeaders hh) {3 MultivaluedMap <String , String > headerParams =

hh.getRequestHeaders ();5 Map <String , Cookie > pathParams =

hh.getCookies ();7 }

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 31 / 41

Page 32: Rest Jersey

Soporte para producir XML

Se soporta el serializado y deserializado XML a través de beansJAXB

La clase que se serializará como un recurso XML o JSON se tieneque anotar con @XmlRootElementSi en algún elemento de un recurso se retorna un elemento de esaclase y se etiqueta con los tipos@Produces({MediaType.TEXT_XML,Mediatype.APPLICATION_JSON}), seserializa automáticamenteVéase http://www.vogella.de/articles/JAXB/article.html

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 32 / 41

Page 33: Rest Jersey

Soporte para producir XML

Clase serializada: Item@XmlRootElement

2 public class Item {private String uri;

4 public void setUri(String uri) {this.uri = uri;

6 }public String getUri () { return uri; }

8 }

Recurso (/rest/hello/item):@GET @Path("item")

2 @Produces(MediaType.TEXT_XML)public Item item()

4 {Item i = new Item();

6 i.setUri("abc");return i;

8 }Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 33 / 41

Page 34: Rest Jersey

Soporte para leer XML

Recurso (/rest/hello/item):Recibe como entrada directamente un recursoserializable/deserializable (Item)

@POST2 @Consumes(MediaType.TEXT_XML)

@Path("item")4 public void newItem(Item i)

{6 System.out.println("Recibido item: " + i.getUri ())

;}

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 34 / 41

Page 35: Rest Jersey

Response.ResponseBuilder

Utilizado para construir objetos ResponseResponse también tiene métodos estáticos que devuelvenResponse.ResponseBuilder:

ok() – Respuesta correctacreated() – Respuesta para un recurso creadostatus(int status) – Respuesta con estadotemporaryRedirect(java.net.URI location) – Redirección aotra localización especificada como un URI. . .

Más información en la página de la clase:https://jsr311.dev.java.net/nonav/releases/1.0/javax/ws/rs/core/Response.html

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 35 / 41

Page 36: Rest Jersey

Response.ResponseBuilder (ii)

Operaciones principales:build() – Construir un Response a partir de un ResponseBuildercacheControl() – Controla la cabecera de la cachéheader(java.lang.String name, java.lang.Object value) –Añadir una cabecera explícitamentestatus(int status) – Estadotype(MediaType type) – Añadir el Media-type:. . .

Página de la clase:https://jsr311.dev.java.net/nonav/releases/1.0/javax/ws/rs/core/Response.ResponseBuilder.html

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 36 / 41

Page 37: Rest Jersey

Media Types y URIs

javax.ws.rs.core.MediaType:TEXT_PLAIN, TEXT_HTML, etc., predefinidosMediaType(String type, String subtype) – Construir un mediatype a partir de tipo/subtipoboolean isCompatible(MediaType other) – Comprobación decompatibilidadhttps://jsr311.dev.java.net/nonav/releases/1.0/javax/ws/rs/core/MediaType.html

javax.ws.rs.core.UriBuilder – Construye java.net.URIfromUri(String uri) – Desde Stringfragment(String), queryParam(String name, Object[]values), matrixParam(String name, Object[] values) – Partesde la URIhttps://jsr311.dev.java.net/nonav/releases/1.0/javax/ws/rs/core/UriBuilder.html

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 37 / 41

Page 38: Rest Jersey

Uso de curl para probar servicios

curl:-X método – Especifica el método HTTP

P. ej. -X GET

-H cabecera – Especifica cabeceras a enviarP. ej. -H Accept:text/xml

--data datos – Datos de POSTP. ej. --data ’<?xml><item><uri>...</uri></item>’

1 $ curl -X GET -HAccept:text/xml \http :// localhost :8080/ es.um.scsyd.RestTest/rest/

hello/item

<?xml version="1.0" encoding="UTF -8"standalone="yes"?>2 <item><uri>abc</uri></item>

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 38 / 41

Page 39: Rest Jersey

Uso de curl para probar servicios (ii)

$ curl -X POST -HContent -type:text/xml \2 --data ’<item ><uri >abcdef </uri ></item >’ \

http :// localhost :8080/ es.um.scsyd.RestTest/rest/hello/item

1 Recibido item: abcdef

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 39 / 41

Page 40: Rest Jersey

Trabajo para casa

Estudiar el ejemplo storage-service de los ejemplos de Jersey

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 40 / 41

Page 41: Rest Jersey

Referencias

L. Richardson, S. RubyRESTful Web ServicesO’Reilly, 2007

L. VogelRESTful Webservices with Java and Jersey (JAX-RS)http://www.vogella.de/articles/REST/article.html

Sun Microsystems (Oracle)RESTful Web Services Developer’s Guidehttp://docs.sun.com/app/docs/doc/820-4867?l=en&a=loadhttp://wikis.sun.com/display/Jersey/Overview+of+JAX-RS+1.0+Features

M. Paternostro, K. HusseyBuilding RESTful Java Applications with EMFhttp://www.slideshare.net/kenn.hussey/building-restful-java-applications-with-emf

Diego Sevilla Ruiz (DITEC Facultad de Informática)Servicios REST con Eclipse y JAX-RS Murcia, noviembre de 2011 41 / 41