Ejecutar API para entornos distintos

Ahora ya tenemos dos entornos y no parece cómodo estar cambiando los archivos de propiedades por ejemplo para ejecutar la API usando una BD u otra. Spring tiene la capacidad de activar perfiles que pueden modificar entre otras cosas los beans o propiedades que use la aplicación.

Esta entrada no tratará sobre usar perfiles, pero valiéndonos de ellos, vamos a ejecutar nuestra API apuntando a una BD o a otra en función del perfil/entorno donde queramos ejecutar.

Vamos a mantener el fichero de propiedades de desarrollo (el que usa H2) para el perfil por defecto y nos vamos a crear otro fichero llamado application-prod.properties para las propiedades que quiero sobrescribir para este perfil (y que tendrá las credenciales de Postgre).

El fichero application-prod.properties quedaría así:

spring.datasource.url=jdbc:postgresql://kandula.db.elephantsql.com:5432/usuario
spring.datasource.username=usuario
spring.datasource.password=password
spring.datasource.driver-class-name=org.postgresql.Driver

hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

logging.level.es.lanyu=INFO

Y ahora vamos a duplicar nuestra configuración de ejecución y le vamos a poner un nombre que quede claro que es para producción. En esta configuración vamos a añadir una propiedad a nuestra JVM que es la de spring.profiles.active=prod. En la casilla correspondiente añadimos esto precedido de -D:

-Dspring.profiles.active=prod

Si ejecutamos con la nueva configuración de ejecución esta propiedad va a estar establecida, pero nuestra ejecución de bootRun no la cogerá. Vamos a hacernos una tarea que coja ese valor y lo establezca en la tarea bootRun. Añadimos este código a nuestro build.gradle:

task cloneJvmProfile {
    ext.profile = System.getProperty("spring.profiles.active")
    if (profile != null) {
        println "Setting $profile profile in bootRun"
        bootRun.systemProperties.put("spring.profiles.active", profile)
    }
}

Ahora ya podemos ejecutar nuestra anterior configuración de ejecución en Eclipse para levantar la API apuntando a H2 o usar la nueva para apuntar a Postgre.

Del mismo modo ahora se puede establecer el perfil a usar en Heroku para que use el de producción y ya no tenemos que cambiar nuestros ficheros .properties. Nos vamos a nuestra app de Heroku > Settings > Config Vars y añadimos la clave valor siguiente:

SPRING_PROFILES_ACTIVE = prod

Puedes conseguir el código hasta aquí en su repositorio.

Wildcards

Para terminar esta introducción a genéricos nos faltaría ver las wildcards que nos permiten poder definir un tipo variable usando como identificador del parámetro el carácter "?".

Es muy habitual verlo en la firma de los métodos para admitir cualquier Collection que admita un tipo de elemento o cualquiera de los subtipos de ese elemento, ya que Collection<Vehiculo> no es asignable a Collection<Coche>. En este ejemplo vamos a definir un método que admita esos dos tipos de colecciones:

private static void imprimirFlota(Collection<? extends Vehiculo> vehiculos) {
    vehiculos.forEach(System.out::println);
}

Su utilidad la vemos a continuación:

Collection coleccionRaw = Arrays.asList(new Coche(), new CocheProducto("", "", 10000.0f));
Collection<Vehiculo> vehiculos = coleccionRaw;
//  Collection<Coche> coches = vehiculos; // Error
imprimirFlota(vehiculos);
Collection<Coche> coches = coleccionRaw;
imprimirFlota(coches);

NOTA: Puede parecer que lo mejor es no definir el tipo ya que "no tiene el problema" que tenemos si lo definimos. Eclipse nos dará un warning tanto al declarar la variable (dirá que debemos declararlo) como al asignarla (nos advierte que no se puede checkear la seguridad de tipo). En resumen, hay que definirlo por seguridad de nuestro código en tiempo de compilación y porque de lo contrario no tendremos acceso a los miembros más allá de los pertenecientes a Object.

Sin tener más conocimiento sobre genéricos no recomiendo usar las wildcards en otro contexto ya que lo más normal es que tengamos muchos problemas. No obstante se puede usar como guía estas guidelines.

Hay más conceptos sobre genéricos, de hecho hay libros enteros sólo sobre este tema con términos como type erasure, pero que no se van a ver en esta introducción de fundamentos, aunque hay que tenerlos presentes pues no conocerlos puede darnos quebraderos de cabeza (lo típico que te dice que no se puede implementar dos veces la misma interface; prueba a implementar Comparable<Coche> en la clase Coche y te encontrarás con el mensaje: "The interface Comparable cannot be implemented more than once with different arguments: Comparable<Vehiculo> and Comparable<Coche>" que lo causa el type erasure).

Genéricos (desde Java 5) al igual que streams o lambdas (desde Java 8) son grandes avances pero quedan fuera del alcance que se pretende en esta parte de fundamentos. Puedes encontrar más tutoriales en la página oficial de Oracle.

Limites en genéricos (boundary)

Cuando necesitamos limitar las opciones de un tipo variable podemos establecer los límites adecuados en la declaración del parámetro tipo. En nuestro ejemplo de Identificable vamos a obligar que el tipo T implemente Comparable<T>. El código quedaría así:

public interface Identificable<T extends Comparable<T>> {

    T getId();

}

De esta forma sólo va a poder admitirse tipos que se encuentren dentro de los límites. Podemos probarlo intentando asignar a T un tipo que no sea comparable (aunque sea absurdo prueba con ProductExterno por ejemplo).

Ésto nos permite contar con otros miembros garantizados, en este caso podemos usar el método compareTo(Identificable<T> identificable) y podríamos definir un orden natural para todos los identificables usando el método getId(). El código definitivo sería:

public interface Identificable<T extends Comparable<T>> extends Comparable<Identificable<T>> {

    T getId();

    @Override
    default int compareTo(Identificable<T> identificable) {
        return getId().compareTo(identificable.getId());
    }
}

NOTA: Para que fuera correcto tendríamos que quitar la implementación de Comparable<Vehiculo> en la clase Vehiculo por el concepto type erasure que se menciona en la siguiente entrada.

Los límites no se ciñen a un único tipo, puedes hacer una composición de ellos (pero que sea posible, no puedes decir que sea de más de una clase siendo que no existe la herencia múltiple). En este caso voy a definir un tipo T en un método para que admita Identificable<Long> y Arrancable:

public static void main(String[] args) {
    admiteCoche(new Coche());
}

private static <T extends Identificable<Long> & Arrancable> void admiteCoche(T identificableArrancable) {
    System.out.println(identificableArrancable.getId());
    identificableArrancable.arrancar();
}

En este caso admitirá Coche, pero no Moto (ya que no es Identificable). La definición del tipo parámetro debe hacerse antes del tipo retorno ya que podría usarse T para el retorno y debería estar definido ya en ese caso.

Cuando en el límite quiero añadir una clase debo poner la clase la primera y luego irían todas las interfaces que hagan falta (intenta hacerlo al revés). Éste es un ejemplo pidiendo un Coche y Comerciable, con lo que sólo admitirá un CocheProducto:

private static  <T extends Coche & Comerciable> void admiteCocheProducto(T cocheComerciable) {
    System.out.println(cocheComerciable.getPrecio() + "|" + cocheComerciable.getClass());
}

Como vemos siempre se define un tipo parámetro que termina definiéndose y, dentro de su scope se mantiene fijo (puede ser definido en una clase que implemente un tipo genérico o tomado de un parámetro en un método/constructor). Sin embargo existe la opción de no definir un tipo específico y dejar que se admita sin hacer la declaración de tipo parámetro. Ésto se conoce como wildcard y lo vemos en la siguiente entrada.

Tipo variable

Para rematar esta parte de fundamentos vamos a ver el tipo por referencia que nos falta que es el Tipo Variable. Lo hemos usado al utilizar interfaces como Collection o Comparable. Ahora vamos a aprender a definirlo. Como dice la documentación, el tipo variable es introducido por la declaración de un parámetro tipo en una clase, interface, método o constructor genérico.

Esto quiere decir que en nuestro código vamos a referirnos a un tipo por su identificador dentro de su ámbito (scope) pero sin definir qué tipo concreto es. Podemos aplicarle unos límites (por ejemplo decir que debe cumplir con una interface, heredar de una clase o una mezcla de ello) como veremos en la siguiente entrada.

En este caso voy a tomar como ejemplo un identificador para una clase. Puede que no tenga claro el tipo que quiero usar para identificarlo, podría ser un número, un String o cualquier otro. Al no tener claro el tipo podría verme bloqueado a no poder seguir programando, sin embargo desde que existen los tipos variables puedo hacer código genérico reutilizable para distintos tipos.

Así pues me voy a crear una interface genérica que refleje esto:

public interface Identificable<T> {

    T getId();

}

Como vemos se marca un tipo T que por defecto puede ser de cualquier tipo. La sintaxis es rodeándolo por los caracteres < y > siendo habitual usar la letra T. Si se necesitan varios parámetros de tipo habría que usar más letras (también podías usar un identificador distinto a una única mayúscula). Otros ejemplos típicos si hay que usar más de un parámetro tipo son usar R para tipos retorno, K para claves o V para valores (ver ejemplos en las interfaces funcionales de Java 8). Ahora podemos usarlo añadiendo un id a Coche. En mi caso voy a identificar los coches por la matrícula así que T sería un String. El código quedaría así:

public class Coche extends VehiculoConRuedas implements Identificable<String> {

    ...

    @Override
    public String getId() {
        return getMatricula();
    }

}

No obstante, podía plantearse escenarios muy habituales donde una matrícula no sería el identificador que se necesitaría. Podría cambiarlo rápidamente a un Long:

public class Coche extends VehiculoConRuedas implements Identificable<Long> {

    ...

    private Long id;

    @Override
    public Long getId() {
        return id;
    }

}

Como podemos observar, al cambiar la definición de T el método anteriormente implementado ya no sirve y debe devolver el nuevo tipo Long. Al ser tipos por referencia se pide que T sea un tipo por referencia, es decir, no puedo usar como tipo variable un tipo primitivo, si lo intentara me saldría un error y no compilaría.

No obstante muchas veces no sirve con dejar completamente abierto T si quiero implementar código ya que sólo podríamos contar con los miembros de Object. Por ejemplo con Collection o Comparable no pasa nada porque debe admitir todo, pero en nuestro ejemplo si quisiéramos implementar por defecto un orden natural usando T deberíamos limitarlo a un Comparable<T>. Cómo se hace lo vemos en la siguiente entrada.

Integrando con código externo

En las entradas anteriores hemos visto las diferencias entre clases e interfaces. Por ahora hemos utilizado tipos nativos de Java pero hay otras muchas librerías que nos hacen la vida más fácil sin tener que reinventar la rueda.

Sin entrar en frameworks concretos y con la idea puesta que nuestro código tendrá que ampliar sistemas que ya estén en producción, añadir librerías de terceros o incluso integrar distintos componentes ¿Cómo podría utilizar tipos de otra librería sobre los que no quiero/puedo modificar el código fuente para integrarlos con mi negocio? ¿Cómo podría usar funcionalidades de terceros que me son útiles para utilizarlos con los objetos de mi negocio?

Sin entrar en cómo añadir librerías que lo veremos más adelante, en esta entrada vamos a simular que tuviera una clase y una interface de un tercero y cómo las integro en mi código.

Supuesto

Imaginemos que ahora tengo que integrar mi código sobre vehículos con una librería que me llevase el tema de comercializarlos. La idea es buscar una librería abierta que tenga mucho apoyo de la comunidad, que se vea que se está manteniendo (ver fecha último commit) y que los "issues" que se van generando son atendidos.

En nuestro caso no vamos a buscar una para desviarnos del tema, pero vamos a simular una que estuviera diseñada para el uso de interfaces. Ésto sabemos que nos permitiría implementar esas interfaces en nuestro código para utilizar sus métodos. La desventaja de esto es que nuestro código estaría acoplado a esa librería así que hay que decidir si de verdad la queremos como dependencia o si queremos poder cambiarla fácilmente en un futuro.

Caso 1.- Usar una clase externa dentro de mi negocio

Vamos a partir de una clase Product externa definida así:

package com.github.commerce;

public class Product implements Merchantable {

  private String description;
  private float price;

  @Override
  public String getDescription() {
    return description;
  }

  @Override
  public float getPrice() {
    return price;
  }

  public Product(String description, float price) {
    this.description = description;
    this.price = price;
  }

}

Y una interface Merchantable definida así:

package com.github.commerce;

public interface Merchantable {
  String DEFAULT_CURRENCY = "€";

  static Double priceToDouble(Merchantable merchantable) {
    return new Double(merchantable.getPrice());
  }

  String getDescription();
  float getPrice();

  default String getString() {
    return getDescription() + " (" + getPrice()
             + DEFAULT_CURRENCY + ")";
  }

}

NOTA: Tanto Product y Merchantable, así como el resto de código externo, vamos a suponer que no sería modificable por nosotros. De hecho vendría compilada como una dependencia aunque aquí la añadamos a nuestro código porque no hemos visto cómo añadir dependencias todavía.

Por nuestra parte tenemos una nueva interface Comerciable:

package vehiculos;

public interface Comerciable {

  String getDescripcion();
  float getPrecio();

}

Y un par de clases para implementar Comerciable. Una para utilizar nuestro tipo Coche:

public class CocheProducto extends Coche implements Comerciable {

  private float precio;

  @Override
  public float getPrecio() {
    return precio;
  }

  public CocheProducto(String modelo, String color, float precio) {
    super(modelo, color);
    this.precio = precio;
  }

  @Override
  public String getDescripcion() {
    return getModelo();
  }

}

Y otra para aprovechar el código nuestro con Product:

public class ProductExterno extends Product implements Comerciable {

  @Override
  public String getDescripcion() {
    return getDescription();
  }

  @Override
  public float getPrecio() {
    return getPrice();
  }

  public ProductExterno(String description, float price) {
    super(description, price);
  }

  @Override
  public String toString() {
    return getString();
  }

}

Ahora juntamos el código en este ejemplo y todo funciona correctamente:

public class UsandoLibreria {

  public static void main(String[] args) {
    ProductExterno productoExterno = new ProductExterno("CocheRaro", 25000f);
    CocheProducto cocheProducto = new CocheProducto("Seat", "Blanco", 16000);
	
    System.out.println("Usando Comerciable");
    Collection<Comerciable> productos = Arrays.asList(
                productoExterno,
                cocheProducto
        );

    productos.forEach(System.out::println);
    System.out.println(getValorTotal(productos));

  }

  private static float getValorTotal(Collection<Comerciable> comerciables) {
    return (float)comerciables.stream().mapToDouble(UsandoLibreria::toDouble).sum();
  }

  private static Double toDouble(Comerciable comerciable) {
    return new Double(comerciable.getPrecio());
  }

}

Ésta es la salida:

Usando Comerciable
CocheRaro (25000.0€)
Placa null - Seat (Blanco), 4 ruedas
41000.0

Como vemos en el ejemplo, al estar nuestro diseño orientado a interfaces, podemos usar tanto nuestras propias clases como otras implementando los métodos de nuestras interfaces. En general se trata de usar siempre la mínima interface en nuestras firmas de métodos.

Caso 2.- Usar nuestros tipos en código de terceros

Ahora vamos a reutilizar código de otros con nuestros tipos. Para ello vamos a añadir a CocheProducto la interface Merchantable:

public class CocheProducto extends Coche implements Comerciable, Merchantable {

  ...

  @Override
  public String getDescription() {
    return getDescripcion();
  }

  @Override
  public float getPrice() {
    return getPrecio();
  }

  @Override
  public String toString() {
    return getString();
  }

}

Y lo utilizamos en nuestro main:

System.out.println("\nUsando Merchantable");
Collection<Merchantable> merchantables = Arrays.asList(
            productoExterno,
            cocheProducto
    );
merchantables.forEach(System.out::println);
System.out.println(merchantables.stream().mapToDouble(Merchantable::priceToDouble).sum());

La salida es:

Usando Merchantable
CocheRaro (25000.0€)
Seat (Blanco) (16000.0€)
41000.0

Podemos observar un mismo "toString()" tanto en la clase que hereda de Product como la que hereda de Coche.

El ejemplo es muy sencillo, pero demuestra las posibilidades de orientar nuestras implementaciones siguiendo estas buenas prácticas. Por supuesto, al ser ProductExterno un Product puede usar todas las funcionalidades de la librería origen. Al autolimitarnos con que el código externo no es modificable (incluso teniendo acceso al código fuente) vamos a estar preparados para que nuestro código pueda ir admitiendo las modificaciones que se hagan desde proyectos externos que arreglen vulnerabilidades o proporcionen mejoras. Es bueno por tanto buscar repositorios que tengan en cuenta asegurar la retrocompatibilidad como lo hace Java.

Sé que esta entrada puede resultar un poco más complicada de entender que las anteriores, pero ya es el último contenido que se ve de fundamentos. Evidentemente se pueden hacer muchas cosas sin seguir estas prácticas, pero si se siguen el día de mañana se agradecerá el esfuerzo. Tómatelo como una inversión necesaria.

Comparación de objetos (equals vs Comparable y Comparator)

Vimos que equals es un miembro de Object. Sirve para comparar dos objetos y obtener si son iguales/equivalentes.

Por otra parte existen las interfaces Comparable y Comparator que sirven también para comparar dos objetos, pero las usaremos para ordenar pues nos pueden decir cuan iguales/distintos son dos objetos midiéndolo con un entero (int). Las diferencias entre estas dos formas de comparar las podemos resumir en:

1. Comparable/Comparator es una interfaz mientras que equals es un miembro de todos los objetos (todos tienen una implementación).
2. Todos los objetos pueden comparar su igualdad (usar equals), pero sólo los objetos con Comparable implementada tienen lo que se llama un orden natural con el que ordenarse por defecto.
3. Comparable/Comparator admiten un tipo variable T (el tipo que pueden comparar). La definición de este tipo variable afectara al parámetro de su único método a implementar: compareTo(T o)/compare(T o1, T o2).

La diferencia fundamental entre Comparable y Comparator es el dónde y el para qué de su funcionalidad:

• Dónde:
  • Comparable necesita implementar el método compareTo(T o) como miembro del objeto que se va a comparar con el parámetro o, y son del mismo tipo T (teniendo en cuenta que los subtipos son del tipo de su supertipo).
  • Comparator necesita implementar el método compare(T o1, T o2) como miembro del objeto comparador que se encargará de comparar o1 con o2: el comparador es un objeto independiente que no tiene relación con o1 ni o2.
• Para qué: Comparable va a establecer un orden natural para el tipo mientras que Comparator se puede usar para hacer una ordenación puntual, pudiendo tener varios comparadores para ordenar por distintos criterios.

equals nos dice si dos valores son iguales, Comparable/Comparator nos dice cuan iguales son y nos permite ordenar

¿Cómo funcionan?

El único método que debe implementar cada una debe devolvernos:

1. un número negativo si o1 es menor que o2,
2. cero si son iguales (no implica que o1.equals(o2) sea true) o
3. positivo si es mayor.

De esta forma podemos medir cuan distintos son dos objetos y por tanto ordenarlos, lo cual es imposible con equals que devuelve un boolean.

Se recomienda encarecidamente que ambos métodos sean coherentes entendido como: o1.compareTo(o2)/compare(o1, o2) == 0 debería dar el mismo resultado que o1.equals(o2).

¿Cuándo usamos cada una?

Desde mi experiencia yo tiendo a generar comparadores antes que a implementar Comparable. Mis motivos son:

1. Puedo ordenar un tipo incluso si no tengo acceso al código para implementar Comparable
2. Puedo disponer de varios comparadores como constantes (static final) en un tipo para poder ordenarlos fácilmente, mientras que sólo puedo tener una implementación para Comparable
3. Comparator es una interfaz funcional y puedes instanciarlos con lambdas desde Java 8. El código queda muy legible y compacto con lo que no es un problema crearlos como antiguamente que había que hacer un tipo sólo para eso.

Sólo se puede implementar Comparable una vez, si un supertipo ya lo tiene implementado habrá que sobrescribir el método compareTo si debe ser distinta implementación y las comparaciones dos-a-dos podrían salir inconsistentes (ver type erasure cuando se hable de genéricos).

El consejo definitivo es: haz un comparador a menos que el diseño de un código en concreto te obligue a implementar Comparable (por ejemplo que tenga que usarse el tipo como clave de un mapa ordenado o que un tipo genérico imponga la interface Comparable).

Si no estás obligado a usar Comparable mejor hazte un Comparator para tener el código de ordenamiento separado

Para ver el uso de Comparator termino la entrada añadiendo éste código al de la entrada anterior que ordena los vehículos por su color:

System.out.println("\nLista ordenada (por color):");
vehiculos.sort((v1, v2) -> v1.getColor().compareTo(v2.getColor()));
vehiculos.forEach(System.out::println);

Así queda más limpio y separado el código de vehículos y el de ordenación para un caso concreto. Si te fijas en los métodos de Comparator verás cómo han potenciado la interfaz desde Java 8 y lo fácil que es tener un comparador que ordene por orden inverso, usando una clave específica (Comparable) o que trate los valores null de forma distinta. Todo son facilidades.

Despliega tu API en la nube gratis

Ahora que tenemos nuestra API lista para ejecutarse vamos a ver cómo desplegarla en la nube. Básicamente tenemos que cambiar nuestra BD (ya no nos sirve con H2 en local) y exponer la API públicamente en red. Los servicios que voy a usar para ello son ElephantSQL para la BD y Heroku para la API. Para ello vamos a hacer lo siguiente:

1. Creo una base de datos en ElephantSQL
2. Cambio el datasource de JPA y el dialecto org.hibernate.dialect.PostgreSQLDialect. Puedes ver qué debes poner en la documentación de ElephantSQL para Java.
3. Una vez cambiado eso voy a cargar los datos de los participantes en la BD ya en la nube. Descomento las líneas del main que lo hacen y lanzo la API. Ya podré ver que todo funciona correctamente pero ahora ya no tengo H2.
4. Una vez cargada la BD y funcionando toca subir la API.
5. Creo una aplicación en Heroku. Se puede desplegar todo usando el CLI.
6. Lo más cómodo es enlazar el repositorio de GitHub donde tengamos el código fuente (para que se construya debe tener acceso a todas las dependencias, por eso ya cambiamos la dependencia datos-deportivos a un repositorio). Así incluso podemos tener nuestro despliegue continuo (cada commit se despliega)
7. Primero tenemos que subir nuestro código con los últimos cambios, pero sin las credenciales de la BD (¡ojo con subir credenciales!)
8. Una vez enlazado el repositorio ya veremos que podemos desplegar la aplicación. Pero nos faltan las credenciales para conectar con la BD. Vamos a ponerlas como una variable en Heroku para que la use sobrescribiendo lo que haya en el archivo de propiedades.
   

   DATABASE_URL: postgres://usuario:password@server.com:5432/usuario

9. Y con esto ya podemos darle a deploy.

Cuando termine de ejecutarse, si todo ha ido bien, podemos acceder a nuestra API RESTful en la url que nos proporcione Heroku. Todo en la nube, sin coste alguno y sin administrar ninguna máquina.

Puedes ver el código hasta aquí en su repositorio.

NOTA: Con el fin de Heroku gratis el 28 de noviembre de 2022, se propone usar como alternativa Railway.

Empaquetar la API en un fichero.jar

Ahora que ya tenemos nuestro MVP desde la entrada anterior vamos a ver cómo empaquetarlo todo. La idea es que podamos ejecutarlo desde cualquier máquina con la JVM.

Spring Boot nos proporciona una tarea a nuestro proyecto de gradle que se llama bootJar y que es suficiente con ejecutarla. Para ello podemos usar la pestaña "Gradle Tasks" en Eclipse o simplemente ejecutar la tarea bootJar con el mismo gradle wrapper que tenemos en nuestro proyecto. Para esto último usamos desde la carpeta raíz de nuestro proyecto el comando siguiente:

gradlew bootJar

Si todo va bien tendremos nuestro .jar en la carpeta /build/libs de nuestro proyecto:

Así lo ejecutamos en la consola con el comando:

java -jar datosdeportivosapi-VERSION.jar

Para que se pueda levantar el servicio se necesita tener la BD levantada.

Para cualquier duda dejarlo en los comentarios.

Código útil: clase ConfiguracionRest

Como hemos visto en las entradas anteriores, hemos añadido un link a un método personalizado pero de una manera muy manual y nos tocaría añadir otro más. No obstante, el código que se ha utilizado puede generalizarse más teniendo en cuenta lo siguiente:

1. Los métodos que queremos enlazar tienen la anotación @ResponseBody
2. Los parámetros que deben formar parte del path los anotaremos con @PathVariable.
3. Los parámetros que deben formar parte de la query string los anotaremos con @RequestParam.
4. Podemos configurar a qué recursos queremos añadirles enlaces en su /recursos/search y relacionarlas con su RecursoController que tenga los métodos a los que queremos enlazar.

Siguiendo esa guía podemos usar Reflection para conseguir toda la información y añadir los enlaces haciendo que:

1. Filtre el recurso para el que debe añadirse los links (sólo los registrados)
2. Recupere todos los métodos del Controller asociado a ese recurso
3. Filtre aquellos marcados con ResponseBody
4. Recupere el link con linkTo pasando como argumentos el valor "(" + nombre + ")" para cada PathVariable (se usan paréntesis para evitar el "escape" de las llaves)
5. Cambiamos los paréntesis por llaves en las variables de la ruta.
6. Utilice sólo los nombres de los parámetros RequestParam como query params
7. Use el nombre del método como rel

El código está en el gist para la clase ConfiguracionRest:

También incluye un filtro CORS (CorsFilter) para permitir cualquier petición y así poder realizar pruebas sin preocuparse de las políticas Cross-Origin por defecto.

Cómo usar el bean correctamente

En nuestro repositorio vamos a eliminar el código de la sesión anterior para sustituirlo por esta clase de configuración que añadimos a nuestra aplicación.

Ahora personalizamos nuestro bean para los links añadiendo al mapa de controladores para enlazar la entidad como clave (PartidoConId.class) y el controlador asociado como valor (PartidoController.class). De aquí se deduce que lo más simple es poner todos los métodos para una entidad en un único Controller.

Si se quieren añadir otros enlaces aparte de los aporta este bean, se puede crear otro bean del mismo tipo en otra clase de configuración y al final todos los enlaces convivirán en el mismo /search.

Puedes encontrar el código hasta aquí en su repositorio.

Este punto finaliza nuestro Producto Mínimo Viable (PMV/MVP) y establece la release v1.0.0. En el README del repositorio se pueden ver las instrucciones para ejecutar la API en local.

Rutas con @PathVariable

En esta entrada vamos a rematar la exposición de nuestros endpoints añadiendo variables a la ruta. Esto es muy normal cuando queremos referirnos a un recurso y nuestras rutas pueden tener fragmentos que sigan el patrón /recursos/:id.

En el endpoint expuesto la entrada anterior sólo hemos usado query params. En esta ocasión vamos a pedir los sucesos de un participante entre dos fechas y el id del participante estará en el path. La consulta ya está hecha en nuestro repositorio (SucesoDAO), pero no lo estamos exponiendo. Lo hicimos cuando vimos cómo personalizar rutas con @RestResource. Ésta anotación nos permitía cambiar el fragmento del path que se obtiene en /recursos/search e incluso personalizar los query params con @Param, pero no permite el uso de variables en el path. En este ejemplo queremos que el path sea /search/participante/{id}/entre-fechas.

Para esto vamos a tener que seguir usando @RequestMapping o cualquiera de sus variantes en un controlador. Como es una consulta sobre sucesos voy a crearme la clase SucesoController. El código se parece muchísimo al que vimos en la última sesión y queda así:

@RepositoryRestController
@RequestMapping(path = "/sucesos/search")
public class SucesoController {

    private SucesoDAO sucesoDAO;

    SucesoController(SucesoDAO sucesoDAO) {
        this.sucesoDAO = sucesoDAO;
    }

    @GetMapping("/participante/{id}/entre-fechas")
    @ResponseBody
    public CollectionModel<PersistentEntityResource> getSucesosConIdParticipanteEntreFechas(
            @PathVariable("id") String id,
            @RequestParam Instant comienzo, @RequestParam Instant fin,
            PersistentEntityResourceAssembler assembler) {
        List sucesos = sucesoDAO.findByIdParticipanteAndTemporalBetween(id, comienzo, fin);

        return assembler.toCollectionModel(sucesos);
    }

}

Me voy a centrar en lo nuevo. Si nos fijamos en el path aparece {id}. Cuando ponemos una parte del path entre llaves estamos indicando que se trata de una variable en el path y su nombre es el texto que hay dentro. Para hacer referencia a esa variable se usa @PathVariable pudiendo anotar un parámetro igual que hicimos con @RequestParam.

Para poder usarlo desde la ruta /sucesos/search nos toca modificar nuestro bean que procesa el recurso para búsquedas y añadirlo al código que ya tenemos para cuando el tipo gestionado sea SucesoConId. Esto empeora el mantenimiento así que, como lo prometido es deuda, en la siguiente entrada vamos a ver cómo añadir una configuración que nos descubra estos links personalizados automáticamente.

Puedes conseguir el código hasta aquí en su repositorio.

Añadir link a /resources/search

Para conseguir en nuestra API REST el nivel 3, HATEOAS, hypermedia o RESTful hace falta que nuestros enlaces se puedan autodescrubrir. Esto no lo digo yo. El padre de REST explica que hypermedia es una condición mínima para llamar a un servicio RESTful. Una traducción (por google) de lo que ha dicho Roy Fielding al respecto:

Me siento frustrado por la cantidad de personas que llaman a cualquier interfaz basada en HTTP una API REST. El ejemplo de hoy es la API REST de SocialSite. Eso es RPC. Grita RPC. Hay tanto acoplamiento en la pantalla que se le debe dar una calificación X.

¿Qué se debe hacer para dejar claro el estilo arquitectónico REST sobre la noción de que el hipertexto es una restricción? En otras palabras, si el motor del estado de la aplicación (y, por lo tanto, la API) no está siendo impulsado por hipertexto, entonces no puede ser RESTful y no puede ser una API REST. Período. ¿Hay algún manual roto en algún lugar que deba repararse?

Con esto claro, en nuestra API no hay ningún enlace que dirija al método que expusimos en la entrada anterior: no se puede autodescubrir, o conoces la URL o navegando no hay un camino hasta ella. Vamos a añadir un link a nuestro nuevo endpoint para que no se frustre Roy.

Para ello vamos a usar RepositorySearchesResource. Éste bean permite añadir links a todos los que se crean automáticamente por Spring Data Rest. Hay varias formas de hacerlo, aunque las que he encontrado por Internet normalmente usan la versión antigua de HATEOAS (ResourceProcessor como veíamos también en la documentación de la entrada anterior). Voy a hacerlo migrado ya a la versión actual y de la forma que me parece mejor por ser más reutilizable.

Me voy a crear un bean del tipo RepresentationModelProcessor<RepositorySearchesResource> en mi clase de configuración. Es decir, voy a indicar el modo en el que se debe procesar el recurso utilizado para las búsquedas. El código quedaría así:

@Bean
RepresentationModelProcessor<RepositorySearchesResource> searchLinks(RepositoryRestConfiguration config) {
    return new RepresentationModelProcessor<RepositorySearchesResource>() {

        @Override
        public RepositorySearchesResource process(RepositorySearchesResource searchResource) {
            if (searchResource.getDomainType().equals(PartidoConId.class)) {
                try {
                    String nombreMetodo = "getPartidosConParticipanteComo";
                    Method method = PartidoController.class.getMethod(nombreMetodo, String.class,
                            PersistentEntityResourceAssembler.class);
                    URI uri = org.springframework.hateoas.server.mvc.WebMvcLinkBuilder
                            .linkTo(method, null, null).toUri();
                    String url = new URI(uri.getScheme(), uri.getUserInfo(), uri.getHost(), uri.getPort(),
                            config.getBasePath() + uri.getPath(), uri.getQuery(), uri.getFragment()).toString();
                    searchResource.add(new Link(url + "{?txt}", nombreMetodo));
                } catch (NoSuchMethodException | URISyntaxException e) {
                    e.printStackTrace();
                }
            }

            return searchResource;
        }

    };
}

Lo importante de todo este código es que el objeto searchResource se usa para todos los /search. Eso quiere decir que si añadimos un enlace aparecerá en todos ellos. Si queremos añadir el enlace en sólo uno (en nuestro caso para partidos) debemos filtrar para que coincida con el tipo correcto: PartidoConId. Podría ponerse el enlace a mano, pero entonces cualquier cambio posterior nos obligaría a recordar que hay que cambiarlo aquí también.

Lo mejor es recuperar el enlace que apunta a un método. Voy a usar linkTo y le pasaré el método al que quiero apuntar y los parámetros con null (estos son para incluir valores en las variables del path y completar la URL, pero nuestro método sólo tiene query params).

NOTA: Para usar linkTo se puede usar la importación estática para evitar poner su paquete, pero lo he dejado en el código para que quede claro de dónde viene el método.

Lamentablemente, el link no incluye el basePath y hay que añadírselo (como dicen ellos: "por ahora") por eso se construye de nuevo la URI incluyéndolo. Para recuperar ese valor lo mejor es usar RepositoryRestConfiguration que puede ser inyectada en el método.

Ya con la información completa podemos añadir el enlace en searchResource incluyendo los query params.

Si ejecutamos veremos que nuestro enlace aparece al final de los que se han añadido automáticamente.

No obstante, supongo que a cualquiera le dolerá ver esos "magic number" y pensará que debe haber una forma más automática de hacerlo. Personalmente no la he encontrado y tiene sentido (no se puede saber cómo se van a añadir los endpoints porque hay varias formas). Si alguno encuentra algo oficial agradecería que lo compartiera en los comentarios para completar la entrada.

Además en la siguiente entrada voy a añadir otro endpoint usando una variable en el path y también habrá que añadir el link.

Para arreglar esta falta de automatización, después de la siguiente entrada voy a compartir una clase de configuración base que puede utilizarse de manera generalizada en los proyectos igual que hicimos con el jpa-config.xml y explicaré la forma en que debe usarse. Así veremos que sólo con eso detecta y añade este endpoint y el que veamos a continuación que incluye path variable (y es otro parámetro que debemos controlar).

Puedes obtener el código hasta aquí en su repositorio.

Exponer metodo con @RepositoryRestController

En la entrada anterior hemos añadido un método personalizado a nuestro repositorio para una consulta más compleja que las que nos resuelve JPA en automático. Incluso luego la hemos optimizado utilizando datos cacheados en memoria.

Pero para que los usuarios de la API puedan utilizarlo hace falta exponerla. Esto no es automático, si revisamos los links generados por HATEOAS no aparecerá. La funcionalidad está en la capa de persistencia pero no es parte de la interfaz de la API.

Lo tradicional es tener un @Controller donde se indica el @RequestMapping que corresponda para conducir la llamada HTTP hasta el método concreto y derivar a un @Service. Más adelante veremos con más detalle y compararemos esta forma con la que vamos a usar aquí. Ahora quiero centrarme en la forma de hacerlo con Data Rest.

En esta entrada se va a utilizar la anotación @RepositoryRestController para continuar dentro del módulo Data Rest. El javadoc lo deja muy claro:

Anotación para marcar los controladores Spring MVC proporcionados por Spring Data REST. Permite detectarlos fácilmente y excluirlos del manejo estándar de Spring MVC.
Esta anotación sólo debe ser utilizada por los controladores de aplicaciones que se asignan a los URI administrados por Spring Data REST, ya que los maneja una implementación especial que aplica funcionalidad adicional.

Esto la convierte en el camino correcto y así lo indica la documentación. Lamentablemente la documentación no está actualizada y sigue utilizando el HATEOAS antiguo (Resource/s) así que aquí se va a ver cómo hacerlo migrado ya a la versión actual.

Me creo una clase PartidoController en mi paquete de rest con el siguiente código:

@RepositoryRestController
public class PartidoController {

    private PartidoDAO partidoDAO;

    PartidoController(PartidoDAO partidoDAO) {
        this.partidoDAO = partidoDAO;
    }

    @GetMapping("/partidos/search/con-nombre-participante")
    @ResponseBody
    public CollectionModel<PersistentEntityResource> getPartidosConParticipanteComo(@RequestParam String txt,
            PersistentEntityResourceAssembler assembler) {
        List<PartidoConId> partidos = partidoDAO.getEventosConParticipanteConTexto(txt);

        return assembler.toCollectionModel(partidos);
    }

}

Al marcar la clase se excluyen de la gestión de Spring MVC (la que usa @RestController por ejemplo) y pasan a ser gestionados por Data Rest. Con ello se consigue:

1. El controlador utilizará la configuración basePath de Data Rest (en nuestro caso /api)
2. Se podrá inyectar en sus métodos el objeto PersistentEntityResourceAssembler. Este objeto va a permitir la creación de EntityModel o CollectionModel (lo que sustituye a Resource/s) en función de si hay que representar un elemento o una colección de elementos. Así la representación será la misma que la que se genera para el resto de métodos, dando consistencia a la API.

Hay otras dos anotaciones necesarias según se ve en la documentación:

• @GetMapping: usamos esta anotación que equivale a @RequestMapping(method=GET,...). Ambas sirven para indicar el endpoint que dirigirá hasta el método. La ruta la ponemos sin el basePath. Si se pone a nivel de clase el fragmento afecta a todos los mapeos internos.
• @ResponseBody: significa que el método devuelve una respuesta web. Si no se pone no se expondrá el endpoint. También se puede poner a nivel de clase para que todos los métodos de dentro tomen ese valor por defecto.

Ahora al arrancar la API podemos probar ese endpoint y ver que existe y funciona correctamente. Sin embargo si acudimos a /partidos/search no se va a mostrar y no se puede autodescubrir. En la próxima entrada vamos a ver cómo añadir este nuevo endpoint a los link de /partidos/search.

Puedes encontrar el código hasta aquí en su repositorio.

Añadir método personalizado en repositorio

Ya conocemos lo básico de Spring Data Rest y cómo nos facilita exponer los recursos que tenemos almacenados en nuestra BD con JPA. Sin embargo todos los métodos que hemos usado hasta ahora tienen una relación directa con las columnas de la BD (por ejemplo busco Participantes usando su campo nombre) y en nuestro proyecto seguramente habrá aspectos que no podamos solucionar con lo visto hasta ahora. Como ejemplo nos gustaría recuperar los Partidos de un Participante con un texto en su nombre. En este caso tenemos un problema: en la tabla PARTIDOS no están los nombres de los participantes, sólo sus ids y ya no es suficiente con usar los Query Methods de JPA para solucionarlo.

En este caso necesitamos hacer un método personalizado para nuestro repositorio.

Para implementar esta funcionalidad vamos a hacer lo siguiente:

1. Crear una búsqueda para buscar los participantes conteniendo un texto (eso ya lo tenemos: ParticipanteDAO.findByNombreIgnoreCaseContaining)
2. Con los participantes recuperados buscaremos los partidos en los que aparecen
3. Añadiremos todos los partidos de esos participantes a una lista
4. Esa lista será el payload de nuestra respuesta HTTP

Para añadir un método personalizado Data Rest permite que nuestro DAO se complete usando fragmentos implementados de varias interfaces, además de la que estamos usando JpaRepository. Esas interfaces tendrán los métodos que queremos añadir. En nuestro caso me creo la interface EventoDAOCustom:

public interface EventoDAOCustom<T extends Evento> {
    List<T> getEventosConParticipanteConTexto(String txt);
}

De esta forma esta interface me servirá para otro tipo de eventos, no sólo para partidos.
Ahora me creo una clase que implemente este método. Lo más importante es que debe tener el sufijo "Impl" e implementar nuestra nueva interface. Nos quedará así:

class PartidoDAOImpl implements EventoDAOCustom<PartidoConId> {

    @Autowired
    ParticipanteDAO participanteDAO;

    @PersistenceContext
    EntityManager entityManager;

    @Override
    public List<PartidoConId> getEventosConParticipanteConTexto(String txt) {
        List<Participante> participantes = participanteDAO.findByNombreIgnoreCaseContaining(txt);
        Set<PartidoConId> partidos = new HashSet<PartidoConId>();
        Query query = entityManager.createNativeQuery(
            "SELECT p.* FROM partidos as p " +
            "WHERE p.local = ?1 OR p.visitante = ?1", PartidoConId.class);
        participantes.forEach(p -> {
            query.setParameter(1, p.getIdentificador());
            partidos.addAll(query.getResultList());
        });

        return new ArrayList<PartidoConId>(partidos);
    }

}

Para implementar este método usamos ParticipanteDAO para recuperar los participantes y luego una Query que es bastante parecida a lenguaje SQL que ya conocemos como se ve en el ejemplo.

NOTA: la query necesita del EntityManager y lo inyectamos con @PersistenceContext.

Usamos la query para ir llamando a nuestra BD con cada participante que cumpla con el texto pasado y lo añadimos a un Set para que no se repita. Finalmente devolvemos todos los partidos. Podrían hacerse más cosas como ordenar por algún campo, etc...

Sólo nos queda añadir la interface a nuestro DAO para que Spring lo complete:

public interface PartidoDAO extends JpaRepository<PartidoConId, Long>, EventoDAOCustom<PartidoConId> {...}

Lo importante de todo esto es que puedo utilizar código propio para implementar aquello que ya se escapa de los Query Methods de JPA. Sin necesidad de añadirlo como bean ni nada parecido, Data Rest va a escanear las clases con el sufijo Impl (se puede configurar) buscando la implementación de EventoDAOCustom que no puede hacer automáticamente. Así irá formando con fragmentos de código el DAO completo.

Ahora probamos que todo funciona correctamente en nuestro main:

partidoDAO.getEventosConParticipanteConTexto("m").stream()
    .map(PartidoConId::toString)
    .forEach(log::trace);

Para que esto funcione de esta forma debemos indicar que este método es transaccional. Como habitualmente estas consultas personalizadas son lecturas de datos, marcamos toda la clase como sólo lectura.

@Transactional(readOnly = true)
class PartidoDAOImpl implements EventoDAOCustom<PartidoConId> {...}

NOTA: ver más sobre cómo funciona @PersistentContext y @Transactional.

Puedes conseguir el código hasta aquí en su repositorio.

Añadida la funcionalidad a nuestra persistencia, lo que nos falta es exponerla en nuestra API. En la siguiente entrada vamos a ver cómo hacerlo.

Práctica: mejorar cómo se consiguen los participantes
Ahora mismo si buscamos un equipo donde su nombre incluya una tilde en el fragmento buscado y no coincida en el valor de txt (ejemplo: buscando "?txt=atletico" no devolverá "Atlético...") parece que no obtenemos el resultado esperado. Se pide modificar el código para que no sólo sea IgnoreCase sino que también ignore las tildes.

NOTA: aparte de ParticipanteDAO tenemos otro origen de datos disponible para ello en forma de bean. Para facilitar el tratamiento de las tildes existe un método en lanyu.commons que se encarga de ello: StringUtils.eliminarTildes.

La solución está en github.

Personalizar endpoints con @RestResource

En estos momentos tenemos un servicio HATEOAS que puede ser descubierto navegando por sus enlaces desde el raíz. Sin embargo sólo hemos configurado las propiedades de @RepositoryRestResource. En nuestras aplicación probablemente querremos poder personalizar alguna URL (sobretodo de los métodos que nos hacemos con query methods de JPA), no permitir algunas operaciones (por ejemplo no dejar borrar un participante) o al menos no permitirlas para todos los usuarios (sólo podrá borrar el adminitrador).

Vamos a ver cómo personalizar algunos de estos aspectos utilizando la anotación @RestResource.

En ParticipanteDAO voy poner las siguientes líneas:

@RestResource(path="nombre")
List<Participante> findByNombreIgnoreCaseContaining(String txt);

@RestResource(exported=false)
void deleteById(String id);

@RestResource(exported=false)
void delete(Participante entity);

// Mejor ponerselo a todo lo que tenga que aplicarse
// void deleteAll(Iterable<? extends Participante> entities);
// ...

Estas líneas hacen dos cosas:

1. Modifica la URL para que el fragmento del path del primer método sea nombre.
2. Prohibe el uso de DELETE sobre Participantes.

NOTA: JpaRepository tiene 6 distintos métodos de borrado, formalmente y por rendimiento es mejor aplicar la anotación a todos ellos aunque con uno sólo sería suficiente. Aquí se indica pero no se ha hecho para ahorrar código.

Ahora quiero buscar un Partido donde participe un idParticipante que le pase. Pongo esta línea en PartidoDAO:

@RestResource(path="participante")
List<PartidoConId> findByIdLocalOrIdVisitante(@Param("idParticipante") String idLocal, @Param("idParticipante") String idVisitante);

Aquí utilizo además la anotación @Param. Esta anotación me permite enlazar un query parameter de la petición HTTP a un parámetro de mi método. La sintaxis del query method de JPA me va a obligar a tener tantos parámetros como vea que necesita su nombre (idLocal e idVisitante). Sin embargo puedo enlazar el mismo query parameter a los dos parámetros.

Puedo encontrar estos enlaces en el path /search de cada recurso.

Puedes encontrar el código hasta aquí en su repositorio.

Esta entrada es muy corta pero ya se puede practicar mucho con ella. Propongo hacer los siguientes métodos de búsqueda y ponerles el nombre apropiado:

1. Buscar sucesos por id de Participante
2. Buscar sucesos entre un Instant comienzo y otro fin
3. Buscar sucesos para un idParticipante entre comienzo y fin. Este método no se expondrá en la API.
4. Buscar sucesos después de un Instant instant. El query param tendrá el nombre start.

La solución está en github.

Inyectar un bean a un RestResource

Seguimos con el Paso 3 de la entrada anterior. Ya tenemos nuestra bean ServicioEntidad cargada e inyectándose en las entidades (Sucesos) que se leen de la BD. ¿Qué pasa con los objetos que se crean al deserializarse el JSON de la llamada HTTP? Esos objetos también deben ser inyectados con el ServicioEntidad, no podemos esperar a que sean leídos desde la BD pues podría fallar el proceso que necesitara esa llamada.

Ahora nuestro punto de entrada es el controlador que recibe esa llamada. Si lo hicieramos a mano podríamos gestionarlo en el @Controller, cuando Jackson lo convirtiera y se lo pasara como argumento a nuestro método del controlador. Sin embargo nosotros usamos Data Rest, pero podemos inyectarlo justo antes, personalizando el bean que se encarga de leer ese JSON y convertirlo en nuestro objeto de negocio (en el ejemplo SucesoConId o sus subtipos). Para ello vamos a crear un bean que al deserializar el JSON inyecte nuestro bean ServicioEntidad. Para esto jackson nos da una anotación perfecta: @JsonComponent.

La anotación @JsonComponent se puede usar sobre una clase que implemente (de)serialización o sobre una clase que contenga varias implementaciones internas que cargará todas. Hay varias formas de aprovecharlo, nosotros nos vamos a centrar en crear en una clase todas las implementaciones de deserializador que necesitamos para nuestros distintos sucesos usando StdDeserializer.

Ya que vamos a hacernos un serializador para cada tipo de suceso vamos a aprovechar la herencia para reutilizar código. El esquema general quedará:

@JsonComponent // Registra la clase/clases internas con (de)serializadores
public class JsonDeserializers {

    public static class JsonSucesoSerializer<T extends SucesoConId> extends StdDeserializer<T> {... }

    public static class JsonGolSerializer extends JsonSucesoSerializer<GolConId> {...}

    public static class JsonTarjetaSerializer extends JsonSucesoSerializer<TarjetaConId> {...}
 
}

NOTA: los deserializadores de gol y tarjeta van a heredar del serializador de suceso.

Ya vimos un ejemplo en clase haciendo un deserializador personalizado. En este caso lo vamos a repetir pues se trata de ir leyendo el JSON e ir asignando los valores en cada campo. Para ello vamos a tener que añadir algún setter más a los Sucesos si no queremos hacer uso de Reflection. Lo interesante va a ser el uso de genéricos para que se adapten al resto de implementaciones para GolConId y TarjetaConId y el uso de un callback para poder añadir lo que falte en tipos que lo necesitan (añadir el tipo de tarjeta en TarjetaConId por ejemplo). La implementación de JsonSucesoSerializer<T extends SucesoConId> resumida quedará así:

public static class JsonSucesoSerializer<T extends SucesoConId> extends StdDeserializer<T> {

    // Constructores heredados del padre StdDeserializer<T>

    @Override
    public T deserialize(JsonParser jsonParser, DeserializationContext context)
                            throws IOException, JsonProcessingException {
        return deserializarSuceso(jsonParser, (Class<T>) handledType());
    }

    protected T deserializarSuceso(JsonParser jsonParser, Class<T> tipo)
                            throws IOException, JsonProcessingException {
        T sucesoDeserializado;
        // Construir y asignar valores a campos. Ver a continuacion.

        postDeserializarSuceso(nodo, sucesoDeserializado);

        return sucesoDeserializado;
    }

    // Callback para completar la deserializacion
    protected T postDeserializarSuceso(JsonNode nodo, T sucesoDeserializado) {
        return sucesoDeserializado;
    }

}

Lo más importante de implementar StdDeserializer, aparte del parseo en sí, se puede decir que es el método handledType(). Usando ese método vamos a tener acceso al tipo de objeto que hay que deserializar y con ello podremos tener acceso al constructor que necesitemos. Para eso sí que vamos a usar Class. Con estas herramientas la construcción de un SucesoConId quedará:

protected T deserializarSuceso(JsonParser jsonParser, Class<T> tipo)
                        throws IOException, JsonProcessingException {
    T sucesoDeserializado;
    try {
        // Variable intermedia final para los lambdas
        // El constructor vendra marcado por el tipo a construir y el parametro indicado
        T suceso = tipo.getConstructor(ServicioEntidad.class).newInstance(servicioEntidad);
        JsonNode nodo = jsonParser.getCodec().readTree(jsonParser);
        // Podemos usar Optional para seguir ejecutando
        // o no si no hay campo
        Optional.ofNullable(nodo.get("timestamp")).ifPresent(n -> suceso.setTimestamp(n.asLong()));
        Optional.ofNullable(nodo.get("idParticipante")).ifPresent(n -> suceso.setIdParticipante(n.asText()));
        Optional.ofNullable(nodo.get("partido")).ifPresent(n -> {
            String idPartido = n.asText();
            idPartido = idPartido.substring(idPartido.lastIndexOf("/") + 1, idPartido.length());
            suceso.setPartido(partidoDAO.getOne(Long.parseLong(idPartido)));
        });
        postDeserializarSuceso(nodo, suceso);

        sucesoDeserializado = suceso;
    } catch (Exception e) {
        e.printStackTrace();
        sucesoDeserializado = null;
    }

    return sucesoDeserializado;
}

Lo destacable de aquí es que este método recibe el tipo del método handledType() que será implementado distinto en sus clases hijas. Con el tipo se construye con el constructor que admite un ServicioEntidad y ya estrará inyectado. Lo demás es ir leyendo y asignando valores hasta la invocación de postDeserializarSuceso(nodo, suceso). Con este callback dejamos la puerta abierta a completar la deserialización en las clases hijas.


Ahora que ya hemos completado el serializador padre podemos aprovecharlo para rematar con los otros dos que necesitamos:

// Basta con devolver el tipo a construir
public static class JsonGolSerializer extends JsonSucesoSerializer<GolConId> {
    @Override public Class<?> handledType() { return GolConId.class; }
}

public static class JsonTarjetaSerializer extends JsonSucesoSerializer<TarjetaConId> {
    @Override public Class<?> handledType() { return TarjetaConId.class; }

    @Override
    protected TarjetaConId postDeserializarSuceso(JsonNode nodo, TarjetaConId sucesoDeserializado) {
        Optional.ofNullable(nodo.get("tipoTarjeta"))
            .ifPresent(n -> sucesoDeserializado.setTipoTarjeta(TipoTarjeta.valueOf(n.asText())));
        return sucesoDeserializado;
    }
}

Vemos que nos quedan muy simples: para Gol sólo necesita decir el tipo que maneja y para Tarjeta también utilizar el callback para asignar el tipo de tarjeta (amarilla o roja) que traiga el nodo.

Ahora ya nos pueden hacer llamadas HTTP que Jackson se encargará de inyectar el ServicioEntidad.

Puedes conseguir el código hasta aquí en su repositorio.

Como práctica se propone hacer lo mismo para los partidos, ya que si se invocase código que necesitase del ServicioEntidad en la clase Partido nuestro código fallaría si no lo ha cargado ya @PostLoad en la práctica que vimos en la entrada anterior.

Inyectar un bean a una Entidad leída desde BD

Con lo que estamos viendo, lo normal es guardar y recuperar datos de una BD usando JPA. También hemos visto la flexibilidad que nos proporciona trabajar con inyección de dependencias. La inyección se produce para los beans y sin embargo nuestros "objetos de negocio" no lo son y no se puede hacer Autowired sobre ellos (me refiero a los objetos que se recuperan de una BD o los que nos llegan en formato JSON por una petición HTTP y deserializa nuestro ObjectMapper).

¿Qué importancia tienes esto?

Nuestra tabla Participantes tiene pocos datos y se modificará poco (los participantes podrán ser modificados como mucho cada comienzo de liga). Aquí tendría sentido tener todos esos datos cargados (o al menos un subconjunto como id y nombre) en memoria porque sin embargo van a ser consultados muy a menudo (clasificación, enfrentamientos históricos, jornada actual, etc...). La BD cuenta con una cache para todos los datos, pero en particular estos valores darán mejor rendimiento si los tenemos en memoria (incluso se podrían leer de un archivo sin necesidad de la BD). Esto lo vamos a hacer creando un bean del tipo ServicioEntidad que no es más que una interface que puede almacenar objetos ordenados por clase y por id usando mapas/diccionarios.

@Autowired sólo funciona en los beans. Nuestras entidades no lo son.

Nuestra librería de datos-deportivos tiene un campo ServicioEntidad en los tipos Partido y SucesoImpl y necesitan un objeto que implemente esa interfaz para hacer el "lazy loading" de participantes (sólo se recupera de la BD el idParticipante, pero no se referencia al objeto hasta que no se tiene que usar). Ni Partidos ni Sucesos son beans gestionados por el contenedor así que ¿Cómo puedo inyectar en ellos tanto por el lado web como por la BD el bean ServicioEntidad? Para ello voy a tener la ayuda de los callbacks, los listeners y los deserializadores personalizados.

He dividido esta sesión también en varios pasos:

• Paso 1: Creo mi bean ServicioEntidad y modifico mis sucesos para poder darles este valor a su campo. Este código no tiene ningún misterio y empezaremos desde este punto.
• Paso 2: Inyecto el bean ServicioEntidad en los sucesos cuando los lea desde la BD. Ésta es la finalidad de esta entrada.
• Paso 3: La otra vía de entrada es desde mi API REST. Los objetos json vendrán sin un ServicioEntidad que tendré que inyectar. Este paso lo haré en la siguiente entrada para no alargarme, pero on quería desvincularlo de esta funcionalidad de inyectar un bean.

Para explicar lo que voy a hacer voy a servirme de la siguiente figura:

Lo que representa la figura son los caminos de entrada y salida de nuestros objetos de negocio en Java teniendo nuestra aplicación en el centro y por fuera:

1. Las operaciones con la BD: Las entidades tienen un ciclo de vida con una serie de eventos
2. Las llamadas HTTP que nos llegarán a la API: vimos que la salida la modificabamos con MixIns, ahora toca configurar la entrada

Ciclo de vida de un Entity

Las entidades pasan por un ciclo de vida con los eventos/callbacks PostLoad, PrePersist, PostPersist, PreUpdate, PostUpdate, PreRemove o PostRemove en función de las operaciones que se ejecuten en la BD. Básicamente son eventos anteriores y posteriores a las operaciones guardar, actualizar y borrar y luego otro después de cargarse en el entityManager.

NOTA: Estos eventos son de JPA. Data Rest tiene otros eventos y hay otros muchos de otras librerías. En el Paso 3 implementaremos uno y lo veremos con más detalle. Lo bueno de estos eventos es que te servirán para gestionar todas las entidades cuando uses JPA.

Para lo que queremos hacer vamos a usar el evento @PostLoad. Así después de leer un SucesoConId voy a asignarle el ServicioEntidad que he creado en mi contenedor Spring.

NOTA: Mirando la documentación puede parecer que la anotación @PersistenceConstructor es exactamente lo que necesitamos. Esta anotación es de Spring pero JPA en la actualidad obliga a tener un constructor sin parámetros. De hecho si lo quitais Hibernate os dará ese error y, aunque Hibernate pueda contruir una entidad sin un constructor sin parámetros, JPA que es la API que estamos usando si lo necesita.

Voy a crearme una clase llamada SucesoListener que será un bean y lo voy a cargar con @Component. JPA no obliga a implementar ninguna interface así que esta clase no heredará de nadie pero va a tener un método que será anotado con @PostLoad. Esto indicará que ese método debe ejecutarse justo después de leer un SucesoConId (del tipo que sea) desde la BD. Para poder modificar ese suceso leído me llega por el parámetro de ese método con un simple setServicioEntidad(servicioEntidad) que añado a SucesoConId (y de ahí heredarán el resto). Sólo falta recuperar el bean ServicioEntidad de mi contenedor que puedo inyectárselo al Listener porque también lo gestiona Spring. Mi Listener queda así:

@Component
public class SucesoListener {
    private static ServicioEntidad servicioEntidad;

    @Autowired
    public void init(ServicioEntidad servicioEntidad) {
        SucesoListener.servicioEntidad = servicioEntidad;
    }

    @PostLoad
    void setServicioEntidadEnSuceso(SucesoConId suceso) {
        suceso.setServicioEntidad(servicioEntidad);
    }
}

Queda relacionar esta clase con la entidad a la que debe suscribirse para recibir el evento. Con una simple anotación en la clase SucesoConId estará hecho:

@EntityListeners(SucesoListener.class)
public class SucesoConId extends SucesoImpl { ... }

Y cargar el bean SucesoListener en el contenedor como cualquier otro @Component escaneando su paquete (usamos "es.lanyu.eventos" que servirá también para el @JsonComponent del paso 3).

@ComponentScan("es.lanyu.eventos") // Tambien para registrar JsonSerializers
public class ConfiguracionPorJava {...}

Si imprimimos nuestros partidos por consola veremos que ya aparecen enriquecidos con el toString() de Participante con lo que nuestro ServicioEntidad ha sido inyectado en cada suceso y está recuperando correctamente nuestros participantes.

SucesoConId #35, participante: Oviedo OVIEDO(ESP) fecha=2020-04-13T17:25:53.297Z
Gol para el Oviedo OVIEDO(ESP)
Tarjeta AMARILLA Heerenveen HERENV(HOL)

Puedes ver el código hasta aquí en su repositorio. En la siguiente entrada continuamos con el Paso 3, pero no olvides hacer la práctica que te pongo más abajo.

Para asimilar este contenido dejo una práctica en la que habrá que utilizar lo que hemos visto:

Se pide implementar lo necesario para PartidoConId el toString() que muestre el id y los detallesDelPartido() (ya implementado y comentado en la última línea del toString() pero habrá que inyectar ServicioEntidad). Además si ahora se intenta usar la API REST para hacer un DELETE sobre un partido con sucesos ocurrirá un error 500: implementar lo necesario para poder borrar un partido con sucesos (también se deben borrar antes sus sucesos). Como ya tenemos cierto nivel con Spring se pide al menos hacerlo de la forma que no hemos visto pero es la más desacoplada: por XML. En el wikibook viene un ejemplo.

ORM por XML: Guardar subclases en SINGLE_TABLE

Ya vimos en una sesión anterior la capacidad de heredar la definición de persistencia desde las superclases con la etiqueta "mapped-superclass". En esta entrada vamos a ver cómo se guardan especializaciones distintas de un mismo tipo pudiendo recuperar todas ellas de forma única o recuperándolas como un tipo específico.

En nuestro ejemplo nuestras especializaciones son los distintos tipos de sucesos que hay en un partido (goles, tarjetas, corners, etc...) ya que todos heredan de Suceso, en nuestra API concretamente de la implementación SucesoConId.

Para persistir varias clases que heredan de un mismo tipo se puede hacer de tres formas:

1. SINGLE_TABLE: Es la opción por defecto y la implementada por todas las librerías. Los datos de todos los subtipos se guardan en una misma tabla. Tiene el mejor rendimiento a la hora de consultar datos porque no hay que realizar ninguna unión, pero como desventaja tendremos campos null en las columnas que no usen especificaciones concretas (tienen que existir columnas para todos los campos de todas las implementaciones)
2. JOINED: Todos los datos comunes se volcarán en una única tabla y el resto de campos se guardará en otra tabla aparte con una FK a la tabla común que lo relacione.
3. TABLE_PER_CLASS: Esta es una opción de JPA y puede que algunas implementaciones no la contempen. Se trata de guardar cada clase entera en su propia tabla.

De estas tres formas nos vamos a centrar en SINGLE_TABLE por ser la más implementada y de mejor rendimiento aunque implique desnormalizar nuestro modelo de datos en la BD.

¿Cómo se identifica qué tipo hay en cada fila?

Como vamos a mezclar tipos distintos en la misma tabla debe haber algún mecanismo que permita saber qué tipo concreto hay en cada fila. Para esto, además de todas las columnas para los datos de todas las distintas especializaciones se va a crear una columna que sirva para discriminar el tipo. Para implementar todo lo necesario lo voy a dividir en 4 pasos:

1. Creación de las dos especializaciones y sus DAO
2. ORM por XML para SucesoConId y especialización de Tarjeta
3. ORM por anotaciones de especialización de Gol
4. Modificar nuestro ObjectMapper como sea necesario

Paso 1: Vamos a crearnos dos de estas especificaciones: GolConId y TarjetaConId que heredarán de SucesoConId y además implementarán sus respectivas interfaces (Gol y Tarjeta). También vamos a crear los DAO correspondientes como lo hicimos en la sesión anterior sobre Spring Data Rest. Éste código no tiene ningún misterio y se puede ver fácilmente en el commit.

Como ya dijimos que para JPA las interfaces no existen, no caigamos en la tentación de asignar las definiciones a las interfaces Gol y Tarjeta (ver fichero Sucesos.orm.xml): deben ser clases que se puedan instanciar. De hecho podríamos tener implementaciones distintas a GolConId y TarjetaConId (y que tuvieran que guardarse de forma distinta también) lo que implicaría otro valor para discriminarlas. Como hay dos especificaciones voy a hacer ORM de formas distintas con cada una:

Paso 2: Tarjeta por XML (lo añado a SucesoConId.orm.xml para que se vea que puede haber varias entidades en el mismo fichero):

<entity class="es.lanyu.eventos.repositorios.SucesoConId" access="FIELD">
    <table name="SUCESOS"/>
    <!-- No hace falta strategy es el valor por defecto -->
    <inheritance strategy="SINGLE_TABLE"/>
    <discriminator-column name="TIPO"/>
    <discriminator-value>S</discriminator-value>
    <attributes>
        ...
    </attributes>
</entity>

<entity class="es.lanyu.eventos.repositorios.TarjetaConId" access="FIELD">
    <discriminator-value>T</discriminator-value>
    <attributes>
        <basic name="tipoTarjeta"/>
    </attributes>
</entity>

Paso 3: Y Gol lo haré por anotaciones añadiéndole lo que hace falta a la clase GolConId:

@Entity
@Access(value=AccessType.FIELD)
@DiscriminatorValue("G")
public class GolConId extends SucesoConId implements Gol { ... }

NOTA: ver @Access.

Paso 4: Ahora toca tunear nuestro MixIns para añadir y reutilizar código (implementación y extensión de ContadorDeMinutos y refactorizado de Datables-Partidos-Sucesos). Como no es parte de esta sesión mejor verlo en el commit o el video del webinar.

Con esto ya podemos levantar el servicio y empezar a añadir también goles y tarjetas. Veremos que crea URLs para los recursos /goles y /tarjetas donde podemos ver cada uno de ellos por separado o todos juntos en el recurso de /sucesos pero con relaciones agrupándo cada tipo distinto.

Se puede obtener el código hasta aquí en su repositorio. Se han añadido peticiones a la colección de Postman para generar goles y tarjetas aleatorias.

La potencia de Spring Data Rest: @RestResource

Ya hemos estado viendo lo básico del Core de Spring, también hemos estado viendo lo básico de JPA/ORM para dar persistencia a los datos. Ahora vamos a ver la capa de presentación mostrando nuestros datos por una API REST.

REST se clasifica en varios niveles en función de su madurez. En general basta con un servicio web que atienda peticiones por protocolo HTTP y devuelva datos serializados (normalmente en JSON, pero puede ser otro formato también): Nivel 0. Estos dos puntos parecen antagónicos con SOAP que permite cualquier protocolo para el transporte, pero los datos deben intercambiarse por XML con un esquema rígido.

URLs bien definidas identificando recursos: colecciones, elementos individuales y otras "operaciones": Nivel 1.

Para las peticiones se usarán verbos HTTP para operaciones CRUD (GET, POST, PUT, DELETE,...): Nivel 2.

El nivel más alto se logra consiguiendo HATEOAS/Hipermedia. Esto significa que, desde la raíz de nuestro servicio REST, todas las llamadas que se puedan realizar deben ser autodescubribles por medio de enlaces URL que representan las asociaciones de los distintos recursos: Nivel 3. Un ejemplo sería la API con datos sobre Star Wars donde se ven los enlaces de Luke con su planeta natal, peliculas donde sale, sus vehículos, raza, etc... siendo todos ellos urls al recurso (pero no incrustando sus datos).

Otra característica es que REST no mantiene estado. Cada petición y respuesta debe contener toda la información necesaria.

Después de esta introducción, recomiendo ver un video que habla de todo ello de una forma muy práctica y directa llamado "Horneando APIs" de Paradigma Digital. y que para mí es como un resumen en español del libro REST API Design Rulebook. Nosotros vamos a poner en práctica todo esto con:

1. Spring Data Rest: que es una de las dependencias que usamos cuando generamos el proyecto inicialmente con Spring Initialzr. Si miramos nuestro build.gradle se identifica perfectamente la dependencia
2. y nuestro ejemplo de Datos Deportivos

Empezamos este tutorial dando persistencia a Participantes y a Partidos que tenía una colección de Sucesos. Cargamos los datos de 237 participantes usando su DAO correpondiente y también cargamos unos partidos aleatorios con sucesos (en general sin decir si son goles, tarjetas, etc...). Esta forma de trabajar no permite la interacción que se espera de una arquitectura cliente-servidor. Al final de esta entrada tendremos una colección para Postman que nos permitirá interaccionar con nuestra aplicación mediante llamadas HTTP y nos permitirá hacer pruebas más fácil. Por tanto el punto inicial es este commit de nuestro repositorio.

Si en este punto no cerramos la aplicación con nuestra última linea del main veríamos que ya se están exponiendo los repositorios. Hacemos una llamada a http://localhost:8080/ y tendremos la siguiente respuesta:

{
  "_links": {
    "partidoConIds": {
      "href": "http://localhost:8080/partidoConIds{?page,size,sort}",
      "templated": true
    },
    "participantes": {
      "href": "http://localhost:8080/participantes{?page,size,sort}",
      "templated": true
    },
    "sucesoConIds": {
      "href": "http://localhost:8080/sucesoConIds{?page,size,sort}",
      "templated": true
    },
    "profile": {
      "href": "http://localhost:8080/profile"
    }
  }
}

Es decir, por defecto, todos los repositorios serán mostrados por Spring Data Rest si no se configura lo contrario. Voy añadir dos propiedades para configurar dos aspectos: que sólo se muestre lo anotado con @(Repository)RestResource y el prefijo de la API:

spring.data.rest.detection-strategy=annotated
spring.data.rest.basePath=/api

Esto lo pondré en un archivo llamada rest.properties que añadiré con @PropertySource como vimos anteriormente mediante una clase de configuración llamada ConfiguracionJava que luego usaré para más cosas:

@Configuration
@PropertySource({ "classpath:config/rest.properties" })
public class ConfiguracionPorJava {}

Y la añadimos a nuestra aplicación:

@Import(ConfiguracionPorJava.class)
public class DatosdeportivosapiApplication {...}

Ahora ya no se mostrará lo anterior, así que lo siguiente será modificar nuestras anotaciones @Repository por @RepositoryRestResource que es de Spring Data Rest.

@RepositoryRestResource admite varios valores para configurar nuestro repositorio. Pongo el ejemplo para SucesoConId:

@RepositoryRestResource(path="sucesos",
//                        exported=false,
                        itemResourceRel="suceso",
                        collectionResourceRel="sucesos")
public interface SucesoDAO extends JpaRepository<SucesoConId, Long> {
}

Aquí se puede ver que podemos decidir el path para este recurso y los nombres que tendrán las relaciones tanto para colección como para elemento (al final de la entrada se ve qué es esto de las relaciones). Recomiendo usar al menos esta configuración porque de lo contrario generará esos nombres automáticamente y puede que el resultado no nos guste (ver cómo se veía antes más arriba).

He comentado el valor exported=false ya que evita que se exponga el recurso. Este valor habría que usarlo si no quisiéramos mostrar este recurso. Por defecto tiene valor true.

Con esto termina el Paso 1, pero los recursos de Partidos y Sucesos no se pueden visitar ya que Jackson no es capaz de serializarlos correctamente porque no son simples POJOs. Vamos a customizar cómo debe serializarse aplicando propiedades para jackson, implementando unos MixIn y añadiéndolos a nuestro ObjectMapper. Como la entrada no va de esto y para no alargarla, lo mejor es ver este segundo paso en vivo en el webinar, pero aquí nos vamos a colocar en el commit del Paso 2 para continuar y terminar con nuestra API RESTful HATEOAS.

El resultado hasta aquí muestra una API con un array de Sucesos en cada Partido y sin mostrar el partido al que corresponde cada Suceso para no entrar en bucle. También vemos links de paginación dando cierta navegabilidad, pero no se puede navegar entre Partidos y Sucesos correctamente. Para implementar HATEOAS correctamente Spring necesita la siguiente información sobre las relaciones:

1. Anotar con @OneToMany y @ManyToOne los miembros necesarios. No sirve sólo con que tenga la información JPA.
2. Los recursos para asociar deben tener repositorio propio (esto ya está hecho)
3. Se debe conocer la implementación concreta si la relación hace referencia a un tipo abstracto (debe saber qué Suceso debe deserializarse: deserialización polimórfica)

Para el primer punto no hace falta anotar las clases con @Entity ni @Id. Con anotar el miembro correspondiente es suficiente. Como no se tiene acceso al campo sucesos lo que hacemos es sobre escribirlo y anotarlo incluyendo la entidad objetivo (punto 3):

@Override
@OneToMany(targetEntity=SucesoConId.class)
public Collection<Suceso> getSucesos() {
    return super.getSucesos();
}

NOTA: también podría hacerse con (de)serializadores personalizados, añadiendo información con TypeResolver (y TypeResolverBuilder, sobre @JsonType(Id)Resolver o ver este snippet). Es la solución más genérica que se encuentra (aunque rebuscando mucho, una búsqueda me dio sólo 3 resultados) en Internet, pero en nuestro caso particular usando semántica esta forma es muy simple y funciona.

Para el caso de SucesoConId basta con anotar el campo con @ManyToOne.

@ManyToOne
PartidoConId partido;

Comparto también una colección, para probar la API en el punto actual.