NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Antes que nada, podrás encontrar todo el código fuente en GitHub: https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/HTTP%20method%20extensions/api

Para estos casos, JAX-RS nos ofrece la anotación @HttpMethod  que nos sirve para crear un nuevo método, esta anotación la tendremos que implementar sobre una anotación personalizada. Digamos que requerimos implementar un nuevo método que nos permite bloquear un recurso para que cualquier otro consumidor del API no pueda modificarlo, para esto, podríamos crear un método HTTP llamado LOCK, veamos cómo quedaría:

package api.methods;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.ws.rs.HttpMethod;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {

}

No quiero entrar en los detalles sobre como crear una anotación, pues no es el tema central de este artículo, pues lo que solo nos centraremos en lo que es realmente necesario para crear un nuevo método HTTP. Como vemos, hemos creado una nueva anotación llamada LOCK, esta a su vez, implementa la anotación @HttpMethod , la cual recibe como parámetro el nombre del número método HTTP que vamos a implementar, en este caso “LOCK”.

Finalmente, solo restaría implementar un método que implemente la interface @LOCK :

@LOCK
@Path("{userId}")
@Produces(MediaType.TEXT_PLAIN)
public Response lockUser() {
    return Response.ok("User loked").build();
}

Como vemos, en el método anterior, solo debemos anotar la función con @LOCK  y JAX-RS será lo suficientemente inteligente como para detectar que estamos utilizando el método HTTP LOCK.

Una vez implementado, solo restaría probar que el servicio realmente funciona, para ello utilizamos Restlet para probar el servicio:

Hay que tomar en cuenta que los métodos HTTP predefinidos en JAX-RS nos servirán para prácticamente para el 100% de los casos, por lo que no es recomendable implementar un método HTTP solo por hacerlo. Si bien, no es recomendable crear métodos HTTP solo por crearlo o por tener un método proprio, sí que hay dos casos donde se recomienda crear nuestros propios métodos:

1. Cuando estamos creando alguno protocolo nuevo que requiera de la implementación de nuevos métodos.
2. Cuando alguna aplicación de terceros sobre la cual no tenemos control, nos solicite la creación de un servicio que responda en algún método determinado.

Conclusiones

Hemos visto como JAX-RS es lo bastante extensible para crear fácilmente nuevos métodos HTTP, aun que como ya vimos, debemos ser cuidados al momento de definir un nuevo método, pues crearlo solo por crearlo, puede ser un error que complique nuestra API.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Entender los métodos HTTP es fundamental para comprender la forma en que funciona la arquitectura REST, pues mediante los métodos le indicamos al servidor la forma en que debe de tratar una determinada petición, dicho esto, una misma URL puede ser tratada de forma diferente por el servidor.

HTTP define una gran cantidad de métodos que son utilizados para diferentes circunstancias, por lo que trataremos de listar lo más relevantes y más utilizamos en la construcción de servicios REST, los métodos son los siguientes:

• GET: Es utilizado únicamente para consultar información al servidor, muy parecidos a realizar un SELECT a la base de datos. No soporta el envío del payload
• POST: Es utilizado para solicitar la creación de un nuevo registro, es decir, algo que no existía previamente, es decir, es equivalente a realizar un INSERT en la base de datos. Soporta el envío del payload.
• PUT: Se utiliza para actualizar por completo un registro existente, es decir, es parecido a realizar un UPDATE a la base de datos. Soporta el envío del payload.
• PATCH: Este método es similar al método PUT, pues permite actualizar un registro existente, sin embargo, este se utiliza cuando actualizar solo un fragmento del registro y no en su totalidad, es equivalente a realizar un UPDATE a la base de datos. Soporta el envío del payload
• DELETE: Este método se utiliza para eliminar un registro existente, es similar a DELETE a la base de datos. No soporta el envío del payload.
• HEAD: Este método se utilizar para obtener información sobre un determinado recurso sin retornar el registro. Este método se utiliza a menudo para probar la validez de los enlaces de hipertexto, la accesibilidad y las modificaciones recientes.

Hasta aquí los métodos más utilizados en la construcción de servicios REST con JAX-RS, sin embargo, existen algunos métodos más que son interesantes conocer, pues no los encontraremos al momento de depurar o analizar el tráfico de red.

• CONNECT: Se utiliza para establecer una comunicación bidireccional con el servidor. En la práctica no es necesario ejecutarlo, si no el mismo API de HTTP se encarga de ejecutarlo para establecer la comunicación previo a lanzar alguna solicitud al servidor.
• OPTIONS: Este método es utilizado para describir las opciones de comunicación para el recurso de destino. Es muy utilizado con CORS (Cross-Origin Resource Sharing) para validar si el servidor acepta peticiones de diferentes origines.

A pesar de que los métodos están diseñados para realizar ciertas acciones, la realidad es que nada impide que los utilices de forma errónea, es decir, fácilmente podrías utilizar el método DELETE para consultar o el POST para eliminar un recurso, si bien, el API funcionará, el desarrollador se volverá loco al intentar entender como funciona el API, es por este motivo que debemos entender y tener mucho cuidado en la forma en que implementamos los métodos.

A pesar de que existe una gran cantidad de método HTTP, la implementación de JAX-RS solo implementa los que son realmente utilizados para crear servicios REST. Para implementar un método HTTP con JAX-RS solo es necesario anotar un método con cualquiera de las siguientes anotaciones del paquete javax.ws.rs :

• @GET
• @POST
• @PUT
• @DELETE
• @HEAD
• @OPTION

Por ejemplo, para crear un servicio que retorne todos los Usuarios, podríamos crear un método como el siguiente:

@GET
public Response findAllUsers() {
    List<Users> users = userDAO.getUsers();
    return Response.ok(users ).build();
}

Antes de comenzar, te cuento que puedes descargar el código completo en https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/M%C3%A9todos%20HTTP/api

De la misma forma, podríamos crear cualquier otro método y anotarlo con el método que necesitemos. Para comprobar cómo funcionan los métodos, vamos a crear un servicio REST que nos permite tener las operaciones básicas para realizar un CRUD (Altas, Bajas, Cambio, Consulta en inglés).

package api.services;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.HEAD;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;

import api.domain.User;


@Path("/users")
@Consumes(value= MediaType.APPLICATION_JSON)
@Produces(value = MediaType.APPLICATION_JSON)
public class UserService {
	
	//User database pre-initialization
	private static final List<User> users = new ArrayList<>();
	
	static {
		users.add(new User(1L, "oscar", "1234"));
		users.add(new User(2L, "juan", "1234"));
		users.add(new User(3L, "maria", "1234"));
	}
	
	
	@GET
	public Response findAllUsers() {
		return Response.ok(this.users).build();
	}
	
	@POST
	public Response createUser(User userRequest) {
		userRequest.setId(users.size()+1l);
		this.users.add(userRequest);
		return Response.ok(userRequest).build();
	}
	
	@PUT
	public Response updateUser(User userRequest) {
		List<User> found = this.users.stream().filter(
                    x -> userRequest.getId() == x.getId()).collect(Collectors.toList());
		
		//Throws error in case of the user not found
		if(found.isEmpty()) 
                    return Response.status(Status.BAD_REQUEST).entity("User not found").build();
		
		User updateUser = found.get(0);
		updateUser.setPassword(userRequest.getPassword());
		updateUser.setUsername(userRequest.getUsername());
		return Response.ok(updateUser).build();
	}
	
	@DELETE
	@Path("{userId}")
	public Response deleteUser( @PathParam("userId") long userId) {
		System.out.println("userId ==> " + userId);
		List<User> found = this.users.stream().filter(
                    x -> userId == x.getId().longValue()).collect(Collectors.toList());
		
		//Throws error in case of the user not found
		if(found.isEmpty()) 
                    return Response.status(Status.BAD_REQUEST).entity("User not found").build();
		
		User updateUser = found.get(0);
		this.users.remove(updateUser);
		return Response.noContent().build();
	}
	
	
	@HEAD
	public Response pingUsersService() {
		return Response.noContent().header("running", true).build();
	}
	
}

Como podrás apreciar, no estamos utilizando una base de datos real para guardar los cambios, pues no es el propósito en este punto, más bien, queremos enfocarnos en la forma en que los métodos son declarados, dicho esto, pasemos a analizar cómo funciona:

Inicialización del servicio

En primer lugar, podemos apreciar que el servicio responde en el path /users, lo cual podemos comprobar en la anotación @Path  a nivel de clase. Por el momento no profundizaremos en esto, pues más adelante tendremos una sección especial para explicar cómo funcionan los paths. Por otra parte, tenemos una lista llamada users, la cual utilizaremos como un sustituto a la DB para ir guardando los nuevos usuarios, actualizar o borrar los existentes. De entrada, iniciamos la lista con 3 usuarios.

Las anotaciones @Consumes  y @Produces  las utilizamos para indicar que él payload recibido y enviado como respuesta serán en formato JSON respectivamente. En otra sección de esta guía profundizaremos en el tema, por lo que por ahora no es necesario entender del todo esta parte.

Consulta de todos los usuarios (@GET)

El método findAllUsers es utilizado fue desarrollado para retornar todos los usuarios que tengamos registrados. Como ya hablamos anteriormente, de inicio tendremos 3 usuarios precargados, por lo que podremos comprobar si realmente funciona. Para la prueba utilizaremos el plugin de Chrome llamado Restlet, pero podrías utilizar otros programas como SOAPUI.

En la imagen podemos apreciar claramente que, al ejecutar el servicio, este nos regresa un array con los 3 usuarios que se pre-cargaron.

Crear un nuevo usuario (@POST)

De la misma forma en la que consultamos los usuarios existentes, podemos crear nuevos mediante el método POST. La única diferencia, es que es necesario enviarle en el payload el username  y el password  con el que se deberá crear, el ID será auto generado.

Como resultado de la ejecución, tenemos un nuevo usuario creado, podemos comprobar que es nuevo por el ID que se va generando de forma secuencial.

Actualización de un usuario existente (@PUT)

De la misma forma en que acabamos de crear un usuario, podemos actualizar sus datos mediante el método PUT. Para comprobar de que el usuario es actualizado, podremos observar que el ID del mismo no cambiara, y en su lugar, solo se actualizara el username  y el password . Como vamos a actualizar el registro, es necesario enviarle el ID como parámetro.

Eliminar un usuario (@DELETE)

El caso del delete es un poco diferente, pues como este método no soporta enviarle el payload, es necesario enviarle el ID del usuario a eliminar de otra forma. En este caso, vamos a enviarle el ID como parte de la URL, es por ello, que agregaremos “/1” al final y agregaremos la anotación @PathParam  para indicarle a JAX-RS como debe de recuperar el ID. Más adelante en otra sección de este tutorial analizaremos cómo funcionan estos parámetros, por ahora no nos preocupemos por esto.

En este caso no hay necesidad de retornar nada, es por ello que vemos el mensaje de “NO CONTENT”.

Comprobar disponibilidad del servicio (@HEAD)

Finalmente, validaremos si el servicio está activo realizando una petición HEAD, el cual nos regresará el header “running” si está actualmente en funcionamiento.

Conclusiones

Como hemos podido comprobar, crear servicios REST que respondan en los diferentes métodos es sumamente simple, y solo falta anotar el método con la anotación adecuada para crear un nuevo servicio. Solo quedo pendiente comprobar el funcionamiento del método OPTION (@OPTION ) el cual tu podrías implementar como tarea.

Sin lugar a duda, los servicios REST ya se han convertido en la principal tecnología para construir servicios, superando con creces a los servicios SOAP o comúnmente conocidos como Web Services. A pesar de que REST ya es visiblemente la tendencia en el desarrollo de servicios, sigue existiendo una gran discusión acerca de si SOAP es mejor que REST o al revés, sin embargo, no quiera tocar este tema ahora, pues no es el tema central de este artículo, para eso he creado el artículo “SOA vs REST” donde discutimos sobre estas dos tecnologías y sus ventajas y desventajas.

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

Antes de comenzar, te cuento que puedes descargar el código completo en https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/M%C3%A9todos%20HTTP/api

Configurando el proyecto

Dicho este, pasemos ahora si a implementar un API REST con Java, para esto, será indispensable crear un proyecto de tipo WEB en tu IDE favorito, en este caso, vamos a crear un “Dynamic web project” en Eclipse, para esto nos dirigimos a file -> new -> Other en el menú superior:

Seleccionamos la opción Dynamic web Project y presionamos Next para iniciar con la configuración de la aplicación:

Una vez aquí, escribimos “api” como nombre del proyecto y seleccionamos nuestro servidor de aplicaciones de preferencia, en nuestro caso, utilizamos Wildfly 11 pero podrías utilizar cualquier otro que tengas disponible. Finalmente, presionamos “Finish” para concluir con la creación del proyecto. El siguiente paso será convertir nuestro proyecto a un proyecto Maven, con la finalidad de administrar más fácilmente nuestras librerías. Para ello, nos posicionaremos sobre el proyecto creado y presionaremos “click derecho“ para abrir las opciones del proyecto, estando allí, nos dirigimos a configure -> convert to Maven Project, tras presionar esto, saldrá una ventana para configurar el proyecto, a lo que simplemente daremos finalizar.

Tras realizar los pasos anteriores deberás ver el proyecto tal y como se ve en la imagen anterior. Podrás observar una pequeña “M” en el ícono del proyecto, señal de que se trata de un proyecto Maven.

El siguiente paso es configurar las librerías de JavaEE y Wildfly con la finalidad de que estén disponibles en nuestro proyecto, por lo que tendremos que ir al archivo pom.xml y agregar las siguientes dos librerías:

<dependency> 
    <groupId>javax</groupId> 
    <artifactId>javaee-api</artifactId> 
    <version>7.0</version> 
    <scope>provided</scope> 
    <type>jar</type> 
</dependency> 
<dependency> 
    <groupId>org.wildfly.core</groupId> 
    <artifactId>wildfly-server</artifactId> 
    <version>2.2.0.Final</version> 
    <scope>provided</scope> 
</dependency>

Guardamos los cambios y tendremos que esperar un momento hasta que Eclipse descarga todas las dependencias necesarias, para esto, verás un indicador de progreso en la parte inferior derecha de Eclipse. Una vez que ha finalizado, estamos listos para empezar a desarrollar.

Iniciando el desarrollo

Lo primero que debemos de hacer para iniciar nuestra API REST es indicarle el Path base desde el cual estará respondiendo nuestra API. Este path corresponde a la URL a partir de la cual se expondrá nuestros servicios. Para lograr esto, será necesario crear una clase que extienda de “Application”, esta clase puede llamarse como sea y puede colocarse en cualquier paquete, lo único importante es que extienda de Application y defina la anotación @ApplicationPath. En nuestro caso crearemos la clase RestApplication en el package api.

package api; 

import javax.ws.rs.ApplicationPath; 
import javax.ws.rs.core.Application; 

@ApplicationPath("/") 
public class RestApplication extends Application { 
}

Como podemos ver, hemos definido “/” como URL base, es decir que los servicios responderán a partir de la raíz del proyecto, pero tu podrías remplazarla por la URL base que más te guste, como por ejemplo “/api” o “/services”.

El siguiente paso será crear nuestro primer servicio, para lo cual deberemos crear una nueva clase, en este caso, crearemos la clase HelloWorldRest en el mismo paquete:

package api; 
import javax.ws.rs.Consumes; 
import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 
import javax.ws.rs.core.MediaType; 
import javax.ws.rs.core.Response; 

@Path("/helloworld") 
@Produces(MediaType.APPLICATION_JSON) 
@Consumes(MediaType.APPLICATION_JSON) 
public class HelloWorldRest {               

    @GET  
    public Response sayHello() {     
        return Response.ok("Hello World desde el API REST",MediaType.APPLICATION_JSON).build();   
    } 
}

Como podrás observar, esta es una clase común y corriente pero que tiene algunas anotaciones, las cuales serán reconocidas por el servidor de aplicaciones para finalmente exponer el servicio, analicemos para que esta cada una de ellas.

La anotación @Path indica la URL en la cual responderá este servicio, cabe mencionar que esta anotación se puede poner a nivel de clase y método, en este caso, al estar a nivel de clase, afecta a todos los servicios que definamos, pero eso lo vamos a analizar más adelante.

Las siguientes dos anotaciones son para indicar que tipo de mensaje esperamos como entrada (consumes) y que tipo de mensaje vamos a responder (produces). En este caso, estamos indicando que esperamos JSON como entrada y que vamos a responder igualmente con JSON.

Finalmente, siguen los métodos, una clase puede tener más de un método, y cada método se puede exponer como un servicio independiente, sin embargo, en esta primera introducción empezaremos con uno. La anotación @GET le indica al servidor de aplicaciones que el método responde por el método GET únicamente. Adicional tenemos anotaciones para los demás métodos, como @POST, @PUT, @DELETE, etc. pero estos los estaremos analizando más adelante.

Podrás observar que el método responde con un tipo llamado Response, esta es una clase de utilidad que nos proporciona el API de JAX-RS para convertir fácilmente un objeto en un JSON en nuestro caso. Esta clase nos proporciona el método ok, el cual nos crea una respuesta con status 200, es decir, respuesta exitosa, la cual recibe el mensaje que queremos responder y el tipo de datos del mensaje, en nuestro caso JSON.

Probando nuestro Hello World

En este punto hemos terminado nuestro primer servicio, por lo que solo resta desplegarlo y probarlo. Para desplegarlo, basta con presionar el click derecho sobre el proyecto y presionar Run As -> Run on Server, presionar siguiente y finalizar.

Si la aplicación desplego correctamente, podremos probar el servicio en la URL http://localhost:8080/api-0.0.1-SNAPSHOT/helloworld, esta URL la podrás ejecutar directamente sobre el navegador:

En este punto te estarás preguntando como es que se generó esta URL, por lo que explico a continuación:

La URL se forma con la siguiente formula: <server_path>:<port>/<app_context>/<app_path>/<service_path>

La sección <server_path> y <port> corresponde al host del servidor y el puerto en el cual responde, esto corresponde a Wildfly.

La sección <app_context> corresponde a la URL base que nos asigna el servidor de aplicaciones cuando desplegamos.

La sección <app_path> fue la que definimos en la anotación @ApplicationPath. En nuestro caso, al definirla como “/” quiere decir que responderá a partir de la raíz del proyecto.

Finalmente, <service_path> corresponde a la URL definida en la anotación @Path, la cual se definió como “helloworld”.

Conclusiones

Hasta este punto hemos aprendido a crear un proyecto web y configurarlo para que responda a nuestras solicitudes como un API REST, por lo que en la siguiente sección de esta guía aprenderemos a utilizar los demás métodos (POST, DELETE, PUT) y aprenderemos a configurar nuestras URL para responder a URL más complejas, por lo que te invito a que te suscribas a mi blog para hacerte llegar las actualizaciones.

Java 9 trae importantes novedades, pero todo sobre sale el sistema de módulos, para conocer todo acerca de java 9, te invito a veas mi articulo “Java 9 – Un análisis de las novedades” que publique en la revista Centripio Magazine, la cual puedes descargar de forma gratuita en aquí.

Como el título de este articulo lo dice, hablaremos de cómo implementar los WebSocket utilizado Java como BackEnd, pero cabe mencionar que todos los lenguajes de programación deberían de tener sus propias API’s para soportar conexiones del lado del servidor.  Los WebSocket fueron agregados a apartar de la versión Java EE 7 bajo la especificación JSR 356, es por ello que todos los Application Server certificados para Java EE 7 deberán de tener una implementación estándar de dicha especificación. Basta de charla y pasemos a cómo implementar un WebSocket con Java.

Implementando un WebSocket con Java

Para explicar cómo funcionan los WebSocket vamos a implementar un ejemplo muy simple, crearemos una barra de progreso la cual se cargará del valor 0 al 100 simulando que un proceso se está ejecutando en el BackEnd. En el formulario tendremos un botón que iniciara el proceso, cuando el usuario presione el botón, enviaremos un mensaje al BackEnd por medio del WebSocket, en ese momento, el BackEnd iniciara con un proceso de notificaciones el cual enviará por medio del WebSocket un mensaje con las actualizaciones de la barra de progreso. Este ejemplo está desarrollado con Java 8 y Wildfly 9.0.

Este ejemplo está compuesto de 4 archivos:

• html: página principal del proyecto, sobre la que mostraremos la barra de progreso.
• js: Archivo de JavaScript en donde está programado el WebSocket y el procesamiento de los mensajes de envío y recepción.
• css: archivo de clases de estilo (opcional).
• java: Clase donde implementamos el WebSocket Server con Java, esta se ejecuta del lado del servidor.

Todo el código del proyecto lo puedes descargar de GitHub: https://github.com/oscarjb1/ProgressWebSocket.git

Index.html

Primero que nada, veremos el documento index.html para entender como esta armada la pantalla:

<!DOCTYPE html>
<html>
    <head>
        <title>WebSocket Progress</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <script type="text/javascript"src="websocket.js"/></script>
        <link rel="stylesheet" type="text/css" href="styles.css">
</head>
<body>
    <section  class="container">
        <h1>WebSocket Progress</h1>
        <div>
            <div class="progress-container">
                <form id="form">
                    <input id="btnSubmit" type="button" value="start" onclick="formSubmit();"/>
                    <progress id="progress" value="0" max="100"></progress>
                    <label for="progress" id="lblProgress"></label>
                </form>
            </div>
        </div>
    </section>
</body>
</html>

Lo primero que hacemos en el Header es importar al archivo styles.css del cual no hay mucho que decir, salvo que es utilizado para darle una apariencia más agradable a la página, y el archivo websocket.js del cual hablaremos más adelante.

El siguiente punto importante es el formulario, en el definimos un botón que al presionarlo ejecutara la función formSubmit() que está definido en el archivo websocket.js, que iniciara con el proceso de carga del progress bar.

También tenemos un progress, el cual será actualizado a medida que el WebSocket reciba las notificaciones del BackEnd, para lo cual utilizaremos el ID (progress) para identificarlo más adelante. Finalmente, debajo del progress tenemos un label el cual será actualizado con el progreso del progress bar.

Tanto el progress como el label son actualizados por Javascript a medida que el servidor manda los datos por medio del WebSocket.

Websocket.js

Por su nombre, podríamos pensar que se trata de una librería o algún script ya desarrollado, pero la realidad es que es un Script totalmente custom y desarrollado a la medida para esta solución.

var socket = new WebSocket("ws://localhost:8080/ProgressWebSocket-1.0-SNAPSHOT/progress");
socket.onmessage = onMessage;

function onMessage(event) {
    var btnSubmit = document.getElementById("btnSubmit");
    btnSubmit.disabled = true;
    
    var progress = document.getElementById("progress");
    var data = JSON.parse(event.data);
    progress.value = data.value;
    
    var lblProgress = document.getElementById("lblProgress");
    if(data.value < 100){
        lblProgress.innerHTML = 'Progress: ' + data.value + '%';
    }else{
        btnSubmit.disabled = false;
        lblProgress.innerHTML = "Finish";
    }
    
}

function formSubmit() {
    socket.send("{\"start\":\"true\"}");
}

La primera línea es la más importante, pues en esta se establece la conexión con el servidor, la clase WebSocket es una clase estándar que nos permitirá comunicarnos con el Servidor de una forma simple, esta clase tiene como parámetro la URL sobre la cual escucha el BackEnd, más adelante veremos cómo está formada esta URL, por lo pronto asumamos que existe un WebSocket Server que está escuchando.

En la línea 2 definimos la función que procesara los mensajes entrantes, es decir, cuando el BackEnd envíe un mensaje al navegador, este lo atenderá por medio del método definido, en este caso, establecemos el método onMessage para procesar los mensajes entrantes.

En la línea 4 definimos el método onMessage el cual implementa toda la lógica de procesamiento de los mensajes entrantes, el parámetro event corresponde al evento recibido y mediante event.data es posible recuperar el mensaje que envió el Servidor. Veamos qué es lo que hace. Primero que nada, en las líneas 5-6 obtenemos la referencia el botón y lo deshabilitamos para impedir que se presione mientras esta en procesamiento. En la línea 8 convertimos el mensaje enviado por el Server en un Json para poderlo procesar. En las líneas 10-11 obtenemos una referencia al progress y actualizamos el valor de la barra de progreso, para lo cual establecemos la propiedad value por el valor enviado por el Servidor. En las líneas 13-19 establecemos el valor del label, indicando el progreso recibido por el servidor, en caso de finalizar (100%), la etiqueta cambia a Finish y el botón se habilitado nuevamente.

Finalmente, en las últimas líneas, tenemos el método formSubmit, el cual es ejecutado por el botón cuando es presionado, este método manda un mensaje dummy al servidor mediante el método send del WebSocket.

ServerDashboardWebSocket.java

Esta es la parte principal para implementar un WebSocket con Java, ya que desde aquí es de donde se aceptan las conexiones del navegador y se procesan los mensajes de envío y recepción.

package com.osb.progresswebsocket.socket;

import java.util.HashSet;
import java.util.Set;
import javax.enterprise.context.ApplicationScoped;
import javax.websocket.OnClose;
import javax.websocket.OnError;
import javax.websocket.OnMessage;
import javax.websocket.OnOpen;
import javax.websocket.Session;
import javax.websocket.server.ServerEndpoint;

/**
 * @author Oscar Blancarte <oscarblancarte3@gmail.com>
 */
@ApplicationScoped
@ServerEndpoint("/progress")
public class ServerDashboardWebSocket {

    private Set<Session> sessions = new HashSet<>();

    @OnOpen
    public void open(Session session) {
        System.out.println("Session opened ==>");
        sessions.add(session);
    }

    @OnMessage
    public void handleMessage(String message, Session session) {
        System.out.println("new message ==> " + message);
        try {
            for (int c = 0; c < 100; c++) {
                for (Session s : sessions) {
                    s.getBasicRemote().sendText("{\"value\" : \"" + (c + 1) + "\"}");
                }
                Thread.sleep(100);
            }
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

    @OnClose
    public void close(Session session) {
        System.out.println("Session closed ==>");
        sessions.remove(session);
    }

    @OnError
    public void onError(Throwable e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Primero que nada, observemos que esta es una clase común y corriente, no extiende ni implementa ninguna clase, sin embargo, esta anotada con @ApplicationScope y @ServerEndpoint. Si ya has trabajado con JavaEE es muy probable que conozcas la primera, la cual no pertenece al API de WebSocket, pero es utilizada para crear un Bean disponible durante toda la vida de la aplicación. La segunda, @ServerEndpoint es en la que debemos de poner atención, con tan solo marcar una clase con ella, le estamos diciendo al Application Server que esta se trata de un WebSocket Server el cual estará escuchando en la URL http://<HOST>:<PORT>/<APPLICATION>/progress, la última parte de la url (/progress) es la que definimos en la anotación @ServerEndpoint por lo que tenemos que tener cuidado de que coincida con la URL que definimos en el archivo websocket.js.

También podemos ver que tenemos una Set de Session. Las Session son objetos que representan las conexiones de los navegadores, por lo que tendremos un Set para no perder la referencia a todas las conexiones.

A continuación, veremos una serie de métodos anotados, estas anotaciones le dicen a Application Server que método debe de ejecutar ante cualquier evento. Veamos los diferentes métodos.

Método open, está marcado con la anotación @OnOpen y se ejecutara cada vez que una nueva conexión se establezca con el servidor, el parámetro Session representa la conexión y la almacenamos en el Set de sesiones.

Método close, esta anotado con @OnClose y se ejecutara cada vez que una sesión se desconecte. Recibe el objeto Session que se desconectó para poder identificarla.

Método onError, esta anotado con @OnError, y se ejecutara ante cualquier error, el error es enviado como parámetro.

Método handleMessage, anotado con @OnMessage, será ejecutado cada vez que llegue un nuevo mensaje de alguno de los navegadores. Este recibe como parámetro el mensaje enviado y el objeto Session que mando el mensaje. Este es el método más importante en nuestro ejemplo, porque una vez recibido un mensaje, iniciara una serie de envíos de mensajes al navegador. Observemos que haremos un ciclo del 1 al 100 y en cada interación enviaremos al Navegador un mensaje con el progreso, al finalizar cada interación, dormiremos el hilo 100 milisegundos para apreciar mejor como se llena la barra. Utilizamos el método getBasicRemote() para que nos regrese una implementación de envío asíncrono y seguido ejecutamos el método sendText, el cual se utiliza para mandar un mensaje de texto al navegador.

Resumen:

Repasemos como funciona todo, cuando entramos a la página, esta carga el archivo websocket.js y establece conexión inmediata con el Servidor, en este momento el método open de la clase ServerDashboardWebSocket.java es ejecutado para recibir la nueva sesión. Seguido, el usuario presiona el botón start y envía mediante el función websocket.send un mensaje al Servidor, el Servidor recibe el mensaje mediante el método handleMessage de la clase ServerDashboardWebSocket.java, el cual envía una serie de mensaje como respuesta al navegador, por su parte, el navegador procesa los mensajes entrantes mediante la función onMessage de JavaScript, en esta función se actualiza la barra de progreso.

Java Message Service es una especificación de la Java Community Process(JRS 914) la cual fue desarrollada originalmente para permitir a las aplicaciones Java comunicarse con los proveedores MOM o Middleware Orientado a Mensajes la cual buscaba los siguientes objetivos:

• Brindas un mecanismo de enrutamiento y entrega de mensajes.
• Entrega fiable de mensajes
• Soportar los patronos de entrega de mensajes Punto a Punto(P2P) y Publicador/Subscriptor (P/S)
• Brindar un mecanismo asíncrono de entrega de mensajes.

En el mercado podemos encontrar diferentes proveedores de JMS los cuales se encuentran embebidos en los principales Application Server como el caso de WebSphere, Wildfly, WebLogic, Glassfish, entre otros, sin embargo todos trabajan bajo el mismo estándar lo que permite que la comunicación entre ellos sea totalmente compatible.

La siguiente imagen muestra como JMS permite que las aplicaciones se pueden comunicar por medio de JMS.

Fig.1: Muestra el proceso por el cual las aplicaciones se comunican a través de JMS.

Aunque JMS es un potente proveedor de Mensajería requiere de la configuración de Colas o Temas para poder depositar lo mensajes de entrada.

Tanto las colas como los temas son muy utilizados en los ambientes distribuidos donde se requerimos una comunicación asíncrona o One Wey(Solo ida) entre los distintos componentes que conforman nuestra infraestructura sin embargo estos se diferencias de los servicios web debido a que los mensajes son colocados en Cola o Temas para luego ser distribuidos a los destinatarios por lo que cambia un poco la forma en que los mensajes son administrados.

Estructura de un mensaje JMS

Al igual que todo protocolo de comunicación los mensajes JMS tiene una Taxonomía la cual se debe de respetar para que los mensajes sea enviados y respondidos de forma correcta.Los mensajes JMS tiene la siguiente estructura:

Header

El Header o cabecera es la parte que contiene todas las propiedades que son necesarias para JMS pueda operar y procesar lo mensajes de forma correcta, Es en esta sección donde es establece el identificador de la conversación(CorrelationID ),Fecha de expiración(Expiration),Tipo de mensaje(Type), Destino al cual deberán responder el mensaje(ReplyTo) y muchas mas las cuales puedes encontrar en la pagina de Oracle.

Body

Esta sección tiene el PayLoad o carga útil la cual representa el mensaje que queremos enviar, Este mensajes puede ser una Map, Texto plano, XML, un Objeto Java, O un Stream o incluso un mensaje personalizado. Lo importante es que esta sección contiene lo que realmente queremos comunicar al destinatario.

Una vez explicado a grandes rasgos podemos pasar a explicar que son las Colas(Queue) y Temas(Topics).

Colas (Queue)

Las colas son las mas utilizadas ya que los mensajes van dirigidos a un único receptor por lo cual, cuando un cliente se conecta a JMS y solicita el mensaje este es entregado pero es eliminado de la Cola por lo que si otra cliente busca el mensaje ya no lo encontrara. Este patrón es conocido como Punto a Punto(P2P)

Te invito a ver mi artículo Estructura de datos Queue para aprender más acerca de las colas.

Estructura de datos – Queue (Cola)

En este tipo mensajes hay que tener un cierto cuidad a la hora de solicitar los mensajes ya que si recuperamos un mensaje equivocado el destinatario real ya no lo podrá recibir y pero a un , El remitente jamas recibirá su respuesta.(JMS Permite tener varios clientes solicitando mensajes a la misma Cola)

Fig.2: Como podemos apreciar en la imagen al único que se le entrega el mensaje  es aquel al que fue dirigido y las demas aplicaciones no son notificadas.

Cuando utilizar Colas:

Las colas son utilices cuando queremos enviar un mensaje a un destinataria único para ser procesado, un ejemplo seria mandar una solicitud de crédito al sistema de crédito(por ponerle un nombre). o simplemente para desacoplar dos sistemas los cuales no queremos que se conozcan sin embargo lo único que conocen los dos es el formato en que se tendrá que hacer la comunicación ( Aquí explico esto )

Temas(Topics)

Por otra parte tenemos lo temas los cuales trabajan de una forma distinta que las Colas pues estos a diferencia de que el mensaje solo es entregado a un único receptor lo Temas pueden enviar el mensaje a Todos los clientes que estén suscritos al Tema de esta manera los Temas(Topics) Siguen el patrón de Publicador/Subscriptor.

Fig.3: Como podemos apreciar todos los suscriptores que estén suscritos al Tema(Topic) recibirán una copia del mensaje.

Cuando utilizar Temas(Topic)

Los Temas son buenos cuando queremos notificar o compartir información a múltiples destinatarios. Por ejemplo, Si tu estas suscrito a mi blog, Cada vez que yo publique un nuevo Post seras notificado por correo electrónico junto con todos los demas que estén suscritos, esto no es precisamente JMS pero es un ejemplo de donde mas de un destinatario reciben la misma notificación.

¿Crees que JMS juega un papel importante en Java o crees que es una herramienta fácilmente sustituida por otras cosas?

*Recuerda que si te gusto este artículo, compártelo y suscribete al blog para recibir todas las actualizaciones por medio de tu correo electrónico.