Creación Servicio Web RESTful

11/11/2015
Nivel Medio-Avanzado, Premium, Servicios Web

En esta serie de publicaciones vamos a desarrollar un ejercicio donde mostraremos el proceso de conexión y gestión de una base de datos MySQL desde una aplicación Android, a través de un servicio web RESTful.

Para ello, vamos a mostrar primero en este tutorial cómo crear ese servicio web, utilizando la API JAX-RS de la versión Java SE que nos facilitará esta tarea.

Al final del tutorial, podrás descargar el código de este proyecto.

Elementos del Proyecto

Para el ejemplo que a continuación se va a describir, se han necesitado los siguientes elementos; posteriormente mostraremos como acceder ellos:

Eclipse versión Luna Release (4.4.0).
Tipo de proyecto «Dynamic Web Project».
Servidor Apache Tomcat 6.0.
API Jersey 2.22 (Implementación de referencia de JAX-RS).
API JAX-RS (Java API for RestFul Web Services).

JAX-RS: The Java API for RestFul Web Services, es una API de Java que nos facilita la creación de servicios web REST. JAX-RS usa anotaciones (dedicamos un pequeño apartado a las «anotaciones» en este mismo tutorial) y a partir de la versión 1.1, es parte oficial de Java EE 6, por lo que entre otras cosas no se requiere configuración para comenzar a usarlo.

Nosotros utilizaremos Jersey , que es un implementación de JAX-RS y nos provee una librería para implementar servicios web RESTful en un contenedor de Java servlets (dedicamos luego un breve apartado a explicar qué es un servlet. Apache Tomcat es un contenedor de servlets).

Puedes ampliar información en este artículo donde se presentaba JAX-RS (en inglés)

Configuración, estructura y ficheros del Proyecto

Se creará un nuevo proyecto en Eclipse de tipo «Dynamic Web Project». Además del nombre del proyecto, se deberá indicar el servidor Apache Tomcat con el que deseamos lanzar el servicio RESTful (aquí puedes descargar un servidor Apache Tomcat para asociarlo a este tipo de proyectos con Eclipse):

Nota: Para implementar este tipo de proyectos en Eclipse (si no está disponible en las opciones de nuevo proyecto) será necesario disponer de las herramientas de desarrollo web de Eclipse, que pueden instalarse a través del menú Help > Instal New Software…. e introduciendo el repositorio software http://download.eclipse.org/releases/indigo/.

Otro de los pasos necesarios dentro de la ventana de creación de proyecto, será añadir dentro de la opción de configuración, la librería JAX-RS (Java API for RestFul Web Services):

Posteriormente se deberá indicar la configuración para la construcción de la aplicación Java (para este ejemplo se deja por defecto):

Al tratarse de un proyecto que utilizará el framework Jersey (implementación de referencia de JAX-RS), se deberá añadir dicho framework, creando una librería de usuario, y seleccionando los archivos java externos (*.jar):

Una vez creado el proyecto, mostraría la siguiente estructura:

A esta estructura por defecto se deberá añadir una clase java, que nos permita poder comprobar el funcionamiento del servicio. En este caso realizaremos un «HolaMundo», y su posterior ejecución mostrando el mensaje en texto plano:

HolaMundoDWP\src\com\academiaandroid\holamundo\HolaMundo.java

package com.academiaandroid.holamundo;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/HolaMundo")
public class HolaMundo 
{   
    @GET
    @Path("/saludo")
    @Produces(MediaType.TEXT_PLAIN)
    public String holaMundo()
    {
        String saludo = "Hola Mundo!!!";        
        return saludo;  
    }
}

package com.academiaandroid.holamundo;

import javax.ws.rs.GET;

import javax.ws.rs.Path;

import javax.ws.rs.Produces;

import javax.ws.rs.core.MediaType;

@Path("/HolaMundo")

public class HolaMundo

{

@GET

@Path("/saludo")

@Produces(MediaType.TEXT_PLAIN)

public String holaMundo()

{

String saludo = "Hola Mundo!!!";

return saludo;

}

En el siguiente paso se deberá modificar el archivo «web.xml» para el servlet de JAX-RS. Este archivo contiene información sobre la estructura y las dependencias externas de los componentes web en el módulo y describe cómo se utilizan los componentes en tiempo de ejecución. Cuando se utilizan servlets, cualquier vía de acceso que está definida en el archivo web.xml se añadirá al URL base. El ejemplo que se muestra quedaría de la siguiente manera:

HolaMundoDWP\WebContent\WEB-INF\web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>HolaMundoDWP</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
  </welcome-file-list>
  <servlet>
    <description>JAX-RS Tools Generated</description>
    <servlet-name>HolaMundo</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.academiaandroid.holamundo</param-value>
    </init-param>  
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>HolaMundo</servlet-name>
    <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>
</web-app>

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">

<display-name>HolaMundoDWP</display-name>

<welcome-file-list>

<welcome-file>index.html</welcome-file>

<welcome-file>index.htm</welcome-file>

<welcome-file>index.jsp</welcome-file>

<welcome-file>default.html</welcome-file>

<welcome-file>default.htm</welcome-file>

<welcome-file>default.jsp</welcome-file>

</welcome-file-list>

<description>JAX-RS Tools Generated</description>

<servlet-name>HolaMundo</servlet-name>

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

<init-param>

<param-name>com.sun.jersey.config.property.packages</param-name>

<param-value>com.academiaandroid.holamundo</param-value>

</init-param>

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

</servlet>

<servlet-mapping>

<servlet-name>HolaMundo</servlet-name>

<url-pattern>/rest/*</url-pattern>

</servlet-mapping>

</web-app>

Una vez añadida la clase java y modificado el archivo «web.xml», será necesario explicar algunas de las configuraciones realizadas:

La primera entrada, en la raíz del elemento servlet, define un nombre para el servlet y especifica la clase compilada que ejecuta el mismo.
Se define un servlet propio por defecto, que permite establecer la lógica del manejo de peticiones al servlet (en el caso de este ejemplo devolver texto plano). Para configurar dicho servlet, se deberá indicar el nombre del mismo, y el patrón url.

Iniciar parámetros en servlet

Es posible pasar parámetros al servlet desde el archivo web.xml. Dichos parámetros solo serán accesibles por el servlet, y es posible configurarlos de la siguiente forma:

<?xml version="1.0" encoding="UTF-8"?>
<web-app...

[...]

  <servlet>

    [...]

    <init-param>
        <param-name>holamundo</param-name>
        <param-value>Hola Mundo!!!</param-value>
    </init-param>   
  </servlet>
  <servlet-mapping>
    <servlet-name>HolaMundo</servlet-name>
    <url-pattern>/rest/HolaMundo</url-pattern>
  </servlet-mapping>

</web-app>

<?xml version="1.0" encoding="UTF-8"?>

<web-app...

[...]

[...]

<init-param>

<param-name>holamundo</param-name>

<param-value>Hola Mundo!!!</param-value>

</init-param>

</servlet>

<servlet-mapping>

<servlet-name>HolaMundo</servlet-name>

<url-pattern>/rest/HolaMundo</url-pattern>

</servlet-mapping>

</web-app>

HolaMundoDWP\src\com\academiaandroid\holamundo\HolaMundo.java

package com.academiaandroid.holamundo;

import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class HolaMundo extends HttpServlet
{   

    String parametroEntrada = null;

    public void init(ServletConfig config) throws ServletException
    {
        super.init(config);
        parametroEntrada = config.getInitParameter("holamundo");
    }

    public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();
        out.println("<html><head></head><body>" + parametroEntrada + "</body></html>");
    }
}

package com.academiaandroid.holamundo;

import java.io.IOException;

import java.io.PrintWriter;

import javax.servlet.ServletConfig;

import javax.servlet.ServletException;

import javax.servlet.http.HttpServlet;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

public class HolaMundo extends HttpServlet

{

String parametroEntrada = null;

public void init(ServletConfig config) throws ServletException

{

super.init(config);

parametroEntrada = config.getInitParameter("holamundo");

}

public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException

{

response.setContentType("text/html");

PrintWriter out = response.getWriter();

out.println("<html><head></head><body>" + parametroEntrada + "</body></html>");

}

El número situado dentro del elemento <load-on-startup>1</load-on-startup> indica al contenedor de servlets la secuencia de carga de los mismos. Los números menores serán cargados primero. Si el número es negativo o no se ha especificado, el servlet podrá ser cargado en cualquier momento:

<?xml version="1.0" encoding="UTF-8"?>
<web-app...

[...]

  <servlet>

    [...]

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

[...]

</web-app>

<?xml version="1.0" encoding="UTF-8"?>

<web-app...

[...]

[...]

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

</servlet>

[...]

</web-app>

Finalmente al compilar la aplicación se mostrará el siguiente resultado, a partir de la URI creada:

Partiendo de la base del ejemplo anterior, es necesario describir algunos aspectos que aparecen en dicho ejemplo, como es el caso de un servlet y el uso de anotaciones en Java:

Que es un servlet?

Un servlet es un programa que se ejecuta en el contenedor Web de un servidor de aplicaciones y puede ser invocado por los clientes utilizando el protocolo HTTP. Si un applet es un pequeño programa que se carga y ejecuta en un navegador web, un servlet sería algo análogo pero en el contexto de un servidor web.

Los servlets fueron la alternativa que Sun (la compañia creadora de Java) planteó a la programación CGI. Es una tecnología más eficiente que ésta, ya que cada petición que les realiza un cliente inicia un hilo, en vez de un proceso, reduciendo el uso de memoria del servidor y el tiempo de respuesta.

El uso más común de los servlets es generar páginas web de forma dinámica a partir de los parámetros de la petición que envíe el navegador web (algo similar a los que sucede al interpretarse una página PHP en un servidor Web, por ejemplo), aunque pueden realizar otras tareas como comunicarse con otro servlet o facilitar el acceso a base de datos.

Desde el punto de vista del lenguaje Java, los servlets son clases del API Java Servlet (no son parte de las librerías estándar Java) que implementan la interfaz Servlet, como HttpServlet, utilizada para servicios específicos HTTP y se ejecutan en un servidor web que tenga capacidad para ello como Apache Tomcat .

Un servlet típico extiende a HttServlet y sobreescribe uno o varios de los métodos servlet que responden a las peticiones de los clientes, como doGet() o doPost() . Los otros métodos, init y detroy, inician el servlet y lo eliminan de de memoria una vez deja de necesitarse. No nos vamos a extender más, ya que profundizar en este tema excede con mucho el objetivo de este tutorial. Puedes encontrar numerosa documentación en la Web, como esta presentación que enlazamos aquí.

Anotaciones

Se trata de una manera de añadir metadatos al código fuente Java en tiempo de ejecución, y que define los recursos y las acciones que se pueden realizar sobre dichos recursos.

@Path

Define la ruta URI relativa, que indica la clase Java que será organizada. Además es posible integrar variables dentro de este tipo de anotación.

import javax.ws.rs.Path;

@Path("/holamundo/{nombre}")

import javax.ws.rs.Path;

@Path("/holamundo/{nombre}")

@GET, @POST, @PUT, @DELETE, @HEAD

Se trata de métodos para realizar una petición, y que se corresponde con el método HTTP denominado igual. Cuando un método esté anotado con esta petición, se procesará una petición HTTP GET/POST/PUT/DELETE/HEAD.

@PathParam

Es un tipo de parámetro que se puede extraer para su uso en la clase de recursos. Los parámetros de la ruta URI se extraen de la URI de solicitud, y los nombres de los parámetros corresponden a los nombres de las variables de plantilla ruta URI especificados en la anotación @Path a nivel de clase.

@QueryParam

Es un tipo de parámetro que se puede extraer para su uso en la clase de recursos.
Los parámetros de consulta se extraen de los parámetros de consulta URI de la solicitud.

@Consumes

Se utiliza para especificar los tipos de medios MIME para la representación de un recurso que puede consumir, enviados por un cliente.

@Produces

Se utiliza para especificar los tipos de medios MIME para la representaciones de un recurso que puede producir y enviar de vuelta al cliente.

import javax.ws.rs.Produces;

@Produces(MediaType.TEXT_PLAIN)

import javax.ws.rs.Produces;

@Produces(MediaType.TEXT_PLAIN)

@Provider

Se utiliza para cualquier cosa que sea de interés en tiempo de ejecución JAX-RS, como MessageBodyReader y MessageBodyWriter. Para las peticiones HTTP, el MessageBodyReader se utiliza para asignar un cuerpo de entidad para la petición HTTP de los parámetros del método. Por el lado de la respuesta, un valor de retorno se asigna a un cuerpo de entidad de respuesta HTTP usando un MessageBodyWriter.

NOTA: Al utilizar la API RESTful JAX-RS, es necesario tener en cuenta las siguientes reglas en tiempo de ejecución:

Métodos HTTP (GET,POST etc.) corresponde con las anotaciones (@GET, @POST etc.).
Cabecera HTTP content-type corresponde con la anotación @Consumes.
Cabecera HTTP accept corresponde con la anotación @Produces.*

Descarga del Proyecto

Aquí puedes descargar el código de este proyecto

Download

En el próximo tutorial veremos la creación de una Aplicación Android para la gestión de libros de una biblioteca. Esta App actuará de cliente de este servidor web RESTful con conexión a una base de datos MySQL.