Iniciándose en RESTful Web Services

(Traducción no oficial de Getting Started with RESTful Web Services)

REpresentational State Transfer (REST) es un estilo de arquitectura para sistemas hipermedia distribuidos, tales como la World Wide Web. El centro de la arquitectura RESTful es el contecpto de los recursos identificados por los identificadores de recursos universal (universal resource identifiers URIs). Estos recursos pueden ser manipulados usando un interfaz estándar, tales como el HTTP, y la información es intercambiada usando representaciones de estos recursos. En este tutorial, primero aprenderemos un poco acerca de REST y luego veremos como NetBeans 6.1 maneja este estilo de arquitectura.

Introducción

Los servicios web RESTful son servicios construidos usando el estilo de arquitectura RESTful. El construir servicios web usando RESTful hace que se aproxime a una alternativa emergencia y popular usando tecnologías basadas en SOAP para desplegar servicios en internet, debido a que es liviando y tiene la capacidad de transmitir datos directamente desde HTTP.

El IDE permite el desarrollo rápido de servicios RESTfulsando la especificación JSR311 - Java API for RESTful Web Services (JAX-RS) y Jersey, la imeplementación del JAX-RS.

Además de construir servicios web RESTful, el IDE también permite probar, construir aplicaciones clientes que accedan a servicios web RESTful, y generando código para invocar a los servicios web (tanto RESTful como basado en SOAP).

Generando Clases de Entidad desde una Base de datos

El objetivo de este ejercicio es crear un proyecto y generar clases entidad desde una base de datos.

Seleccione File > New Project. Debajo de Categories, seleccione Web. Debajo de Projects, seleccione Web Application y clic en Next.

En Project name, escriba CustomerDB.

Seleccione GlassFish como servidor. Clic en Finish.

Abra la ficha Services (Ctrl+5). Debajo de Databases, clic derecho en Java DB e iniciarlo.

Volvemos al panel de proyectos (Ctrl+1). Haga clic derecho en el nodo del proyecto y seleccione New > Entity Classes from Database. Otra manera de hacer es seleccionar la categoría Persistence en el asistente de Nuevo Archivo (Ctrl+N)

En el panel de las tablas de la base de datos, seleccione como fuente de datos jdbc/sample.

Debajo de la sección de Tablas disponibles (Available Tables) seleccione CUSTOMER y haga clic en el botón "Add". La tabla DISCOUNT_TABLE también se agregará ya que está relacionada con la tabla CUSTOMER.

Clic en Next.

En la entrada del package, escriba customerdb. Como se ve acontinuación:

Clic en Create Persistence Unit. Llene los datos como se ve en el siguiente diálogo:

Clic en Create y luego en Finish.

Revise la ventana de proyectos. Debería lucir así:

Generando Servicio Web RESTful desde las clases entidad

La meta de este ejercicio es generar servicios web RESTful desde las clases entidad que se crearon en la sección anterior.

Presione Ctrl+N para crear un nuevo archivo. Seleccione la categoría Web Services y e

Clic en Next.

En la ventana de selección de Clases Entidad, haga clic en "Add All>>". Clic en el botón Next.

En el campo Resource package escriba customerdb.service, y en el campo Converter Package, escriba customerdb.converter.

Acepte todos los valores por defecto como se muestran a continuación:

Aquí se puede ver lo que el IDE generará por nosotros. NetBeans usa el patrón del elemento del contenedor para generar las clases del recurso. Por ejemplo, para la clase entidad Customer, NetBeans genera un recurso de contenedor llamado CustomersResource y un recurso llamado CustomerResource. Además,por cada clase recurso, NetBeans generar una clase convertidor que se usará para generar la representación del recurso desde las instancias de entidad correspondientes, tales como CustomerConverter y CustomerConverter.

Es más, hay información adicional de la clase convertidora llamada convertidor de referencia, tal como CustomerRefConverter, que representará relaciones.

Clic en Finish.

Ahora la ventana del proyecto lucirá algo así:

El nodo RESTful Web Services muestra todos los servicios web RESTful de nuestro proyecto. El valor entre los corchetes, como [/customers/], es el valor para el URI de la plantilla. Podemos enrtar al código fuente haciendo doble clic en el nodo. Esta vista también muestra todos los métodos HTTTP y los métodos de ubicación de los subrecursos. También podemos hacer doble clic en los nodos para ver los métodos.

Ahora que ya se generaron las clases entidad y los servicios web RESTful, probemos la aplicación.

Probando los servicios web RESTful

La meta de esta ejercicio es probar la aplicación que acabamos de crear.

Clic derecho en el nodo del proyecto seleccionar Test RESTful Web Services. El servidor se iniciará y la aplicación será desplegada. Cuando haya terminado, el navegador web de nuestro sistema mostrará nuestra aplicación, con un enlace por cada servicio web.

En el lado izquierdo están los recursos. Aquí son llamados customers y discountCodes.

Primero seleccionemos el recurso customers. Luego, de la lista Choose method to test seleccionemos "GET(application/json)" o "GET(application/xml)". Y hagamos clic en el botón "Test".

Notemos que el resultado se muestra en la parte inferior de esta página estática. (Revisa el URL del navegador y verás que no es http://.. sino file:///)

En este resultado se muestran 4 fichas. La vista tabular (Tabular View) es una vista plana que muestra todos los URI en el documento resultante. Podemos hacerle clic a un url para ver el contenido.

La vista cruda (Raw view) muestra los datos que se obtuvieron del servicio web. Si hemos seleccionado application/xml se mostrarán en formato xml, y si hubieramos seleccionado application/json nos mostrará en formato JSON. La ficha Headers muestra información de la cabecera de la respuesta del servidor, y en la ficha Http Monitor nos muestra la petición HTTP que se envió así como la respuesta recibida.

Salir del navegador y regresar al IDE.

Agregando GoogleMap

El objetivo de este ejercicio es agregar una funcionalidad de Google Map a nuestro servicio web RESTful.

Abrir la clase CustomerResource

Agregar el siguiente código:

    @GET
    @ProduceMime(value="text/html")
    public String getGoogleMap(){
        
        return "";
    }

Obtengamos una clave para usar Google Map desde aquí http://www.google.com/apis/maps/signup.html El URL que escribiremos para que genere nuestra clave será http://localhost:8080

En nuestro IDE, presionemos Ctrl+5 para ver el panel de servicios. Abramos el nodo Web Services, luego Google, después Map Service.

Arrastremos el nodo getGoogleMap y soltémoslo en el método que hemos creado en el paso 2. Justo antes del return "". El IDE nos mostrará una ventana con datos con ejemplo para ser utilizado en nuestra aplicación.

Le damos clic en "OK" y el IDE agregará el siguiente código automáticamente.
```
    @GET
    @ProduceMime(value = "text/html")
    public String getGoogleMap() {
        try {

            String address = "16 Network Circle, Menlo Park";
            java.lang.Integer zoom = 15;
            String iframe = "false";

            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
        //TODO - Uncomment the print Statement below to print result.
        //System.out.println("The SaasService returned: "+result.getDataAsString());
        } catch (Exception ex) {
            ex.printStackTrace();
        }

        return "";
    }
```
El IDE también ha creado los paquetes org.netbeans.saas y org.netbeans.saas.google que contienen las siguientes clases y recursos
- RestConnection - Una clase que envuelve a HttpUrlConnection
- RestResponse - Un clase que envuelve las respuestas HTTP
- googlemapservice.properties - Un archivo de propiedades que almacenará la clave para manejar el GoogleMap.
- GoogleMapService - Un servicio que envuelve los métodos que usa RestConnection y llama al servicio GoogleMap.

En el bloque try de getGoogleMap() reemplacemos las líneas comentadas con lo siguiente:

return result.getDataAsString();

Ahora nuestro método lucirá así:

    @GET
    @ProduceMime(value = "text/html")
    public String getGoogleMap() {
        try {

            String address = "16 Network Circle, Menlo Park";
            java.lang.Integer zoom = 15;
            String iframe = "false";

            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);

            return result.getDataAsString();
        } catch (Exception ex) {
            ex.printStackTrace();
        }

        return "";
    }

Abrimos el archivo googlemapservice.properties y pegamos la clave del API que hemos generado en el paso 3.

Hacemos clic derecho en el nodo del proyecto CustomerDB y seleccionamos Test RESTful Web Services. El IDE desplegará nuevamente la aplicación y la abrirá en el navegador web.

Hacemos clic en el enlace customers del lado izquierdo. Luego hacemos clic en el botón "Test". Se mostrará la tabla de los clientes.

Desde esta tabla de resultados, hagamos clic justo donde dice /customers/1/. Se abrirá una página para probar el resultado de este cliente. Seleccionamos de la lista desplegable MIME la opción text/html. Y le damos clic en Test. El GoogleMap se mostrará en la calle que le indicamos.

Pudimos haber cambiado la dirección en el método getGoogleMap() para que apuntase a la dirección que querramos. Por ejemplo, Lima.

La dirección que hemos puesto por hardcode se mostrará en todos los registros de la base de datos. Lo que haremos ahora será modificar el método getGoogleMap() para que muestre el mapa de cada registro del cliente según corresponda.

    @GET
    @ProduceMime(value = "text/html")
    public String getGoogleMap() {
        try {
            Customer c = getEntity();
            String address = c.getAddressline1() + " " + c.getAddressline2() + " " +
                    c.getCity() + " " + c.getState() + " " + c.getZip();

            java.lang.Integer zoom = 15;
            String iframe = "false";

            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);

            return result.getDataAsString();
        } catch (Exception ex) {
            ex.printStackTrace();
        }finally{
            PersistenceService.getInstance().close();
        }

        return "";
    }

Nuevamente hacemos clic en "Test RESTful" y examinaremos todos los registros de los clientes. Este, por ejemplo, corresponde al cliente con id=149

Recursos

La aplicación que utilicé para este ejemplo se puede descargar desde aquí http://diesil-java.googlecode.com/files/customerdbRESTful.tar.gz.

Buscar este blog

Apuntes de Java