Skip to content

11. Caso de estudio: la aplicación RdvMedecins

11.1. El problema

La aplicación RdvMedecins gestiona las citas de un consultorio médico. Cada médico tiene franjas horarias (de 8:00 a. m. a 12:00 p. m. en intervalos de 20 minutos, por ejemplo); una cita consta de un día, una franja horaria y un cliente (un paciente). Esta es la implementación exacta, en [Spring MVC], de la aplicación [ASP.NET Core MVC] de la lección anterior: la misma base de datos, las mismas reglas de negocio, las mismas páginas, las mismas URL, los mismos diccionarios de traducción. Las páginas HTML las genera el servidor mediante vistas [Thymeleaf]; el acceso a la base de datos lo gestionan [Spring Data JPA] y [Hibernate].

Tres roles de usuario comparten la aplicación:

Rol
Quién
Qué puede hacer
ADMIN
El administrador ([admin])
Ver las agendas, hacer y cancelar citas para cualquier paciente; gestionar (listar, agregar, editar, eliminar) médicos y clientes
DOCTOR
Médicos
ver las agendas, hacer citas y cancelar citas para cualquier paciente
USER
clientes (pacientes)
ver las agendas sin ver los nombres de otros pacientes; reservar una cita para sí mismos; cancelar su cita; gestionar su cuenta; crear una cuenta

Principales reglas de gestión:

  • No se admiten citas en el pasado;
  • una franja horaria solo puede reservarse una vez por día;
  • un paciente puede tener solo una cita próxima a la vez;
  • dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un nombre de usuario pertenece a una sola cuenta;
  • No se puede eliminar a un médico que tiene citas; a un cliente se le elimina junto con sus citas;
  • la página de inicio de sesión está protegida contra bots (CAPTCHA, intentos limitados), y para crear una cuenta de cliente primero se debe resolver el CAPTCHA en esa página.

11.2. Uso de la aplicación

11.2.1. La página de inicio de sesión

Image

La página presenta dos botones: Log in y Create a patient account. Ambos requieren que se ingresen los caracteres que aparecen en la imagen. Los botones FR / EN cambian el idioma:

Image

Un error (en este caso, un CAPTCHA ingresado incorrectamente) se muestra al pie de la página sobre un fondo rosa claro:

Image

11.2.2. El calendario, visto por el administrador y los médicos

Una vez iniciada la sesión, el administrador es dirigido a la página del calendario. Allí selecciona un médico y un día:

Image

Image

Cada franja horaria está disponible (botón Book) u ocupada (nombre del paciente, botón Cancel). Al hacer clic en Book se abre una ventana que solicita la información del paciente. Esta ventana la genera el servidor, al igual que el resto de la página: la URL ahora contiene el parámetro [book=4], que es el número de la franja horaria seleccionada:

Image

Al hacer clic en «Cancel» se solicita una confirmación (aquí por parte del Dr. Pélissier, cuya barra de navegación no incluye los menús de administración):

Image

11.2.3. El portal del paciente

Un paciente (rol USER) llega a My area: su próxima cita, que puede cancelar, y enlaces a la gestión de su cuenta y al calendario:

Image

En el calendario, ve su propia cita (en azul), pero no los nombres de otros pacientes, que se reemplazan por «Booked»: este nombre ni siquiera aparece en el código fuente de la página. Dado que ya tiene una cita próxima, no puede programar otra: no se muestra ningún botón «Book» (en el calendario de otro día o de otro médico, donde su cita no aparece, un mensaje explica el motivo):

Image

Un paciente sin cita puede reservar una franja disponible para sí mismo: la ventana de reserva no le pide al usuario que seleccione un paciente.

Image

Gestión de la cuenta: editar la información personal, cambiar la contraseña o eliminar la cuenta (y sus citas). Se requiere la contraseña actual para cualquier cambio:

Image

Un paciente que intenta abrir una página reservada al administrador (aquí, [/doctors], escrita manualmente) recibe una página de error:

Image

11.2.4. Gestión de médicos y pacientes

El administrador dispone de dos menús adicionales, Doctors y Patients:

Image

Image

El formulario para agregar un médico, enviado con errores:

Image

Un nombre idéntico al de un médico existente es rechazado, incluso si está escrito en minúsculas (veremos que es la propia base de datos la que compara los nombres sin distinguir entre mayúsculas y minúsculas ni acentos):

Image

Eliminar a un paciente requiere confirmación:

Image

11.2.5. Creación de una cuenta de paciente

Desde la página de inicio de sesión, el botón «Create a patient account» solo abre el formulario si el CAPTCHA se ingresó correctamente:

Image

Image

11.3. Instalación y ejecución

La aplicación se encuentra en la carpeta [rdvmedecins2-spring-mvc], junto a la carpeta [examples]. Es un proyecto [Maven] independiente: no depende del proyecto padre que contiene los ejemplos y tiene su propio Maven Wrapper (véase más abajo). El archivo [README.md] de la carpeta contiene todo lo que sigue.

11.3.1. Software necesario

Bastan dos programas:

  • JDK 21 ([Java Development Kit]), que contiene el compilador [javac] y la máquina virtual [java]. [Java] 21 es una versión LTS (soporte a largo plazo). Una distribución gratuita es adecuada, por ejemplo, [Eclipse Temurin] (https://adoptium.net); en [Linux], el paquete [openjdk-21-jdk]. Verifique la instalación en una terminal:
java -version
1
2
3
openjdk version "21.0.10" 2026-01-20
OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04)
OpenJDK 64-Bit Server VM (build 21.0.10+7-Ubuntu-124.04, mixed mode, sharing)
  • Un servidor [MySQL] 8 , por ejemplo, el de [Laragon] en [Windows] (véase el ejemplo 28). [MariaDB] también es adecuado: la aplicación se ha probado con él.

[Maven] no necesita instalarse: el script [mvnw] (Maven Wrapper) lo descarga automáticamente en el primer inicio, y luego [Maven] descarga las bibliotecas del proyecto desde el repositorio [Maven Central]. Por lo tanto, debe estar conectado a Internet durante la primera compilación. El editor recomendado es [Visual Studio Code], con el «Extension Pack for Java» y el «Spring Boot Extension Pack»; sin embargo, todo se puede hacer desde la línea de comandos.

11.3.2. Creación de la base de datos

La base de datos [dbrdvmedecins2] se crea mediante el script [database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Base de datos) y luego ejecute el script desde el menú Archivo / Ejecutar archivo SQL. Desde la línea de comandos, en la carpeta de la aplicación:

mysql -u root -p < database/dbrdvmedecins2.sql

La opción [-p] solicita la contraseña de [root]; omítala si la cuenta no tiene contraseña (como ocurre con [Laragon]). Es la misma base de datos que usa la versión [ASP.NET Core]: si ya existe, este paso es opcional. El script puede ejecutarse en cualquier momento para volver a los datos originales.

11.3.3. Configuración del acceso a la base de datos

Todos los parámetros de configuración están en el archivo [src/main/resources/application.properties] (que se comenta más adelante). De manera predeterminada, la aplicación se conecta a [MySQL] en [localhost], puerto 3306, con el usuario [root] sin contraseña: esta es la configuración predeterminada de [Laragon]. Si su cuenta [root] tiene contraseña, lo más sencillo es escribirla en este archivo, bajo la clave [spring.datasource.password]. Para evitar escribir una contraseña en un archivo del proyecto, también puede indicarla mediante una variable de entorno, que tiene prioridad sobre el archivo. Su nombre se deriva del nombre de la clave: en mayúsculas, con [.] y [-] reemplazados por [_]:

1
2
3
export SPRING_DATASOURCE_PASSWORD=myPassword          # Linux, macOS
set SPRING_DATASOURCE_PASSWORD=myPassword             # Windows (cmd)
$env:SPRING_DATASOURCE_PASSWORD="myPassword"          # Windows (PowerShell)

La variable se aplica solo a la terminal en la que se definió: la aplicación se inicia entonces desde ella.

11.3.4. Inicio de la aplicación

Abra la carpeta [rdvmedecins2-spring-mvc] en [Visual Studio Code] (menú Archivo / Abrir carpeta), luego abra una terminal (menú Terminal / Nueva terminal) y escriba:

./mvnw spring-boot:run

En [Windows], escriba [mvnw spring-boot:run] en el símbolo del sistema, o [.\mvnw spring-boot:run] en [PowerShell]. La primera vez que se ejecuta, [mvnw] descarga [Maven], que a su vez descarga las bibliotecas, compila la aplicación y luego la inicia. Después de los mensajes de [Maven], la consola muestra los mensajes de la aplicación:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.1.1)

2026-09-25T18:46:42.404+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : Starting RdvMedecinsApplication using Java 21.0.10 with PID 19025 (/home/serge/cours/rdvmedecins2-spring-mvc/target/classes started by serge in /home/serge/cours/rdvmedecins2-spring-mvc)
2026-09-25T18:46:42.422+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : The following 1 profile is active: "dev"
2026-09-25T18:46:42.598+02:00  INFO 19025 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : Devtools property defaults active! Set 'spring.devtools.add-properties' to 'false' to disable
2026-09-25T18:46:42.598+02:00  INFO 19025 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : For additional web related logging consider setting the 'logging.level.web' property to 'DEBUG'
2026-09-25T18:46:43.729+02:00  INFO 19025 --- [  restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Bootstrapping Spring Data JPA repositories in DEFAULT mode.
2026-09-25T18:46:43.795+02:00  INFO 19025 --- [  restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Finished Spring Data repository scanning in 55 ms. Found 5 JPA repository interfaces.
2026-09-25T18:46:44.511+02:00  INFO 19025 --- [  restartedMain] o.s.boot.tomcat.TomcatWebServer          : Tomcat initialized with port 8081 (http)
2026-09-25T18:46:44.524+02:00  INFO 19025 --- [  restartedMain] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2026-09-25T18:46:44.525+02:00  INFO 19025 --- [  restartedMain] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/11.0.24]
2026-09-25T18:46:44.552+02:00  INFO 19025 --- [  restartedMain] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 1949 ms
2026-09-25T18:46:44.747+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.jpa                    : HHH008540: Processing PersistenceUnitInfo [name: default]
2026-09-25T18:46:44.783+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000001: Hibernate ORM core version 7.4.5.Final
2026-09-25T18:46:45.287+02:00  INFO 19025 --- [  restartedMain] o.s.o.j.p.SpringPersistenceUnitInfo      : No LoadTimeWeaver setup: ignoring JPA class transformer
2026-09-25T18:46:45.317+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Starting...
2026-09-25T18:46:45.487+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Added connection com.mysql.cj.jdbc.ConnectionImpl@4a05c6b0
2026-09-25T18:46:45.488+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Start completed.
2026-09-25T18:46:45.537+02:00  WARN 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported, hence certain features may not work properly.The minimum supported version is 8.0.0. Check the community dialects project for available legacy versions.
2026-09-25T18:46:45.554+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.connections.pooling    : HHH10001005: Database info:
    Database JDBC URL [jdbc:mysql://localhost:3306/dbrdvmedecins2]
    Database driver: MySQL Connector/J
    Database dialect: MySQLDialect
    Database version: 5.5.5
    Default catalog/schema: dbrdvmedecins2/undefined
    Autocommit mode: undefined/unknown
    Isolation level: REPEATABLE_READ [default REPEATABLE_READ]
    JDBC fetch size: none
    Pool: DataSourceConnectionProvider
    Minimum pool size: undefined/unknown
    Maximum pool size: undefined/unknown
2026-09-25T18:46:47.573+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
2026-09-25T18:46:47.597+02:00  INFO 19025 --- [  restartedMain] j.LocalContainerEntityManagerFactoryBean : Initialized JPA EntityManagerFactory for persistence unit 'default'
2026-09-25T18:46:47.688+02:00  INFO 19025 --- [  restartedMain] o.s.d.j.r.query.QueryEnhancerFactories   : Hibernate is in classpath; If applicable, HQL parser will be used.
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` order by d1_0.last_name,d1_0.first_name
Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
2026-09-25T18:46:52.549+02:00  INFO 19025 --- [  restartedMain] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 8081 (http) with context path '/'
2026-09-25T18:46:52.563+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : Started RdvMedecinsApplication in 10.82 seconds (process running for 11.321)
2026-09-25T18:46:52.928+02:00  INFO 19025 --- [omcat-handler-0] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
2026-09-25T18:46:52.929+02:00  INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2026-09-25T18:46:52.930+02:00  INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet        : Completed initialization in 1 ms

Volveremos a esta consola en la sección «Inicio de la aplicación». Por ahora, observe la línea [Tomcat started on port 8081]: la aplicación está lista en la dirección [http://localhost:8081]. El puerto 8081 permite ejecutar al mismo tiempo un ejemplo del curso (puerto 5000). La versión [ASP.NET Core] de la aplicación también escucha en el puerto 8081: no ejecute ambas al mismo tiempo.

Detenga la aplicación presionando [Ctrl-C] en la terminal.

11.3.5. Cuentas de demostración

La contraseña de cada cuenta es su nombre de usuario; también debe ingresar los caracteres de la imagen, en mayúsculas o minúsculas:

Nombre de usuario
Rol
[admin]
ADMIN (el administrador)
[pelissier], [tatou], [dupont]
DOCTOR (los médicos)
[martin], [durand], [bistrou], [german]
USER (pacientes)

Una guía para explorar la aplicación:

  • [admin]: Schedule, la Sra. Marie PELISSIER, hoy: una franja horaria ya está reservada por la Sra. Brigitte BISTROU. Reserve una franja para el Sr. Jean MARTIN y luego intente reservarle una segunda cita (rechazada). Menús Doctors y Patients: agregar, editar, eliminar (no se puede eliminar a la Dra. PELISSIER, que tiene citas);
  • [pelissier]: su agenda del día se muestra directamente; la dirección [/doctors], ingresada manualmente, devuelve una página de error 403;
  • [martin]: My area, su cita, el calendario donde los demás pacientes aparecen como «Booked»; Manage my account;
  • página de inicio de sesión: Create a patient account y luego iniciar sesión con la nueva cuenta;
  • Botones FR / EN: toda la interfaz cambia de idioma, incluidas las fechas.

11.3.6. Modo de desarrollo

El comando [./mvnw spring-boot:run] inicia la aplicación con el perfil [dev] (véase [pom.xml], más abajo): la consola muestra entonces cada comando SQL enviado a la base de datos por [Hibernate] (las dos líneas [Hibernate: select ...] de la consola anterior). Otras dos herramientas facilitan el desarrollo:

  • la biblioteca [Spring Boot DevTools] (véase [pom.xml]) reinicia automáticamente la aplicación en cuanto se recompila una clase en la carpeta [target/classes]. [Visual Studio Code] recompila un archivo [.java] en cada guardado; sin él, habría que escribir [./mvnw compile] en una segunda terminal. El reinicio toma apenas unos segundos: solo se recargan las clases de la aplicación, no las bibliotecas. En cambio, una vista [templates/*.html] modificada se recarga la próxima vez que se muestra la página, una vez que se ha copiado a [target/classes] de la misma manera;
  • El depurador: con el «Extension Pack for Java», los enlaces Run y Debug aparecen encima del método [main] en [RdvMedecinsApplication.java]; Debug inicia la aplicación bajo el control del depurador. Establezca un punto de interrupción haciendo clic en el margen de una línea de código. La vista Spring Boot Dashboard del «Spring Boot Extension Pack» ofrece los mismos comandos.

11.3.7. Un archivo ejecutable

Para instalar la aplicación en un servidor, empaquétela en un único archivo:

./mvnw package
java -jar target/rdvmedecins-1.0.jar

El primer comando compila la aplicación y crea el archivo [target/rdvmedecins-1.0.jar] (de aproximadamente 60 MB): contiene la aplicación, todas sus bibliotecas y el propio servidor [Tomcat]. El segundo comando lo inicia: solo se requiere un JDK (o un JRE) 21 en la máquina. Cuando se inicia de este modo, la aplicación no tiene el perfil [dev] (la consola no muestra los comandos SQL), y [Spring Boot DevTools] no está incluido en el archivo. Cada clave de [application.properties] puede reemplazarse en la línea de comandos, por ejemplo, con [java -jar target/rdvmedecins-1.0.jar --server.port=9000].

11.3.8. Problemas frecuentes

Al iniciar, [Hibernate] consulta la base de datos para determinar su versión y luego la aplicación lee de ella las listas de médicos y clientes: si la base de datos no es accesible, la aplicación se detiene de inmediato, con un error que se muestra en la consola. Este error suele quedar enterrado en una larga pila de llamadas, y la última línea, [Caused by: ...], no es muy descriptiva ([Unable to determine Dialect without JDBC metadata]: [Hibernate] no pudo consultar la base de datos). En su lugar, busque el mensaje de la propia base de datos, que [Hibernate] también escribe en una advertencia al comienzo del error. Por ejemplo, con una base de datos que no existe:

1
2
3
4
5
6
... WARN ... org.hibernate.orm.jdbc.error : HHH000247: ErrorCode: 1049, SQLState: 42000
... WARN ... org.hibernate.orm.jdbc.error : Unknown database 'dbunknown'
...
Caused by: java.sql.SQLSyntaxErrorException: Unknown database 'dbunknown'
...
Caused by: org.hibernate.HibernateException: Unable to determine Dialect without JDBC metadata (please set 'jakarta.persistence.jdbc.url' for common cases or 'hibernate.dialect' when a custom Dialect implementation must be provided)

Los mensajes más frecuentes:

Mensaje
Causa probable
[Communications link failure] o [Connection refused]
[MySQL] no se ha iniciado, o no escucha en [localhost:3306]
[Access denied for user 'root'@'localhost']
Debe ingresarse la contraseña de [MySQL] (véase «Configuración del acceso a la base de datos»)
[Unknown database 'dbrdvmedecins2']
No se ha ejecutado el script [database/dbrdvmedecins2.sql]
[rdvmedecins.auth.jwt-secret must be at least 32 characters long]
La clave secreta de los tokens es demasiado corta en [application.properties]
[Port 8081 was already in use]
El puerto 8081 ya está en uso (¿se está ejecutando la versión [ASP.NET Core] ?): deténgala o cambie [server.port]
[JAVA_HOME is not set] o [release version 21 not supported]
Falta el JDK o es anterior a la versión 21
[Could not transfer artifact] mientras se ejecuta [mvnw]
El repositorio [Maven Central] no es accesible (sin conexión a Internet, proxy)

Con [MariaDB], [Hibernate] también muestra una advertencia inofensiva al iniciar: [HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported]. [MariaDB] en realidad se presenta ante el controlador de [MySQL] con el número de versión «5.5.5», que [Hibernate] interpreta como un [MySQL] muy antiguo.

11.4. La arquitectura de la aplicación

Image

  • El navegador envía sus solicitudes al servidor [Tomcat], que está integrado en la aplicación. Cada solicitud pasa primero por la cadena de filtros de [Spring Security] (configurada por [config/SecurityConfig.java]), que identifica al usuario a partir del token JWT de su cookie y deniega el acceso a las páginas protegidas;
  • [controllers]: los controladores de la capa web. Todos pasan por un único bean, [ApplicationModel] (archivo [web]), que almacena en memoria las listas de médicos y clientes y reenvía las demás solicitudes a la capa de negocio;
  • [auth]: la conexión, los tokens JWT, el CAPTCHA, los límites de intentos y el pase de creación de cuenta;
  • [web]: elementos comunes de la capa web: la caché y la fachada [ApplicationModel], la traducción, los mensajes flash, la validación, los atributos comunes a todas las vistas y la gestión de excepciones; [models]: modelos de formularios y de vistas;
  • [business]: reglas de negocio y transacciones;
  • [repositories]: la capa DAO, una interfaz [Spring Data JPA] por tabla;
  • [entities]: las entidades [JPA], que [Hibernate] lee de la base de datos y escribe en ella; [domain]: los objetos del calendario, calculados por la capa de negocio;
  • [templates]: las vistas [Thymeleaf], que generan las páginas HTML; [i18n]: los diccionarios, que usa el traductor; [static]: la hoja de estilos, el script de la página y [Bootstrap];
  • [config]: la configuración escrita en [Java] (seguridad, idioma, mensajes flash, propiedades tipadas); [RdvMedecinsApplication.java] inicia todo el proceso.

La carpeta de la aplicación:

rdvmedecins2-spring-mvc/
├── .mvn/
│   └── wrapper/
│       └── maven-wrapper.properties
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── src/
│   └── main/
│       ├── java/
│       │   └── rdvmedecins/
│       │       ├── auth/
│       │       │   ├── AuthService.java
│       │       │   ├── Captcha.java
│       │       │   ├── CaptchaService.java
│       │       │   ├── CaptchaDrawing.java
│       │       │   ├── AttemptLimiterService.java
│       │       │   ├── RegistrationPassService.java
│       │       │   ├── README.md
│       │       │   ├── InvalidSessionException.java
│       │       │   └── ConnectedUser.java
│       │       ├── config/
│       │       │   ├── AuthProperties.java
│       │       │   ├── ProtectionProperties.java
│       │       │   ├── README.md
│       │       │   ├── SecurityConfig.java
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   ├── ScheduleController.java
│       │       │   ├── AuthController.java
│       │       │   ├── ClientsController.java
│       │       │   ├── ErrorController.java
│       │       │   ├── PatientAreaController.java
│       │       │   ├── RegistrationController.java
│       │       │   ├── LanguageController.java
│       │       │   ├── DoctorsController.java
│       │       │   ├── PersonsControllerBase.java
│       │       │   └── README.md
│       │       ├── domain/
│       │       │   ├── DoctorDaySchedule.java
│       │       │   ├── DoctorDaySlot.java
│       │       │   └── README.md
│       │       ├── entities/
│       │       │   ├── AbstractEntity.java
│       │       │   ├── Client.java
│       │       │   ├── Slot.java
│       │       │   ├── Doctor.java
│       │       │   ├── Person.java
│       │       │   ├── README.md
│       │       │   ├── Role.java
│       │       │   ├── Appointment.java
│       │       │   └── User.java
│       │       ├── business/
│       │       │   ├── Dates.java
│       │       │   ├── PersonData.java
│       │       │   ├── Business.java
│       │       │   ├── BusinessException.java
│       │       │   ├── BusinessService.java
│       │       │   └── README.md
│       │       ├── models/
│       │       │   ├── Forms.java
│       │       │   ├── ViewModels.java
│       │       │   ├── README.md
│       │       │   └── InputRules.java
│       │       ├── repositories/
│       │       │   ├── ClientRepository.java
│       │       │   ├── SlotRepository.java
│       │       │   ├── DoctorRepository.java
│       │       │   ├── PersonRepository.java
│       │       │   ├── README.md
│       │       │   ├── AppointmentRepository.java
│       │       │   └── UserRepository.java
│       │       ├── web/
│       │       │   ├── ApplicationModel.java
│       │       │   ├── CookieFlashMapManager.java
│       │       │   ├── Flash.java
│       │       │   ├── HtmlExceptionHandler.java
│       │       │   ├── FlashMessage.java
│       │       │   ├── CommonModel.java
│       │       │   ├── Utils.java
│       │       │   ├── README.md
│       │       │   ├── Translator.java
│       │       │   ├── FlashType.java
│       │       │   └── Validation.java
│       │       └── RdvMedecinsApplication.java
│       └── resources/
│           ├── i18n/
│           │   ├── en.json
│           │   └── fr.json
│           ├── static/
│           │   ├── css/
│           │   │   └── styles.css
│           │   ├── js/
│           │   │   └── app.js
│           │   └── lib/
│           │       └── bootstrap/
│           │           ├── css/
│           │           │   └── bootstrap.min.css
│           │           └── LICENSE
│           ├── templates/
│           │   ├── fragments/
│           │   │   ├── captcha.html
│           │   │   ├── person-fields.html
│           │   │   ├── confirmation.html
│           │   │   ├── errors.html
│           │   │   ├── flash.html
│           │   │   ├── navbar.html
│           │   │   └── booking.html
│           │   ├── persons/
│           │   │   ├── form.html
│           │   │   └── list.html
│           │   ├── schedule.html
│           │   ├── account.html
│           │   ├── error.html
│           │   ├── area.html
│           │   ├── registration.html
│           │   ├── layout.html
│           │   ├── login.html
│           │   └── README.md
│           ├── application-dev.properties
│           └── application.properties
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md

Esta es la organización estándar de un proyecto [Maven], como se vio en los ejemplos: el código [Java] en [src/main/java], organizado en paquetes (un paquete [Java] es una carpeta de clases, cuyo nombre —aquí, por ejemplo, [rdvmedecins.web]— refleja la ruta); todo lo demás (configuración, vistas, diccionarios, archivos estáticos) en [src/main/resources]. Durante la compilación, [Maven] copia el contenido de [src/main/resources] en [target/classes], junto a las clases compiladas: juntos, forman el classpath de la aplicación: el conjunto de carpetas y archivos donde la máquina virtual busca clases y archivos. Por eso el código se refiere a un diccionario como [i18n/fr.json], sin el prefijo [src/main/resources]. La carpeta [target], creada por [Maven], no se muestra.

Cada carpeta principal contiene un archivo llamado [README.md] que enumera sus archivos. La siguiente tabla compara las carpetas de las dos versiones de la aplicación:

ASP.NET Core MVC
Spring MVC
Contenido
[Program.cs]
[RdvMedecinsApplication.java], [config/]
Inicio, configuración
[Config/]
[config/]
propiedades tipadas
[Auth/]
[auth/]
Autenticación
[Controllers/]
[controllers/]
controladores
[Web/], [Models/]
[web/], [models/]
Servicios comunes de la capa web, modelos
[Business/]
[business/]
capa de negocio
[Repositories/], [Data/]
[repositories/]
capa DAO
[Entities/], [Domain/]
[entities/], [domain/]
entidades, elementos del calendario
[Views/]
[templates/]
vistas
[i18n/]
[i18n/]
diccionarios
[wwwroot/]
[static/]
archivos estáticos
[appsettings.json]
[application.properties]
Configuración
[RdvMedecins.csproj]
[pom.xml]
El archivo del proyecto

A continuación se comentan todos los archivos, desde las capas inferiores (base de datos) hasta las capas superiores (vistas).

11.5. La base de datos

La base de datos [dbrdvmedecins2] se crea mediante el script [database/dbrdvmedecins2.sql] (véase «Creación de la base de datos»). Es, palabra por palabra, el script de la versión [ASP.NET Core], precedido por una línea [SET NAMES]: ambas aplicaciones pueden trabajar sobre la misma base de datos, y una puede reemplazar a la otra sin hacer ningún cambio. Lo demostramos con dos extractos: la estructura, seguida de los datos.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Base de datos [dbrdvmedecins2] - MySQL 8
--
-- Evolución de [dbrdvmedecins]:
--   1. las tablas [doctors] y [clients] obtienen una columna [user],
--      clave externa hacia users(id): cada médico y cada cliente es
--      ahora también un usuario que puede iniciar sesión;
--   2. aparece un tercer rol: DOCTOR (además de ADMIN y USER);
--   3. el script crea una fila en [users] para cada médico (rol DOCTOR)
--      y para cada cliente (rol USER):
--        - login        = apellido en minúsculas
--        - contraseña   = apellido en minúsculas, con hash bcrypt (10 rondas)
--        - nombre visible = nombre + apellido
--
--   4. restricciones de unicidad, todas con NOMBRE (la aplicación reconoce
--      el nombre de la restricción violada en el mensaje de error de MySQL):
--        - unq_users_login                   : un login pertenece a una sola cuenta;
--        - unq_doctors_first_name_last_name  : dos médicos no pueden tener los
--                                              mismos nombre y apellido;
--        - unq_clients_first_name_last_name  : lo mismo para los clientes.
--      Atención: la collation utf8mb4_unicode_ci compara sin distinguir
--      mayúsculas ni acentos - "Hélène DUPONT" y "helene dupont"
--      se consideran, por lo tanto, idénticos.
--
-- La tabla [users] ahora debe crearse ANTES de [doctors] y [clients]
-- (las referencian), y eliminarse DESPUÉS de ellas.
-- =========================================================================

-- el script está escrito en UTF-8
SET NAMES utf8mb4;

-- se parte de una base de datos vacía en cada ejecución del script (práctico en desarrollo)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- orden de eliminación: de las tablas "hijas" a las tablas "padre"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- tabla [users]: los usuarios autorizados a iniciar sesión en la aplicación
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- un login solo puede pertenecer a una cuenta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabla [doctors]: los médicos del consultorio
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- una cuenta por médico, y un médico por cuenta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dos médicos no pueden tener los mismos nombre y apellido
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [clients]: los pacientes de los médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- una cuenta por cliente, y un cliente por cuenta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dos clientes no pueden tener los mismos nombre y apellido
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabla [slots]: los intervalos de tiempo de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- tabla [appointments]: las citas reservadas por los clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- un mismo intervalo, en el mismo día, solo puede reservarse una vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

Comentemos esta primera parte:

  • línea 30: el script le indica al servidor que está escrito en UTF-8. Sin esta línea, el cliente [mysql] de ciertos sistemas enviaría los caracteres acentuados («Hélène») con otra codificación, y se almacenarían incorrectamente;
  • línea 33: la base de datos se crea si aún no existe, con el juego de caracteres [utf8mb4] y la intercalación [utf8mb4_unicode_ci], como en el ejemplo 28: las comparaciones de cadenas ignoran las mayúsculas y los acentos. Esto también se aplica a las restricciones de unicidad: [Hélène DUPONT] y [helene dupont] son, para [MySQL], dos instancias de la misma persona, y «Admin» es el mismo nombre de usuario que «admin»;
  • líneas 37–41: el script comienza con una base de datos vacía en cada ejecución. Las tablas se eliminan desde las tablas «hijas» hacia las tablas «padre»: una tabla referenciada por una clave externa ([users], por ejemplo, referenciada por [doctors] y [clients]) no puede eliminarse mientras otra tabla aún la referencie. Las tablas se crean en el orden inverso;
  • líneas 46–55: las cuentas de usuario. Cada tabla comienza con una clave primaria [id], asignada por la base de datos ([AUTO_INCREMENT]), y una columna [version], que se establece en 0 cuando se crea la fila;
  • líneas 49–52: el nombre de usuario, la contraseña, el nombre que se muestra tras iniciar sesión y el rol ([ADMIN], [DOCTOR], o [USER]). La columna [password] nunca contiene la contraseña en sí, sino su hash, [bcrypt] (véase el ejemplo 25): 60 caracteres, que la columna (de 100 caracteres) admite sin problema;
  • Línea 54: un nombre de usuario pertenece a una sola cuenta. Como en el ejemplo 28, la restricción tiene nombre: cuando [MySQL] rechaza una operación de escritura, su mensaje de error especifica el nombre de la restricción violada, y la capa de negocio lo utiliza para elegir el mensaje que se mostrará (véase «La capa de negocio»);
  • líneas 60–72: médicos: título, apellido, nombre;
  • línea 62: la columna [version] se utiliza para el bloqueo optimista (véase el ejemplo 28): se incrementa cada vez que se modifica la fila, lo que permite detectar si otro usuario modificó la fila entre el momento en que se leyó y el momento en que se escribió. Aquí es [Hibernate] quien la incrementa, gracias a la anotación [@Version] de las entidades (véase «Entidades»);
  • Líneas 66–67: cada médico tiene una cuenta: la columna [user] es una clave externa que referencia a [users(id)]. La base de datos rechaza un valor que no se refiera a ninguna cuenta y se niega a eliminar una cuenta que todavía esté referenciada por un médico. Dado que [user] es una palabra reservada en [MySQL], el nombre de la columna se encierra entre comillas invertidas;
  • línea 69: una cuenta pertenece a un solo médico: la relación entre [doctors] y [users] es una relación «uno a uno»;
  • línea 71: dos médicos no pueden tener el mismo nombre y apellido. La restricción se aplica al par de columnas: dos médicos pueden tener el mismo apellido si no tienen el mismo nombre. En cambio, un médico y un cliente sí pueden tener el mismo apellido: son dos tablas distintas;
  • Líneas 77–89: los clientes (pacientes) siguen el mismo modelo: una cuenta por cliente (clave externa [fk_clients_user], restricción de unicidad [unq_clients_user]); dos clientes no pueden tener el mismo nombre y apellido;
  • líneas 94–103: las franjas horarias de cada médico (clave externa [doctor_id]): hora y minuto de inicio, hora y minuto de fin. Una franja horaria no tiene fecha: se repite todos los días;
  • líneas 108–118: las citas: una fecha (tipo [DATE], sin hora), una franja horaria y un cliente, identificados por dos claves externas;
  • línea 117: la misma franja horaria solo puede reservarse una vez por día. La propia base de datos impone esta regla: si dos usuarios reservan la misma franja horaria al mismo tiempo, el segundo [INSERT] es rechazado, sin importar lo que la aplicación haya verificado justo antes.

La segunda parte del script inserta los datos de ejemplo:

-- =========================================================================
-- Datos de demostración
-- =========================================================================

-- los usuarios: contraseñas con hash bcrypt (10 rondas de sal)
--   admin/admin (ADMIN)
--   una cuenta DOCTOR por médico, una cuenta USER por cliente
--   (la cuenta de demostración user/user ya no existe: una cuenta USER es
--   ahora SIEMPRE la cuenta de un cliente, que puede reservar y administrar la cuenta)
--   (login = contraseña = apellido en minúsculas)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- los médicos: la columna [user] se busca a partir del login,
-- en lugar de suponer los valores de las claves primarias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- intervalos del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en pasos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- intervalos del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en pasos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- una cita ya reservada, para ver de inmediato un intervalo ocupado en la agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • líneas 5–21: las cuentas de demostración: el administrador, tres médicos (rol [DOCTOR]) y cuatro clientes (rol [USER]). La contraseña de cada usuario es su nombre de usuario ([admin] / [admin], [pelissier] / [pelissier]...). Los hashes comienzan con [$2b$10$]: el algoritmo [bcrypt], en su versión [2b], con un costo de 10 (véase el ejemplo 25). El codificador [BCryptPasswordEncoder] de [Spring Security], configurado para esta misma versión, puede verificarlos (véase «Autenticación»);
  • líneas 25–28: la columna [user] de cada médico se obtiene mediante una subconsulta sobre el nombre de usuario, en lugar de suponer los identificadores que la base de datos asignó a las cuentas;
  • líneas 30–34: los clientes se tratan de la misma manera;
  • líneas 36–41: doce franjas horarias de 20 minutos, de 8:00 a. m. a 12:00 p. m., para el Dr. PELISSIER. Aquí, el ID del médico (1) está escrito directamente en el código: la tabla [doctors] acaba de crearse, por lo que sus ID comienzan en 1;
  • líneas 43–48: doce franjas horarias, de 2:00 p. m. a 6:00 p. m., para el Dr. TATOU. El Dr. DUPONT no tiene franjas horarias: su agenda está vacía;
  • líneas 50–52: ya se ha programado una cita para Brigitte BISTROU (cliente n.º 3) en la segunda franja horaria del Dr. PELISSIER (8:20 a. m.). [CURDATE()] es la fecha en que se ejecuta el script: en el primer inicio de sesión, el calendario de hoy muestra una franja ya reservada.

11.6. Configuración del proyecto

11.6.1. pom.xml

El archivo [pom.xml] ([Project Object Model]) describe el proyecto en [Maven]: su identificador, la versión de [Java], las bibliotecas utilizadas y la forma de iniciar la aplicación. Es el equivalente del archivo [RdvMedecins.csproj] de la versión [ASP.NET Core]. Cada ejemplo tenía su propio archivo [pom.xml], todos derivados de un archivo [pom.xml] común ubicado en la carpeta [examples]; el caso de estudio, un proyecto independiente, escribe todo en su propio archivo.

<?xml version="1.0" encoding="UTF-8"?>
<!--
  =========================================================================
  pom.xml - el archivo de proyecto Maven: identidad del proyecto, versión de Java,
  bibliotecas utilizadas y plugin que compila y ejecuta la aplicación.

  Las bibliotecas (dependencias) se descargan de Maven Central
  durante la primera compilación y se almacenan en la carpeta ~/.m2 del
  usuario. Sus versiones no se escriben aquí: las define,
  todas compatibles entre sí, el proyecto padre de Spring Boot.
  =========================================================================
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
    <relativePath/>
  </parent>

  <groupId>course.springmvc</groupId>
  <artifactId>rdvmedecins</artifactId>
  <version>1.0</version>
  <name>RdvMedecins</name>

  <properties>
    <!-- Java 21, versión LTS (soporte a largo plazo) -->
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <!-- Spring MVC y el servidor web Tomcat, integrado en la aplicación -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <!-- las vistas Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- validación de formularios (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Spring Security: autenticación con token JWT, roles, hash bcrypt -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
    </dependency>
    <!-- Spring Data JPA: el ORM Hibernate, transacciones, repositorios -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <!-- el controlador JDBC de MySQL (también sirve para MariaDB) -->
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
    </dependency>
    <!-- las herramientas de desarrollo: reinicio automático tras un cambio -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-devtools</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <!-- mvnw spring-boot:run ejecuta la aplicación, con el perfil [dev]
           (ver src/main/resources/application-dev.properties) -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
          <profiles>
            <profile>dev</profile>
          </profiles>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Comentemos este archivo:

  • Líneas 18–23: el proyecto padre, [spring-boot-starter-parent], en la versión 4.1.1 de [Spring Boot]. El proyecto hereda su configuración: la codificación UTF-8 de los archivos fuente, la configuración del compilador, la configuración de los plugins y, sobre todo, las versiones de todas las bibliotecas que [Spring Boot] puede integrar, seleccionadas para que sean compatibles entre sí. Por eso ninguna de las dependencias que se enumeran a continuación especifica su versión. Para actualizar a una versión más reciente de [Spring Boot], basta con cambiar la línea 21;
  • línea 22: el elemento vacío [relativePath] le indica a [Maven] que no busque el padre en la carpeta superior del proyecto (que es donde se encontraba el padre de los ejemplos), sino en los repositorios de bibliotecas;
  • líneas 25–28: la identidad del proyecto: el grupo (un nombre de dominio invertido, por convención), el nombre del artefacto, su versión y un nombre legible. El archivo creado por [./mvnw package] se llama [artifact-version.jar], es decir, [rdvmedecins-1.0.jar]. Como no se indica ningún elemento [packaging], se trata de un archivo [jar], que es el caso predeterminado;
  • líneas 30–33: la versión de [Java]: el compilador genera código para [Java] 21 y se niega a compilar con un JDK más antiguo;
  • líneas 35–73: las dependencias. Casi todas son starters de [Spring Boot]: un starter es una dependencia que no aporta código por sí misma, sino que incorpora un conjunto coherente de bibliotecas para una funcionalidad determinada. Cada starter también activa la autoconfiguración correspondiente al iniciar (véase «Inicio de la aplicación»);
  • líneas 37–40: [Spring MVC] y el servidor web [Tomcat], integrado en la aplicación: no es necesario instalar ningún servidor; la propia aplicación es un servidor web;
  • líneas 42–45: el motor de vistas [Thymeleaf] (véase el ejemplo 13);
  • líneas 47–50: validación de formularios: la API [Bean Validation] ([@NotBlank], [@Size]...) y su implementación, [Hibernate Validator] (véase el ejemplo 19);
  • líneas 52–55: [Spring Security], con su módulo de «servidor de recursos» [OAuth2], que permite verificar un token JWT (véase el ejemplo 25). También proporciona el hash [bcrypt] para las contraseñas: no se necesita una biblioteca aparte;
  • líneas 57–60: [Spring Data JPA], junto con el ORM, [Hibernate], el administrador de transacciones y el grupo de conexiones [HikariCP] (véase el ejemplo 28);
  • líneas 62–66: el controlador JDBC para [MySQL] y [mysql-connector-j], que también es adecuado para [MariaDB]. El alcance [runtime] (línea 65) significa que el código de la aplicación no lo necesita para compilarse (solo se comunica con JPA y JDBC); el controlador se carga únicamente en tiempo de ejecución;
  • líneas 68–72: [Spring Boot DevTools], las herramientas de desarrollo (reinicio automático). [optional] (línea 71): la dependencia no se transmite a los proyectos que dependan de este, y el plugin de [Spring Boot] no la incluye en el archivo ejecutable: solo se usa durante el desarrollo;
  • Líneas 79–87: el plugin de [Spring Boot] para [Maven]. Este plugin proporciona el comando [spring-boot:run] y, durante una ejecución de [./mvnw package], convierte el archivo [jar] estándar en un archivo ejecutable que contiene todas las bibliotecas;
  • Líneas 82–86: [spring-boot:run] activa el perfil [dev], que agrega el archivo [application-dev.properties] a la configuración (véase más abajo). Un perfil es un nombre que designa un conjunto de parámetros; este se aplica únicamente a [spring-boot:run]: una aplicación iniciada con [java -jar] no tiene ningún perfil activo a menos que se especifique uno ([java -jar target/rdvmedecins-1.0.jar --spring.profiles.active=dev]).

11.6.2. El Maven Wrapper

El Maven Wrapper permite compilar el proyecto sin tener [Maven] instalado. Consta de tres archivos:

  • [mvnw] (para [Linux] y [macOS]) y [mvnw.cmd] (para [Windows]): dos scripts, proporcionados por el proyecto [Apache Maven], que no deben modificarse y no se reproducen aquí. Leen el archivo siguiente, descargan la versión de [Maven] que allí se especifica si aún no está presente, la colocan en la carpeta [.m2/wrapper] dentro del directorio personal del usuario y luego ejecutan el comando siguiente: [./mvnw spring-boot:run] ejecuta [mvn spring-boot:run] con la versión correcta de [Maven];
  • [.mvn/wrapper/maven-wrapper.properties]:
1
2
3
wrapperVersion=3.3.4
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
  • línea 1: la versión del propio Maven Wrapper;
  • línea 2: [only-script]: el wrapper consta únicamente de los scripts [mvnw] y [mvnw.cmd], sin el archivo [maven-wrapper.jar] que usaban sus versiones anteriores;
  • línea 3: el enlace de descarga de la distribución de [Maven]: versión 3.9.11. Así, todos los que compilan el proyecto usan la misma versión de [Maven], sea cual sea la versión que pueda estar instalada en su máquina.

Las bibliotecas descargadas por [Maven] se almacenan en la carpeta [.m2/repository] dentro del directorio personal: son compartidas por todos los proyectos y se descargan una sola vez.

11.6.3. src/main/resources/application.properties

El archivo [application.properties] cumple la misma función que el archivo [appsettings.json] en la versión [ASP.NET Core]. Cada línea asocia un valor a una clave; las claves se separan con puntos ([spring.datasource.url]). [Spring Boot] contiene cientos de claves que configuran sus componentes (las que comienzan con [server.], [spring.], etc.); la aplicación puede agregar las suyas (en este caso, las que comienzan con [rdvmedecins.]). Una línea que comienza con [#] es un comentario.

# =========================================================================
# application.properties - la configuración de la aplicación.
#
# Cada valor puede reemplazarse sin modificar este archivo, mediante una
# variable de entorno: spring.datasource.password se escribe entonces
# SPRING_DATASOURCE_PASSWORD (mayúsculas, "." y "-" reemplazados por "_").
# =========================================================================

# el puerto de escucha: ni 8080 (el puerto por defecto de Spring Boot, a menudo ya
# ocupado), ni 5000 (el de los ejemplos): así todo puede ejecutarse al mismo tiempo
server.port=8081

# la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate no crea ni modifica las tablas: ese es el papel del script SQL
spring.jpa.hibernate.ddl-auto=none
# la conexión a la base de datos no se mantiene abierta mientras se construye la vista
spring.jpa.open-in-view=false

# las solicitudes se procesan mediante hilos "virtuales" (Java 21): un
# hilo que espera a la base de datos ya no bloquea un hilo del sistema
spring.threads.virtual.enabled=true

# las respuestas de error nunca contienen la traza de la pila
spring.web.error.include-stacktrace=never

# autenticación (vea config/AuthProperties.java)
# clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256).
# Debe cambiarse obligatoriamente en producción (cadena aleatoria larga).
rdvmedecins.auth.jwt-secret=change-me-to-a-long-random-string
# duración de validez de un token, en segundos (7200 s = 2 h); la cookie que
# transporta el token tiene la misma duración
rdvmedecins.auth.jwt-expires-in-seconds=7200
# true en producción (sitio servido por HTTPS): la cookie de autenticación
# nunca se envía entonces por una conexión sin cifrar
rdvmedecins.auth.cookie-secure=false

# protección contra robots (vea config/ProtectionProperties.java)
# inicio de sesión: fallos permitidos para el mismo login desde la misma dirección IP...
rdvmedecins.protection.login-max-failures=5
# ... antes de un bloqueo de esta duración (toda la dirección IP también se bloquea
# si acumula 5 veces más fallos, todos los logins juntos)
rdvmedecins.protection.login-block-minutes=15
# creación de cuentas de cliente: máximo de cuentas creadas por hora y por dirección
# IP. En un aula, todas las computadoras suelen salir por la misma dirección:
# aumente el valor si es necesario.
rdvmedecins.protection.registration-max-per-hour=10

Comentemos este archivo:

  • línea 11: el puerto de escucha del servidor [Tomcat]. El puerto predeterminado de [Spring Boot] es el 8080; los ejemplos escuchaban en el puerto 5000; la aplicación escucha en el puerto 8081, como la versión [ASP.NET Core];
  • Línea 14: la dirección de la base de datos, en forma de URL JDBC (véase el ejemplo 28): el protocolo [jdbc:mysql], seguido del servidor, el puerto y el nombre de la base de datos. [Spring Boot] la utiliza para determinar qué controlador cargar;
  • Líneas 15–16: el nombre de usuario y la contraseña de [MySQL]; de manera predeterminada, los de [Laragon] son [root], sin contraseña. La línea 16 es la que se debe completar si la cuenta [root] tiene contraseña;
  • línea 18: [Hibernate] puede crear o modificar tablas por sí mismo a partir de las entidades; aquí no las modifica: la estructura de la base de datos es la del script SQL, compartido con la versión [ASP.NET Core];
  • línea 20: de manera predeterminada, [Spring Boot] mantiene abierta la conexión a la base de datos hasta el final de la solicitud, incluso mientras se genera la vista (el modo «open in view»), y señala esta elección con una advertencia al iniciar. La aplicación desactiva este comportamiento, como se muestra en el ejemplo 28: todos los datos que necesita una vista los lee la capa de negocio, dentro de su transacción, antes de que se genere la vista. Así, una conexión nunca se mantiene abierta más tiempo del necesario;
  • Línea 24: las solicitudes las procesan hilos virtuales, una novedad de [Java] 21. Un servidor web procesa cada solicitud en un hilo (un hilo de ejecución); un hilo del sistema es un recurso costoso, y [Tomcat] mantiene solo un número limitado de ellos (200 de manera predeterminada). Sin embargo, un hilo que espera la respuesta de la base de datos no hace nada pero permanece ocupado. Un hilo virtual es un hilo ligero administrado por la máquina virtual: mientras espera, el hilo del sistema que lo alojaba ejecuta otro hilo. No es necesario modificar el código de la aplicación para aprovechar esto;
  • línea 27: las respuestas de error nunca contienen la pila de llamadas, que revelaría el funcionamiento interno de la aplicación a un atacante (véase el capítulo 1);
  • líneas 32–38: las claves de autenticación: la clave secreta que firma los tokens (de al menos 32 caracteres; debe reemplazarse en producción por una cadena aleatoria larga), la duración del token (dos horas) y la opción [Secure] de la cookie que lo transporta. En producción, el sitio se sirve mediante HTTPS y la cookie nunca debe viajar por una conexión sin cifrar: la opción se establece en [true];
  • Líneas 42–49: los umbrales de la protección contra bots (véase el ejemplo 27): el número de intentos fallidos de inicio de sesión permitidos y la duración del bloqueo resultante; el número de cuentas de cliente creadas por hora desde la misma dirección IP.

Las claves [rdvmedecins.auth.*] y [rdvmedecins.protection.*] se leen como registros tipados (véase [config/AuthProperties.java], más abajo). En el archivo, los nombres compuestos se escriben en minúsculas separadas por guiones ([jwt-secret]): esta es la convención que utiliza [Spring Boot], que los asigna a los nombres en [Java] ([jwtSecret]).

[Spring Boot] lee la configuración de varias fuentes sucesivas, cada una de las cuales puede reemplazar los valores de las anteriores: [application.properties], luego [application-{profile}.properties] para cada perfil activo (véase el archivo siguiente), luego las variables de entorno y, por último, los argumentos de la línea de comandos ([--server.port=9000]). El nombre de una variable de entorno se deriva de la clave: en mayúsculas, con [.] y [-] reemplazados por [_]. [spring.datasource.password] se convierte así en [SPRING_DATASOURCE_PASSWORD], y [rdvmedecins.auth.jwt-secret] se convierte en [RDVMEDECINS_AUTH_JWT_SECRET]: así se proporciona un secreto a la aplicación en producción sin escribirlo en un archivo del proyecto.

11.6.4. src/main/resources/application-dev.properties

1
2
3
4
5
6
# =========================================================================
# application-dev.properties - complementa application.properties cuando el
# perfil [dev] está activo (mvnw spring-boot:run lo activa, vea pom.xml):
# las sentencias SQL enviadas por Hibernate se muestran en la consola.
# =========================================================================
spring.jpa.show-sql=true
  • Línea 6: cuando el perfil [dev] está activo, [Spring Boot] lee el archivo [application-dev.properties] después de [application.properties] y fusiona ambos: las claves presentes en el segundo archivo reemplazan a las del primero; las demás se conservan. Durante el desarrollo, se agrega por lo tanto la clave [spring.jpa.show-sql]: [Hibernate] escribe en la consola cada comando SQL que envía a la base de datos, precedido por [Hibernate:]. Esto equivale al archivo [appsettings.Development.json] de la versión [ASP.NET Core], donde el perfil hace las veces del entorno [Development]. Hemos visto que es [pom.xml] quien activa este perfil para [spring-boot:run].

11.6.5. config/AuthProperties.java

// =========================================================================
// config/AuthProperties.java
// -------------------------------------------------------------------------
// Las propiedades [rdvmedecins.auth.*] de application.properties, como
// un record tipado. Spring Boot hace corresponder los nombres:
//   rdvmedecins.auth.jwt-secret             -> jwtSecret
//   rdvmedecins.auth.jwt-expires-in-seconds -> jwtExpiresInSeconds
//   rdvmedecins.auth.cookie-secure          -> cookieSecure
// y convierte los valores al tipo de los componentes (int, boolean).
// Una clase que lo necesita recibe este record por inyección de dependencias:
// así evitamos leer cadenas de caracteres por todas partes.
// =========================================================================
package rdvmedecins.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("rdvmedecins.auth")
public record AuthProperties(
        // clave secreta usada para firmar / verificar los tokens JWT. El algoritmo HMAC-SHA256
        // exige una clave de al menos 256 bits, es decir, 32 bytes.
        String jwtSecret,
        // duración de validez de un token, en segundos; la cookie que lo transporta
        // tiene la misma duración
        int jwtExpiresInSeconds,
        // true en producción (HTTPS): la cookie de autenticación nunca se
        // envía por una conexión sin cifrar
        boolean cookieSecure) {
}

Comentemos este código:

  • línea 18: las claves [rdvmedecins.auth.*] de [application.properties], en forma de record: una clase cuyos campos, declarados entre paréntesis (los «componentes» del record), se establecen de una vez por todas mediante el constructor. El compilador genera este constructor por sí mismo, junto con un método getter para cada componente, con el mismo nombre: [jwtSecret()], [jwtExpiresInSeconds()], [cookieSecure()];
  • Línea 17: la anotación [@ConfigurationProperties] especifica el prefijo de las claves. Al iniciar, [Spring Boot] crea el record llamando a su constructor con los valores de las claves [rdvmedecins.auth.jwt-secret], [rdvmedecins.auth.jwt-expires-in-seconds] y [rdvmedecins.auth.cookie-secure], convertidos al tipo de cada componente (["7200"] se convierte en el entero 7200, [false] se convierte en el booleano [false]). Un valor que no puede convertirse (texto donde se espera un número) hace que la aplicación falle al iniciar, con un mensaje que indica la clave problemática. Una clave ausente da como resultado el valor predeterminado del tipo: [null], 0 o [false];
  • líneas 21–27: los tres componentes. El record se convierte en un bean, que una clase que lo necesite recibe mediante su constructor (inyección de dependencias; véase el ejemplo 06): esto es lo que hacen [config/SecurityConfig.java] y [auth/AuthService.java] (véase «Autenticación»). Esto evita tener que leer cadenas de caracteres por todas partes: el compilador verifica los nombres y los valores ya están convertidos.

Esta es la técnica utilizada en el ejemplo 25, que declaraba su record mediante la anotación [@EnableConfigurationProperties(JwtProperties.class)]. El caso de estudio tiene dos de ellos y deja que [Spring Boot] los encuentre por sí mismo, gracias a la anotación [@ConfigurationPropertiesScan] de la clase principal (véase «Inicio de la aplicación»).

11.6.6. config/ProtectionProperties.java

// =========================================================================
// config/ProtectionProperties.java
// -------------------------------------------------------------------------
// Las propiedades [rdvmedecins.protection.*]: los umbrales de la protección
// contra robots (vea auth/AttemptLimiterService.java).
// =========================================================================
package rdvmedecins.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("rdvmedecins.protection")
public record ProtectionProperties(
        // inicio de sesión: número de fallos (captcha o contraseña incorrectos) permitidos
        // para el mismo login desde la misma dirección IP, antes de que este par se bloquee...
        int loginMaxFailures,
        // ... durante esta duración (una dirección IP también se bloquea si acumula
        // 5 veces más fallos, todos los logins juntos)
        int loginBlockMinutes,
        // creación de cuentas de cliente: número máximo de cuentas creadas por hora
        // desde la misma dirección IP
        int registrationMaxPerHour) {
}
  • Líneas 11–21: las claves [rdvmedecins.protection.*], siguiendo el mismo patrón. El registro se inyecta en [auth/AttemptLimiterService.java], que lee de allí sus umbrales (véase “Autenticación”).

11.7. Inicio de la aplicación

La versión [ASP.NET Core] consolidó toda la funcionalidad relacionada con el inicio en [Program.cs]: el registro de cada servicio y luego la construcción del pipeline de middleware en un orden específico. Con [Spring Boot], este trabajo se reparte: la clase principal se limita a iniciar [Spring Boot], que a su vez configura por sí mismo lo esencial, según las bibliotecas disponibles y [application.properties]; y cada aspecto que la aplicación quiere configurar de otra manera tiene su propia clase de configuración, ubicada en la carpeta [config].

11.7.1. RdvMedecinsApplication.java

// =========================================================================
// RdvMedecinsApplication.java
// -------------------------------------------------------------------------
// El punto de entrada de la aplicación: el método main inicia Spring Boot.
//
// @SpringBootApplication reúne tres anotaciones:
//   - @Configuration: la clase puede declarar beans (@Bean);
//   - @EnableAutoConfiguration: Spring Boot mismo configura lo que las
//     bibliotecas presentes requieren (Spring MVC, Thymeleaf, JPA, Spring
//     Security...), según application.properties;
//   - @ComponentScan: Spring busca las clases anotadas (@Controller,
//     @Service, @Component, @Repository...) en el paquete [rdvmedecins] y
//     sus subpaquetes, y las convierte en beans, que proporciona a quienes
//     los necesitan (inyección de dependencias).
//
// @ConfigurationPropertiesScan: los records anotados con @ConfigurationProperties
// (paquete config) reciben los valores de application.properties.
//
// Aquí no hay equivalente al "pipeline de middleware" del Program.cs de ASP.NET
// Core: el orden de los filtros lo fijan Spring Boot y Spring Security, y
// cada aspecto se configura en su propia clase (config/SecurityConfig,
// config/WebConfig...).
// =========================================================================
package rdvmedecins;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class RdvMedecinsApplication {

    public static void main(String[] args) {
        SpringApplication.run(RdvMedecinsApplication.class, args);
    }
}

Comentemos este código:

  • líneas 34–36: el método [main], el punto de entrada de todo programa [Java], como se vio en los ejemplos. [SpringApplication.run] crea el contenedor de [Spring] (el “contexto de aplicación”, que crea y administra todos los beans), inicia el servidor [Tomcat] y luego devuelve el control; el programa sigue en ejecución mientras el servidor esté escuchando. La clase pasada como parámetro sirve como punto de partida de la configuración;
  • línea 30: la anotación [@SpringBootApplication]—que ya estaba presente en todos los ejemplos—combina las tres anotaciones detalladas en el comentario del archivo (líneas 6–14). [@ComponentScan] hace que [Spring] recorra el paquete [rdvmedecins] y todos sus subpaquetes: cada clase anotada—[@Controller], [@Service], [@Component] (o [@Configuration], [@ControllerAdvice]...)—se convierte en un bean dentro de él. Las interfaces de repositorio de [Spring Data JPA] se encuentran de la misma manera, en los mismos paquetes, mediante la autoconfiguración de [Spring Data JPA] (véase más adelante). Por lo tanto, a diferencia de [Program.cs], no hay una lista de servicios que mantener: basta con agregar una clase anotada a uno de estos paquetes. Por eso la clase principal se ubica en el paquete raíz, por encima de todos los demás;
  • línea 31: [@ConfigurationPropertiesScan] hace lo mismo con los records anotados con [@ConfigurationProperties] (véase [config/AuthProperties.java]).

Los beans de la aplicación son todos singletons: una única instancia compartida por todas las solicitudes. La versión [ASP.NET Core] distinguía tres ciclos de vida ([Singleton], [Scoped], [Transient]) porque su capa DAO dependía de una instancia de [DbContext] creada para cada solicitud. Con [Spring], los repositorios y la capa de negocio no dependen de ninguna solicitud: es [Spring] quien proporciona a cada tarea de procesamiento una conexión tomada del pool de conexiones (un conjunto de conexiones abiertas, reutilizadas de una consulta a la siguiente) y, para las escrituras de la capa de negocio, su transacción. Este punto se trata con más detalle en las secciones sobre la capa DAO y la capa de negocio.

11.7.2. Lo que Spring Boot configura automáticamente

[@EnableAutoConfiguration], contenida en [@SpringBootApplication], activa la autoconfiguración: al iniciarse, [Spring Boot] examina las bibliotecas presentes en el classpath y los beans ya declarados por la aplicación, y crea por sí mismo los beans que faltan, configurados según [application.properties]. La consola de inicio, mostrada arriba, permite seguir este proceso:

Qué se configura
Presente gracias a
Registros de la consola
el servidor [Tomcat], en el puerto [server.port]
[spring-boot-starter-webmvc]
[Tomcat initialized with port 8081], luego [Tomcat started on port 8081]
el servlet [DispatcherServlet], el controlador frontal de [Spring MVC], que recibe todas las solicitudes y las distribuye entre las acciones
[spring-boot-starter-webmvc]
[Initializing Servlet 'dispatcherServlet'], en la primera solicitud
los archivos estáticos de la carpeta [static/], servidos tal cual ([/css/styles.css]...)
[spring-boot-starter-webmvc]
ninguno
el motor [Thymeleaf]: la vista [schedule] es el archivo [templates/schedule.html]
[spring-boot-starter-thymeleaf]
ninguno
el validador de formularios ([Hibernate Validator])
[spring-boot-starter-validation]
ninguno
La fuente de datos ([DataSource]): un pool de conexiones [HikariCP] hacia la URL [spring.datasource.url]
[spring-boot-starter-data-jpa], [mysql-connector-j]
[HikariPool-1 - Start completed]
[Hibernate] (la “fábrica” de [EntityManager] y de [JPA]), el administrador de transacciones y el bean [TransactionTemplate] que usa la capa de negocio
[spring-boot-starter-data-jpa]
[Hibernate ORM core version 7.4.5.Final], [Database info], [Initialized JPA EntityManagerFactory]
una implementación de cada una de las cinco interfaces de repositorio de la carpeta [repositories/] (la sexta, [PersonRepository], un modelo común a médicos y clientes, está marcada como [@NoRepositoryBean]: [Spring Data JPA] no la implementa)
[spring-boot-starter-data-jpa]
[Found 5 JPA repository interfaces]
reinicio automático y desactivación de la caché de vistas de [Thymeleaf]
[spring-boot-devtools]
[Devtools property defaults active!], [restartedMain]

Comentemos algunas líneas de esta consola:

  • [The following 1 profile is active: "dev"]: el perfil activado por [pom.xml]; por lo tanto, se lee [application-dev.properties] ;
  • [restartedMain] es el nombre del hilo que inicia la aplicación: el de [Spring Boot DevTools], que la reiniciará después de cada recompilación. Al lanzarla con [java -jar], sin DevTools, la aplicación se inicia en el hilo [main];
  • la advertencia [HHH000511] aparece solo con [MariaDB] (véase “Problemas comunes”);
  • las dos líneas [Hibernate: select ...] son las consultas de carga de la caché (véase más adelante), mostradas gracias al perfil [dev]. Aquí se ve el join que [Hibernate] dedujo a partir de las entidades para recuperar cada médico junto con su cuenta [users];
  • [Tomcat started on port 8081] aparece después de estas consultas: el servidor solo acepta solicitudes una vez que se han creado todos los beans, incluida la caché;
  • Las tres últimas líneas solo aparecen con la primera solicitud: [Spring Boot] inicializa [DispatcherServlet] solo cuando es necesario. Su hilo, [tomcat-handler-0] (del cual la consola solo muestra el final del nombre), es un hilo virtual (véase [application.properties]).

La autoconfiguración queda en segundo plano frente a la aplicación: solo crea un bean si la aplicación no ha declarado uno con el mismo rol. Así es como la aplicación reemplaza los valores predeterminados que no se ajustan a sus necesidades:

  • seguridad: sin configuración, [Spring Boot] protegería todas las páginas con un formulario de inicio de sesión y una contraseña generada al arrancar; [config/SecurityConfig.java] declara su propia cadena de filtros y su propio decodificador de tokens JWT (véase “Autenticación”);
  • las traducciones: el bean [messageSource], que [Thymeleaf] utiliza para sus expresiones [#{...}], es la clase [web/Translator.java], que lee los diccionarios JSON (véanse el ejemplo 22 y “La capa web: servicios compartidos”);
  • la página de error: los errores (400, 403, 404, 500...) son gestionados por el servidor en la dirección [/error]. [Spring Boot] normalmente coloca allí su propio controlador; [controllers/ErrorController.java] ocupa su lugar (véanse el ejemplo 24 y “La capa web: controladores”);
  • el idioma de cada solicitud y los atributos Flash: son los dos beans de [config/WebConfig.java], que se tratan a continuación.

Tampoco hay, como en [Program.cs], un pipeline de middleware que configurar: cada solicitud pasa por la cadena de filtros de [Spring Security]—cuyo orden determina [Spring Security] mismo—antes de llegar a [DispatcherServlet], que selecciona la acción según las anotaciones del controlador (véase el ejemplo 24).

11.7.3. config/WebConfig.java

// =========================================================================
// config/WebConfig.java
// -------------------------------------------------------------------------
// Los agregados a la configuración de Spring MVC:
//   - el idioma de cada solicitud, leído de una cookie (vea el ejemplo 22);
//   - los atributos flash, almacenados en una cookie (vea web/CookieFlashMapManager).
// Los archivos estáticos de la carpeta src/main/resources/static (css/, js/,
// lib/bootstrap/) los sirve Spring Boot sin configuración.
// =========================================================================
package rdvmedecins.config;

import java.time.Duration;
import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.FlashMapManager;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;

import rdvmedecins.web.CookieFlashMapManager;

@Configuration
public class WebConfig {

    // el idioma de cada solicitud: el de la cookie [rdvmedecins_language],
    // establecida por LanguageController; inglés en caso contrario. El bean debe llamarse
    // [localeResolver]: con ese nombre lo busca Spring MVC.
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("rdvmedecins_language");
        resolver.setDefaultLocale(Locale.ENGLISH);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSameSite("Lax");
        return resolver;
    }

    // los atributos flash en una cookie, y no en la sesión HTTP. El bean
    // debe llamarse [flashMapManager]: reemplaza entonces al de Spring MVC.
    @Bean
    public FlashMapManager flashMapManager() {
        return new CookieFlashMapManager();
    }
}

Comentemos este código:

  • línea 23: una clase anotada con [@Configuration] declara beans mediante métodos anotados con [@Bean] (véase el ejemplo 06). Al iniciarse, [Spring] llama una vez a cada uno de estos métodos y almacena el objeto resultante como un bean. El bean lleva el nombre del método;
  • Línea 30: [LocaleResolver] determina el idioma ([Locale]) de cada solicitud. [Spring MVC] lo busca con el nombre [localeResolver]: es el nombre del método lo que lo convierte en el reemplazo de [Spring Boot], que seguiría el idioma preferido del navegador;
  • Línea 31: el idioma se lee de la cookie [rdvmedecins_language], como en el ejemplo 22. Este mismo objeto establece la cookie cuando [controllers/LanguageController.java] le envía el idioma seleccionado (botones FR / EN);
  • línea 32: sin cookie, el idioma es el inglés;
  • líneas 33–35: la cookie dura un año; es [HttpOnly] (el script de la página no puede leerla) y [SameSite=Lax] (el navegador no la envía en las solicitudes hechas por otro sitio, salvo al navegar simplemente hacia la aplicación);
  • Líneas 41–44: [FlashMapManager] conserva los atributos Flash entre un POST y la redirección posterior (el patrón Post/Redirect/Get; véase el ejemplo 20). El bean de [Spring MVC] los almacena en la sesión HTTP; sin embargo, la aplicación es sin estado: no conserva ningún dato del usuario entre solicitudes, ya que el usuario se identifica mediante el token JWT de su cookie. Por lo tanto, el bean llamado [flashMapManager] reemplaza al llamado igual de [Spring MVC] con la clase [web/CookieFlashMapManager.java], que almacena los atributos flash en una cookie (véase “La capa web: servicios comunes”).

11.7.4. Carga de la caché al iniciar

Las listas de médicos y de clientes se muestran en casi todas las páginas (listas desplegables en el calendario, páginas de administración). En lugar de recuperarlas de la base de datos en cada solicitud, la aplicación las mantiene en memoria dentro del bean [web/ApplicationModel.java], por el que pasan todos los controladores. Este bean las vuelve a cargar después de cada alta, modificación o eliminación de un médico o un cliente.

La carga inicial se realiza al iniciar, en un método de este bean anotado con [@PostConstruct]. Esta anotación indica a [Spring] que llame al método una vez creado el objeto e inyectadas sus dependencias (en este caso, la capa de negocio): por lo tanto, durante el arranque, antes de que el servidor acepte la primera solicitud. Son las dos consultas [Hibernate: select ...] de la consola. Un error de lectura no se captura: la aplicación se detiene de inmediato, y el error aparece en la consola. Una base de datos inaccesible (error en la URL, servidor [MySQL] detenido) detiene la aplicación incluso antes, en cuanto se inicializa [Hibernate] (véase “Problemas comunes”).

Para esta carga, la versión [ASP.NET Core] tenía que crear explícitamente un “scope” en [Program.cs], porque su fachada dependía del [DbContext] de una solicitud. Aquí no ocurre así: [ApplicationModel] es un singleton, igual que la capa de negocio que utiliza. El archivo se documenta en la sección “La capa web: servicios comunes”.

11.7.5. De Program.cs de ASP.NET Core a Spring Boot

Para los lectores familiarizados con la versión [ASP.NET Core], aquí se indica dónde se ubica cada parte de [Program.cs]:

Program.cs (ASP.NET Core)
Spring Boot
[WebApplication.CreateBuilder(args)] ... [app.Run()]
[SpringApplication.run(...)] ([RdvMedecinsApplication.java])
[builder.Services.AddScoped<...>()], una llamada por servicio
[@ComponentScan]: clases anotadas [@Service], [@Component], [@Controller]... ; las interfaces de registro (autoconfiguración de [Spring Data JPA]); los métodos [@Bean] de las clases [@Configuration]
[Configure<AuthOptions>(...)] y [IOptions<AuthOptions>]
records [@ConfigurationProperties] y [@ConfigurationPropertiesScan]
[AddDbContext] y [UseMySql]
Configuración automática de la fuente de datos y de [Hibernate], a partir de [spring.datasource.*]
[AddControllersWithViews]
Autoconfiguración de [DispatcherServlet] y de [Thymeleaf]
[AddJwtAuthentication], [UseAuthentication], [UseAuthorization]
[config/SecurityConfig.java] (cadena de filtros de [Spring Security])
[UseStaticFiles] (carpeta [wwwroot])
Automático (carpeta [static])
[UseRequestLocalization] y [CookieRequestCultureProvider]
bean [localeResolver] ([CookieLocaleResolver], [config/WebConfig.java])
[TempData] (cookie)
bean [flashMapManager] ([CookieFlashMapManager], [config/WebConfig.java])
[UseExceptionHandler], [UseStatusCodePagesWithReExecute]
la dirección [/error], procesada por [controllers/ErrorController.java]
[CreateScope()], luego [LoadAsync()], antes de [app.Run()]
método [@PostConstruct] de [web/ApplicationModel.java]
[appsettings.Development.json] y [ASPNETCORE_ENVIRONMENT]
[application-dev.properties] y el perfil [dev]
[dotnet watch]
[Spring Boot DevTools]

11.8. Las entidades

Las entidades [JPA] se asignan a las tablas de la base de datos y a las clases [Java] (véase el ejemplo 28). Cada clase de entidad se anota como [@Entity]; sus campos se asocian con columnas mediante anotaciones ([@Column], [@Id], [@JoinColumn]...) del paquete [jakarta.persistence]. Estas anotaciones son las definidas en el estándar [JPA] (Jakarta Persistence); [Hibernate], la implementación del estándar utilizada por [Spring Boot], las lee al iniciar la aplicación para determinar qué clase corresponde a qué tabla y qué campo a qué columna. La base de datos no la crea [Hibernate], sino el script SQL [database/dbrdvmedecins2.sql] (véase la sección “La base de datos”): las entidades solo deben describir con exactitud las tablas que ya existen.

Las entidades de la aplicación se encuentran en la carpeta [entities]:

Archivo
Tabla
Rol
[AbstractEntity.java]
-
Los campos comunes [id] y [version] (bloqueo optimista)
[Person.java]
-
Campos comunes a médicos y clientes: [title], [lastName], [firstName], y la cuenta de usuario
[Doctor.java]
[doctors]
un médico
[Client.java]
[clients]
un paciente
[Slot.java]
[slots]
una franja horaria de citas de un médico
[Appointment.java]
[appointments]
una cita
[User.java]
[users]
una cuenta de usuario
[Role.java]
-
una lista de los tres roles

11.8.1. entities/AbstractEntity.java

// =========================================================================
// entities/AbstractEntity.java
// -------------------------------------------------------------------------
// Los dos campos comunes a todas las entidades: el identificador [id] y el
// número de versión [version] (bloqueo optimista).
//
// @MappedSuperclass: esta clase no tiene tabla; sus campos se agregan
// a las tablas de las clases hijas (Doctor, Client, Slot, Appointment, User).
//
// Las anotaciones @Id, @Column, @Version... provienen del estándar JPA (Jakarta
// Persistence, paquete jakarta.persistence): Hibernate las lee al iniciar
// para saber qué clase va en qué tabla, qué campo en qué columna.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.Version;

@MappedSuperclass
public abstract class AbstractEntity {

    // la clave primaria, generada por la base de datos (columna AUTO_INCREMENT): Hibernate
    // vuelve a leer su valor después de cada INSERT. Integer (y no int): una entidad
    // aún no guardada tiene un id null.
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Integer id;

    // @Version: el bloqueo optimista. Cada UPDATE enviado por Hibernate lleva
    // la condición "WHERE id = ... AND version = <valor leído>", y escribe la
    // versión incrementada en 1. Si alguien modificó la fila entretanto,
    // no se actualiza ninguna fila: Hibernate lanza una excepción
    // (OptimisticLockException, que Spring traduce a
    // ObjectOptimisticLockingFailureException, vea business/BusinessService.java).
    @Version
    @Column(name = "version")
    private Integer version;

    public Integer getId() {
        return id;
    }

    public Integer getVersion() {
        return version;
    }
}
  • Línea 23: [@MappedSuperclass] designa una clase padre sin tabla: no corresponde a ninguna tabla, pero sus campos y sus anotaciones se agregan a los de sus clases hijas. Todas las entidades de la aplicación heredan de ella y, por lo tanto, tienen un identificador y una versión. La clase es además [abstract]: nunca se crea un objeto [AbstractEntity];
  • líneas 29–32: la clave primaria ([@Id]), columna [id]. [@GeneratedValue(strategy = GenerationType.IDENTITY)] indica que el valor lo genera la base de datos (columna [AUTO_INCREMENT]): [Hibernate] envía [INSERT] sin identificador y luego lee el que asignó la base de datos. Punto clave para recordar más adelante: el [INSERT] de una nueva entidad se envía inmediatamente al llamar a [save], porque [Hibernate] necesita el identificador de inmediato. El tipo es [Integer], no [int]: un [Integer] puede ser igual a [null], que es el caso de una entidad que aún no ha sido registrada;
  • Líneas 40–42: la versión de la fila, para el bloqueo optimista (véase el ejemplo 28). Con [@Version], [Hibernate] hace todo el trabajo: cada [UPDATE] que envía lleva la condición [WHERE id = ... AND version = <value read>] y escribe la versión incrementada en 1. Si otra persona modificó la fila mientras tanto, no se actualiza ninguna fila y [Hibernate] lanza una excepción, que [Spring] traduce en [ObjectOptimisticLockingFailureException] (véase “La capa de negocio”). Esto difiere de [Entity Framework Core], donde la aplicación debía incrementar ella misma la versión antes de cada guardado;
  • Líneas 44–50: accesores de solo lectura. No hay métodos llamados [setId] ni [setVersion]: estos valores solo los escribe [Hibernate]. Como la anotación [@Id] se coloca sobre un campo (y no sobre un método [getId]), [Hibernate] lee y escribe los campos directamente—incluso los privados—sin pasar por los accesores. Esto se conoce como acceso por campo.

11.8.2. entities/Person.java

// =========================================================================
// entities/Person.java
// -------------------------------------------------------------------------
// Clase padre (sin tabla) de las entidades [Doctor] y [Client]: un título, un
// apellido, un nombre - y la cuenta de usuario asociada (columna [user]).
//
// Una relación declarada en una @MappedSuperclass la heredan las
// clases hijas exactamente igual que las columnas: la relación [user] existe por lo tanto
// en la tabla [doctors] Y en la tabla [clients].
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.OneToOne;

@MappedSuperclass
public abstract class Person extends AbstractEntity {

    @Column(name = "title", length = 5)
    private String title; // Melle, Mme, Mr

    @Column(name = "last_name", length = 20)
    private String lastName;

    @Column(name = "first_name", length = 20)
    private String firstName;

    // -----------------------------------------------------------------------
    // La relación con la cuenta de usuario: un médico (un cliente) tiene UNA
    // cuenta, y una cuenta pertenece a UNA persona (columna [user] UNIQUE).
    //   - @OneToOne: relación "uno a uno";
    //   - fetch = LAZY: el User se lee de la base de datos solo si se solicita (en la
    //     consulta, vea @EntityGraph en repositories/, o al acceder al campo
    //     durante una transacción);
    //   - @JoinColumn: la columna de la clave externa. Las comillas invertidas
    //     (`user`) piden a Hibernate "proteger" este nombre, que es una
    //     palabra reservada de MySQL.
    // -----------------------------------------------------------------------
    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "`user`")
    private User user;

    // la misma columna, leída como un simple número: así conocemos el id de la
    // cuenta sin cargar el User. insertable / updatable = false: es el campo
    // [user] de arriba el que escribe la columna, este solo la lee.
    @Column(name = "`user`", insertable = false, updatable = false)
    private Integer userId;

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }

    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }

    public User getUser() { return user; }
    public void setUser(User user) { this.user = user; }

    public Integer getUserId() { return userId; }
}
  • Líneas 19–20: la clase padre—que tampoco tiene tabla asociada ([@MappedSuperclass])—de [Doctor] y de [Client], hija a su vez de [AbstractEntity]. Los médicos y los clientes tienen las mismas columnas: se declaran una sola vez;
  • líneas 22–29: el título (Sra., Sr., etc.), el apellido y el nombre. El atributo [length] de [@Column] especifica el ancho de la columna; en realidad solo se usa si [Hibernate] crea las tablas por sí mismo, lo cual no ocurre aquí (véase la sección “JPA, Hibernate y Spring Data”): no es una regla de validación, sino simplemente una documentación fiel del script SQL;
  • Líneas 42–44: la relación con la cuenta de usuario, en forma de un campo de tipo [User] (el objeto mismo, no su identificador). [@OneToOne] define una relación “uno a uno”: un médico (o un cliente) tiene una cuenta, y una cuenta pertenece como máximo a una persona (la columna [user] es [UNIQUE] en el script SQL). [@JoinColumn] indica la columna que contiene la clave externa. [fetch = FetchType.LAZY] especifica la carga diferida: cuando [Hibernate] lee una persona, no lee su cuenta; en su lugar, el campo [user] recibe un proxy, un objeto que suplanta al [User] y solo leerá la fila de la tabla [users] en la primera llamada a uno de sus métodos, y solo si la transacción sigue abierta. Para recuperar a la persona junto con su cuenta, la consulta debe solicitarlo explícitamente (véase “La capa DAO”);
  • Línea 43: [user] es una palabra reservada en [MySQL]: si se escribe tal cual en una consulta SQL, provocaría un error de sintaxis. Los acentos graves que rodean el nombre en [@JoinColumn] indican a [Hibernate] que proteja ese nombre: lo encerrará entre acentos graves en cada comando SQL, como hace el script SQL;
  • Líneas 49–50: la misma columna [user], esta vez leída como un simple número. Esto permite determinar el identificador de la cuenta sin cargar la cuenta misma: la capa de negocio lo usa para eliminar la cuenta de una persona. Una columna solo puede ser escrita por un campo: [insertable = false, updatable = false] indica que este campo solo la lee y que es el campo [user] el que escribe en ella (en [INSERT] y [UPDATE]);
  • líneas 52–64: los accesores. Una clase cuyos campos privados se leen mediante métodos llamados [getXxx] y se escriben mediante métodos llamados [setXxx] sigue la convención JavaBean; las vistas de [Thymeleaf] se basan en esta convención ([${doctor.lastName}] llama a [getLastName()]). No existe [setUserId]: el campo [userId] es de solo lectura.

Esta es la consulta SQL, capturada en la consola de la aplicación, que [Hibernate] envía para recuperar a un médico y su cuenta (véase [findWithUserById] en la capa DAO). Aquí se ve la columna [user] con sus acentos graves y el join con la tabla [users]:

Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` where d1_0.id=?

La columna [user] de la tabla [doctors] (también conocida como [d1_0]) se lee una sola vez, aunque le corresponden dos campos: [Hibernate] la usa para completar el campo [userId] y vincula el campo [user] con el registro recuperado por el join. [?] es un parámetro de la consulta (el identificador del médico) que se envía por separado a la base de datos.

11.8.3. entities/Doctor.java

// =========================================================================
// entities/Doctor.java
// -------------------------------------------------------------------------
// Un médico del consultorio (tabla [doctors]).
//
// Restricción SQL de unicidad: unq_doctors_first_name_last_name (dos médicos no pueden
// tener el mismo nombre y apellido) - creada por el script SQL,
// reconocida por su nombre en la capa de negocio.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

// @Entity: una clase cuyos objetos son las filas de una tabla;
// @Table: el nombre de esta tabla
@Entity
@Table(name = "doctors")
public class Doctor extends Person {
}
  • línea 17: [@Entity] define la clase como una entidad: sus objetos son filas de una tabla;
  • línea 18: [@Table] da a esta tabla el nombre [doctors]. Sin ella, [Hibernate] buscaría una tabla con el mismo nombre que la clase;
  • Línea 19: la clase hereda todos sus campos de [Person], y el identificador y la versión de [AbstractEntity]. No tiene constructor explícito: el compilador de [Java] le proporciona entonces un constructor predeterminado—público y sin parámetros—, que es exactamente lo que exige [JPA] (véase [Appointment.java]) y lo que usará la capa de negocio ([Doctor::new]). La restricción de unicidad [unq_doctors_first_name_last_name], mencionada en el comentario, la crea el script SQL; la capa de negocio la reconoce por su nombre.

A diferencia de la versión [ASP.NET Core], [Doctor] no declara la relación inversa con sus franjas horarias (una lista [@OneToMany]): la aplicación no la usaría; lee las franjas horarias de un médico a través de la capa DAO.

11.8.4. entities/Client.java

// =========================================================================
// entities/Client.java
// -------------------------------------------------------------------------
// Atención: [Client] aquí designa a un PACIENTE del consultorio médico, ¡no a un
// cliente HTTP! Es el vocabulario del dominio de negocio original, conservado
// tal cual (tabla [clients]).
//
// Restricción SQL de unicidad: unq_clients_first_name_last_name (vea Doctor.java).
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

@Entity
@Table(name = "clients")
public class Client extends Person {
}

Un cliente, es decir, un paciente del consultorio (no un cliente HTTP): una [Person] de la tabla [clients] (líneas 15–17), sin campos adicionales.

11.8.5. entities/Slot.java

// =========================================================================
// entities/Slot.java
// -------------------------------------------------------------------------
// Una franja horaria de un médico (tabla [slots]): 8:00 - 8:20, etc.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;

@Entity
@Table(name = "slots")
public class Slot extends AbstractEntity {

    @Column(name = "start_hour")
    private int startHour; // hora de inicio de la franja

    @Column(name = "start_minute")
    private int startMinute; // minuto de inicio de la franja

    @Column(name = "end_hour")
    private int endHour; // hora de fin de la franja

    @Column(name = "end_minute")
    private int endMinute; // minuto de fin de la franja

    // varias franjas para el mismo médico: @ManyToOne ("muchos a uno"),
    // clave externa [doctor_id]. Misma técnica que Person.user / userId.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "doctor_id")
    private Doctor doctor;

    @Column(name = "doctor_id", insertable = false, updatable = false)
    private Integer doctorId;

    public int getStartHour() { return startHour; }
    public int getStartMinute() { return startMinute; }
    public int getEndHour() { return endHour; }
    public int getEndMinute() { return endMinute; }
    public Doctor getDoctor() { return doctor; }
    public Integer getDoctorId() { return doctorId; }
}
  • líneas 19–29: las horas y los minutos de inicio y de fin de la franja horaria, de tipo [int]: estas columnas están declaradas como [NOT NULL] en la base de datos; un tipo primitivo—que no puede ser [null]—les resulta adecuado;
  • Líneas 33–35: la relación “muchos a uno” con el médico ([@ManyToOne]): varias franjas horarias para un médico, clave externa en la columna [doctor_id]; el médico se carga de forma diferida ([LAZY]). La misma técnica que para la cuenta de una persona;
  • líneas 37–38: la misma columna [doctor_id], de solo lectura, en forma de número. Las consultas del tipo “franjas horarias del médico n.º 2” apuntarán a este campo, sin tener que cargar al médico;
  • líneas 40–45: accesores de solo lectura: la aplicación nunca crea ni modifica franjas horarias (las crea el script SQL).

De forma predeterminada, una relación [@ManyToOne] se carga de inmediato ([EAGER]): leer una franja horaria leería también a su médico y luego la cuenta de ese médico... En cambio, todas las relaciones de la aplicación se declaran como [LAZY], y cada consulta solicita explícitamente las relaciones que necesita: así se sabe exactamente qué SQL se envía.

11.8.6. entities/Appointment.java

// =========================================================================
// entities/Appointment.java
// -------------------------------------------------------------------------
// Una cita (tabla [appointments]): un cliente, en una franja, en un día dado.
//
// Restricción SQL de unicidad: unq1_appointments (day, slot_id) - una franja se
// reserva una sola vez por día. Creada por el script SQL, reconocida por su
// nombre en la capa de negocio.
// =========================================================================
package rdvmedecins.entities;

import java.time.LocalDate;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;

@Entity
@Table(name = "appointments")
public class Appointment extends AbstractEntity {

    // LocalDate: una fecha SIN hora, que corresponde exactamente al tipo SQL
    // DATE de la columna [day]
    @Column(name = "day")
    private LocalDate day;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "client_id")
    private Client client;

    @Column(name = "client_id", insertable = false, updatable = false)
    private Integer clientId;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "slot_id")
    private Slot slot;

    @Column(name = "slot_id", insertable = false, updatable = false)
    private Integer slotId;

    // JPA exige un constructor sin parámetros (Hibernate crea con él los
    // objetos leídos de la base de datos)
    protected Appointment() {
    }

    // una nueva cita
    public Appointment(LocalDate day, Slot slot, Client client) {
        this.day = day;
        this.slot = slot;
        this.client = client;
    }

    public LocalDate getDay() { return day; }
    public Client getClient() { return client; }
    public Integer getClientId() { return clientId; }
    public Slot getSlot() { return slot; }
    public Integer getSlotId() { return slotId; }
}
  • línea 22: la tabla de citas. Su restricción de unicidad [unq1_appointments (day, slot_id)] garantiza que una franja horaria se reserve una sola vez por día;
  • líneas 27–28: el día de la cita. El tipo [LocalDate] (paquete [java.time]) representa una fecha sin hora: corresponde exactamente al tipo SQL [DATE] de la columna [day], sin importar la zona horaria. [Hibernate] realiza la conversión en ambos sentidos;
  • líneas 30–42: el cliente y la franja horaria de la cita: dos relaciones “muchos a uno”, cada una definida con un campo de objeto (que llena la columna) y un campo numérico de solo lectura ([clientId], [slotId]);
  • Líneas 46–47: [JPA] exige que toda entidad tenga un constructor sin parámetros: [Hibernate] usa este constructor para crear los objetos que lee de la base de datos antes de llenar sus campos. En cuanto una clase declara un constructor (líneas 50–54), el compilador ya no le proporciona un constructor predeterminado: por lo tanto, hay que escribirlo. Se declara como [protected]: [Hibernate] puede usarlo, pero el resto de la aplicación, que no lo ve, se ve obligado a usar el constructor completo. [JPA] acepta un constructor [public] o [protected], pero no [private]: [Hibernate] crea sus delegados (proxies) definiendo clases hijas de las entidades, y una clase hija debe poder llamar al constructor de su padre (por eso mismo una clase de entidad no debe declararse como [final]);
  • líneas 50–54: el constructor de una nueva cita: una fecha, una franja horaria y un cliente. Llena los campos de objeto [slot] y [client], que establecen las claves externas; los campos de solo lectura [clientId] y [slotId] solo se llenarán cuando se lea una cita de la base de datos;
  • Líneas 56–60: accesores de solo lectura: una cita nunca se modifica, solo se crea o se elimina.

11.8.7. entities/Role.java

// =========================================================================
// entities/Role.java
// -------------------------------------------------------------------------
// Los tres roles de un usuario (columna users.role):
//   - ADMIN  : el administrador - citas + gestión de médicos y clientes;
//   - DOCTOR : un médico - reserva y cancela citas;
//   - USER   : un cliente (paciente) - reserva para sí mismo, gestiona su cuenta.
//
// Una enumeración (enum): el compilador rechaza cualquier otro valor. JPA
// la almacena en la base de datos como TEXT ('ADMIN'...), igual que el script SQL
// (vea @Enumerated en User.java).
// =========================================================================
package rdvmedecins.entities;

public enum Role {
    ADMIN,
    DOCTOR,
    USER
}
  • líneas 15–19: los tres roles, en forma de una enumeración ([enum]): una variable de tipo [Role] solo puede tener el valor [Role.ADMIN], [Role.DOCTOR], [Role.USER] (o [null]), y el compilador rechaza cualquier otro valor. [Role] no es una entidad: es el tipo de un campo de [User]. Cada valor tiene un nombre ([name()] devuelve ["ADMIN"]) y un número de orden ([ordinal()] devuelve 0 para [ADMIN]): esta es la elección entre ambos, para la base de datos, que [@Enumerated] realiza en [User.java].

11.8.8. entities/User.java

// =========================================================================
// entities/User.java
// -------------------------------------------------------------------------
// Un usuario autorizado a iniciar sesión en la aplicación (tabla [users]).
// Cada médico y cada cliente tiene SU cuenta de usuario (columna [user]
// de las tablas [doctors] y [clients], vea Person.java).
//
// Restricción SQL de unicidad: unq_users_login (un login pertenece a una sola
// cuenta). La crea el script database/dbrdvmedecins2.sql;
// la capa de negocio la reconoce por su NOMBRE (vea business/BusinessService.java).
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.Table;

@Entity
@Table(name = "users")
public class User extends AbstractEntity {

    @Column(name = "login", length = 30)
    private String login;

    // la contraseña con HASH (bcrypt) - nunca en claro
    @Column(name = "password", length = 100)
    private String password;

    // el nombre que se muestra una vez iniciada la sesión - para un médico o un cliente:
    // "firstName LASTNAME" (p. ej. "Marie PELISSIER")
    @Column(name = "name", length = 40)
    private String name;

    // ADMIN, DOCTOR o USER, almacenado en la base de datos como texto (STRING) y no
    // como número ordinal (ORDINAL: 0, 1, 2)
    @Enumerated(EnumType.STRING)
    @Column(name = "role", length = 10)
    private Role role;

    public String getLogin() { return login; }
    public void setLogin(String login) { this.login = login; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public Role getRole() { return role; }
    public void setRole(Role role) { this.role = role; }
}
  • Líneas 20–22: las cuentas de los usuarios autorizados a iniciar sesión: el administrador, cada médico y cada cliente. La restricción [unq_users_login] prohíbe dos cuentas con el mismo nombre de usuario;
  • líneas 24–25: el nombre de usuario;
  • líneas 28–29: el hash [bcrypt] de la contraseña, nunca la contraseña misma (véase el ejemplo 25);
  • líneas 33–34: el nombre que se muestra en la barra de navegación una vez iniciada la sesión (“Marie PELISSIER”);
  • líneas 38–40: el rol. De forma predeterminada, [JPA] almacenaría una enumeración en la base de datos por su número de orden ([EnumType.ORDINAL]: 0, 1, 2), lo que tendría dos inconvenientes: la columna [role] del script SQL contiene texto, y agregar en algún momento un valor en medio de la enumeración alteraría el orden de los números ya registrados. [@Enumerated(EnumType.STRING)] almacena el nombre del valor (['ADMIN']...) y lo convierte de nuevo en [Role] al leerlo;
  • Líneas 42–52: los getters. La clase [User] no declara una relación con el médico o el cliente que la posee: la relación solo se conoce del lado de [Person], que contiene la clave externa.

11.9. JPA, Hibernate y Spring Data

La versión [ASP.NET Core] de la aplicación contenía una clase llamada [DbContext], que era el componente central de [Entity Framework Core]: mantenía la conexión, daba acceso a las tablas, hacía el seguimiento de las entidades cargadas y enviaba los cambios a la base de datos. La versión [Spring] no tiene un equivalente escrito a mano: estas funciones se reparten entre objetos que [Spring Boot] crea por sí mismo al iniciar, según la configuración. Esta sección explica quién hace qué; no corresponde a ningún archivo [Java] del proyecto.

11.9.1. Tres capas

El acceso a datos se basa en tres capas, que el starter [spring-boot-starter-data-jpa] proporciona en conjunto (véase la sección “Configuración del proyecto”):

  • [JPA] (Jakarta Persistence) es un estándar: un conjunto de interfaces y anotaciones ([@Entity], [EntityManager]...), sin ningún código que las haga funcionar;
  • [Hibernate] es una implementación de este estándar: lee las anotaciones de las entidades, escribe los comandos SQL, los envía a la base de datos mediante JDBC ([mysql-connector-j]) y convierte las filas resultantes en objetos [Java];
  • [Spring Data JPA] agrega sobre esto los repositorios: basta con describir un DAO mediante una interfaz, y [Spring] escribirá la implementación (véase “La capa DAO”).

11.9.2. El EntityManager y el contexto de persistencia

El objeto central de [JPA] es el [EntityManager] (el “administrador de entidades”): se encarga de leer ([find]), guardar ([persist]) y eliminar ([remove]) entidades, así como de ejecutar consultas. Administra un contexto de persistencia: el conjunto de entidades que ha leído o guardado, llamadas entidades “administradas”. Para cada entidad administrada, conserva una copia del estado tal como se leyó de la base de datos. En el momento de la sincronización con la base de datos (el *flush*), que ocurre a más tardar justo antes del [COMMIT] de la transacción, compara cada entidad con su copia y envía por sí mismo un [UPDATE] para cada una que haya cambiado (*dirty checking*). Por lo tanto, no hay ningún método “guardar los cambios” al que llamar: basta con modificar una entidad administrada. Un contexto de persistencia también garantiza que una misma fila esté representada por un solo objeto: leer dos veces al médico n.º 1 dentro de la misma transacción devuelve dos veces el mismo objeto [Java].

Este es exactamente el “seguimiento de cambios” de [DbContext] de [Entity Framework Core], con una diferencia importante: con [Spring], el contexto de persistencia está ligado a la transacción. Se crea al inicio de la transacción y se cierra al final de esta ([COMMIT] o [ROLLBACK]). Las entidades que administraba pasan entonces a estar desasociadas: son objetos [Java] ordinarios a los que ya nadie da seguimiento. Modificarlos ya no tiene ningún efecto en la base de datos, y sus relaciones [LAZY] que no se hayan cargado ya no pueden cargarse.

La aplicación nunca manipula directamente el [EntityManager]: los repositorios de [Spring Data JPA] se encargan de ello en su nombre. Cuando se llama a un método de un repositorio mientras hay una transacción en curso (abierta por la capa de negocio), este usa el [EntityManager] de esa transacción: todos los repositorios llamados durante la transacción comparten, por lo tanto, el mismo contexto de persistencia, la misma conexión y la misma transacción. Cuando no hay ninguna transacción en curso, los métodos heredados de [JpaRepository] ([findById], [save]...) abren una transacción breve durante la llamada (de solo lectura para las operaciones de lectura); las consultas declaradas en nuestras interfaces ([findAllByOrderByLastNameAscFirstNameAsc], los métodos [@Query], etc.) se ejecutan sin transacción: [Spring] crea un [EntityManager] durante la llamada y luego lo cierra. En ambos casos, las entidades devueltas quedan desasociadas de inmediato.

11.9.3. La configuración

Todo lo que [Hibernate] necesita lo produce [Spring Boot] (esta es la autoconfiguración) a partir de las claves [spring.datasource.*] y [spring.jpa.*] del archivo [application.properties] (véase la sección “Configuración del proyecto”):

1
2
3
4
5
6
7
8
# la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate no crea ni modifica las tablas: ese es el papel del script SQL
spring.jpa.hibernate.ddl-auto=none
# la conexión a la base de datos no se mantiene abierta mientras se construye la vista
spring.jpa.open-in-view=false
  • Líneas 2–4: las claves [spring.datasource.*] describen la conexión: la URL de la base de datos y JDBC (el protocolo [jdbc:mysql:], la máquina, el puerto y el nombre de la base de datos), el nombre de usuario y la contraseña. [Spring Boot] crea en realidad un [DataSource], un pool de conexiones. Abrir una conexión a una base de datos consume muchos recursos: este [DataSource] es un pool de conexiones (la biblioteca [HikariCP]), que mantiene abiertas unas cuantas conexiones y las presta por turnos;
  • Línea 6: [ddl-auto=none]: [Hibernate] no crea ni modifica tablas (podría crearlas a partir de las entidades, con el valor [create], o actualizarlas con [update]): la base de datos la describe el script SQL, y solo este;
  • Línea 8: [open-in-view=false] cierra el [EntityManager] en cuanto termina la transacción, sin mantenerlo abierto hasta el final de la solicitud HTTP (véase más adelante).

A partir de [DataSource] y de las entidades, [Spring Boot] crea también [EntityManagerFactory] (que crea los [EntityManager]), un administrador de transacciones ([JpaTransactionManager]) y un [TransactionTemplate], que la capa de negocio utiliza para abrir sus transacciones. El dialecto SQL (las particularidades de [MySQL]: [limit], acentos graves, etc.) se deduce automáticamente de la base de datos a la que se conecta.

El archivo [application-dev.properties], que también se lee cuando el perfil [dev] está activo (como ocurre con [./mvnw spring-boot:run]), agrega la clave [spring.jpa.show-sql=true]: [Hibernate] muestra entonces en la consola cada comando SQL que envía. Todas las consultas que aparecen en este capítulo se capturaron de esta manera.

En comparación con [DbContext] de la versión [ASP.NET Core], faltan dos elementos porque ya no son necesarios: la lista de tablas (las entidades se encuentran automáticamente porque están en el paquete de la aplicación o en uno de sus subpaquetes) y los detalles de [OnModelCreating] (la relación “uno a uno” la especifica [@OneToOne], la conversión del rol a texto, [@Enumerated], y el incremento de la versión, [@Version]).

11.9.4. open-in-view=false: cargar explícitamente las relaciones

De forma predeterminada ([spring.jpa.open-in-view=true]), [Spring Boot] abre un [EntityManager] al inicio de cada solicitud HTTP y lo cierra solo después de generar la vista: una vista puede entonces leer una relación [LAZY] no cargada ([${appointment.client.lastName}]), y [Hibernate] envía la consulta necesaria en el momento de mostrarla. Esto es cómodo, pero entonces se pueden enviar consultas SQL desde cualquier lugar, incluso desde una vista [Thymeleaf], la conexión permanece ocupada durante todo el proceso de renderizado de la página, y un bucle con 20 eventos puede disparar 20 consultas pequeñas en lugar de una (el llamado problema “N+1”). [Spring Boot] también muestra una advertencia al iniciar cuando no se especifica la clave.

La aplicación elige [open-in-view=false]: [EntityManager] se cierra al final de cada transacción (o de cada llamada a un repositorio hecha fuera de una transacción), y las entidades que salen de la capa de negocio quedan desasociadas. El resultado es una regla que debe cumplirse en todas partes: cada lectura carga explícitamente las relaciones que necesitará la página, mediante [@EntityGraph] o [join fetch] (véase “La capa DAO”). Leer una relación [LAZY] que no se ha cargado—por ejemplo, la cuenta de un médico leída por una consulta que no la solicitó—provocaría una [LazyInitializationException]: ya no se puede leer nada; el [EntityManager] está cerrado. En cambio, se sabe exactamente qué consultas se envían y cuándo: todas están en la capa DAO.

11.10. El dominio: el calendario

La carpeta [domain] contiene dos clases que no corresponden a ninguna tabla: describen la agenda de un médico para un solo día, calculada por la capa de negocio ([BusinessService.getDoctorDaySchedule]) y mostrada por el controlador de la agenda.

11.10.1. domain/DoctorDaySlot.java

// =========================================================================
// domain/DoctorDaySlot.java
// -------------------------------------------------------------------------
// Un objeto "de negocio" (sin tabla) que asocia una franja horaria con la
// cita posiblemente reservada en esa franja, en un día dado.
//
// Un record de Java es una clase cuyos campos los establece de una vez por
// todas el constructor (objeto inmutable): exactamente lo que se necesita
// para un objeto calculado, que nadie modifica después.
// =========================================================================
package rdvmedecins.domain;

import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Appointment;

// appointment: null si la franja está libre ese día
public record DoctorDaySlot(Slot slot, Appointment appointment) {
}
  • Línea 17: una franja horaria y la cita programada en esa franja ese día, o [null] si la franja está libre. Un record (a partir de [Java] 16) declara una clase en una sola línea, cuyos campos se establecen de una vez por todas mediante el constructor: el compilador mismo escribe los campos privados y [final] (no modificables), el constructor de dos parámetros, los accesores [slot()] y [appointment()] (sin el prefijo [get]) y los métodos [equals], [hashCode] y [toString]. El cuerpo del record, encerrado entre llaves, está vacío aquí. Ya nos hemos encontrado con los records para los datos transmitidos a la capa de negocio (véase el ejemplo 28).

11.10.2. domain/DoctorDaySchedule.java

// =========================================================================
// domain/DoctorDaySchedule.java
// -------------------------------------------------------------------------
// La agenda completa de un médico para un día dado: la lista de sus
// franjas horarias, cada una libre u ocupada por una cita. Calculada por
// BusinessService.getDoctorDaySchedule, convertida en una tabla HTML por
// ScheduleController.
// =========================================================================
package rdvmedecins.domain;

import java.time.LocalDate;
import java.util.List;

import rdvmedecins.entities.Doctor;

public record DoctorDaySchedule(Doctor doctor, LocalDate day, List<DoctorDaySlot> doctorDaySlots) {
}

La agenda (línea 16): un médico, un día y la lista de sus franjas horarias—disponibles o reservadas—en orden cronológico. Las vistas de [Thymeleaf] pueden leer los accesores de un record: [${schedule.day}] llama a [day()].

11.11. La capa DAO

Un DAO por tabla, como en el ejemplo 28: métodos sin lógica de negocio, que simplemente consultan o modifican la base de datos. Aquí se denominan repositorios. Con [Spring Data JPA], un repositorio es una simple interfaz: al iniciar la aplicación, [Spring] genera una clase que la implementa, la convierte en un bean y la inyecta donde se necesita. La interfaz hereda de [JpaRepository<T, ID>] ([T]: el tipo de la entidad; [ID]: el tipo de su clave primaria), que proporciona los métodos estándar: [findById], [findAll], [save], [deleteById], [getReferenceById]... Las consultas específicas de la aplicación se agregan de tres maneras:

  • por nombre de método: [Spring Data JPA] analiza el nombre ([find] ... [By] *criterios* [OrderBy] *orden*) y deduce de él la consulta. Un error en el nombre de un campo se detecta al iniciar, lo que provoca que el proceso falle;
  • en JPQL, con la anotación [@Query]. [JPQL] (Jakarta Persistence Query Language) es el lenguaje de consultas de [JPA]: se parece a SQL, pero hace referencia a las entidades y sus campos ([Appointment], [a.client]), en lugar de a las tablas y sus columnas. [Hibernate] lo traduce a SQL;
  • en SQL, con [@Query(nativeQuery = true)], cuando [JPQL] no es suficiente.

Los métodos que pueden no devolver nada devuelven un [Optional<T>] (paquete [java.util]): una caja que contiene un objeto o está vacía. El llamador no puede usar el resultado sin comprobar antes si existe ([isPresent()], [orElseThrow(...)]...): no hay ningún [null] olvidado.

Al igual que las entidades, los repositorios no gestionan transacciones: las abre la capa de negocio.

11.11.1. repositories/PersonRepository.java

Los repositorios de médicos y de clientes serían idénticos: una interfaz genérica los escribe una sola vez.

// =========================================================================
// repositories/PersonRepository.java
// -------------------------------------------------------------------------
// La capa DAO común a los médicos y los clientes.
//
// Con Spring Data JPA, un DAO es una simple INTERFAZ: Spring escribe
// su implementación él mismo al iniciar. JpaRepository<T, Integer> ya
// aporta findById, findAll, save, delete...; le agregamos nuestras consultas:
//   - ya sea por el NOMBRE del método, que Spring Data traduce a una consulta
//     (findFirstByFirstNameAndLastName -> ... WHERE first_name = ? AND last_name = ? LIMIT 1);
//   - o mediante una consulta JPQL escrita en una anotación @Query. JPQL
//     se parece a SQL, pero trabaja con las clases y sus campos, no con
//     las tablas y sus columnas.
//
// Los DAO de los médicos y de los clientes serían idénticos: esta
// interfaz GENÉRICA los escribe una sola vez, siendo T Doctor o Client.
// @NoRepositoryBean: Spring no crea un DAO para esta interfaz
// misma, solo para sus subinterfaces DoctorRepository y
// ClientRepository. En las consultas, #{#entityName} designa la entidad de
// la subinterfaz (Doctor o Client).
//
// Transacciones: todos los métodos DAO de una misma solicitud HTTP
// usan la transacción actual, si existe (vea BusinessService).
// =========================================================================
package rdvmedecins.repositories;

import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.NoRepositoryBean;

import rdvmedecins.entities.Person;

@NoRepositoryBean
public interface PersonRepository<T extends Person> extends JpaRepository<T, Integer> {

    // lista ordenada por apellido y luego por nombre, cuenta de usuario incluida.
    // @EntityGraph(attributePaths = "user"): trae TAMBIÉN la cuenta, mediante un
    // join (SELECT ... FROM doctors LEFT JOIN users ...). Sin él, la
    // cuenta solo se leería en el primer acceso - imposible fuera de una
    // transacción: estas listas se conservan en memoria en la caché
    // (web/ApplicationModel.java), mucho después del fin de la solicitud.
    @EntityGraph(attributePaths = "user")
    List<T> findAllByOrderByLastNameAscFirstNameAsc();

    // una persona y su cuenta
    @EntityGraph(attributePaths = "user")
    Optional<T> findWithUserById(int id);

    // la persona cuya cuenta de usuario es [userId]
    @EntityGraph(attributePaths = "user")
    Optional<T> findByUserId(int userId);

    // la persona que tiene este nombre y apellido, si existe. La comparación
    // la hace MySQL, por lo tanto con la collation de la base de datos
    // (utf8mb4_unicode_ci: sin distinguir mayúsculas ni acentos) -
    // exactamente la misma regla que la de la restricción SQL de unicidad.
    Optional<T> findFirstByFirstNameAndLastName(String firstName, String lastName);

    // un DELETE enviado directamente a la base de datos, sin leer antes a la persona.
    // @Modifying: la consulta modifica datos (no es un SELECT)
    @Modifying
    @Query("delete from #{#entityName} p where p.id = :id")
    void remove(int id);
}

Comentemos este código:

  • línea 39: [PersonRepository<T extends Person>] es una interfaz genérica: [T] es un parámetro de tipo, reemplazado por un tipo real ([Doctor] o [Client]) en las subinterfaces, como [T] en [List<T>]. [extends Person] solo acepta [Person] o sus clases hijas para [T]: en las consultas, [T] incluye por lo tanto necesariamente los campos [lastName], [firstName], [user], [userId]... La interfaz hereda de [JpaRepository<T, Integer>]: entidad [T], clave primaria de tipo [Integer];
  • línea 38: [@NoRepositoryBean] indica a [Spring Data JPA] que no cree un repositorio para esta interfaz misma, que no se refiere a ninguna entidad concreta ([T] es desconocido), sino solo para sus subinterfaces [DoctorRepository] y [ClientRepository];
  • líneas 47–48: todas las personas, ordenadas por apellido y luego por nombre. El nombre del método es la consulta: [findAll] (la palabra [All] se incluye únicamente por legibilidad), [By] sin criterios (todas las filas), [OrderByLastNameAscFirstNameAsc] (orden ascendente por apellido y luego por nombre). [@EntityGraph(attributePaths = "user")] exige que la relación [user] se cargue también en la misma consulta mediante un join; sin ella, el campo [user] de cada persona sería un proxy sin cargar. Esto es esencial aquí: estas listas se conservan en memoria en la caché ([web/ApplicationModel.java]) mucho después de terminada la transacción, y las vistas muestran el nombre de usuario de cada persona;
  • Líneas 51–52: una persona y su cuenta, o un [Optional] vacío. [JpaRepository] ya proporciona [findById], pero sin la cuenta; no se le puede agregar [@EntityGraph] sin cambiar todos sus usos. Por eso se declara otro método: en el nombre de un método, [Spring Data JPA] ignora el texto entre [find] y [By] (aquí, [WithUser]), que sirve solo para indicar al lector lo que devuelve el método. La consulta es la de [findById] ([where id = ?]), y [@EntityGraph] le agrega el join;
  • líneas 55–56: la persona cuya cuenta es [userId]: el criterio se aplica al campo [userId] (de solo lectura) y, por lo tanto, directamente a la columna [user]. Así es como un paciente con sesión iniciada, cuyo token contiene el identificador de la cuenta, recupera su ficha de cliente;
  • línea 62: un posible homónimo. [First] limita el resultado a una sola fila ([limit ?] en SQL), [ByFirstNameAndLastName] cumple ambos criterios, unidos por [and]. Los parámetros del método se asocian con los criterios en orden. La comparación la realiza [MySQL], según la collation de la base de datos, sin distinguir mayúsculas de minúsculas ni acentos, exactamente igual que la restricción de unicidad;
  • líneas 66–68: la eliminación de una persona mediante una consulta [JPQL] [delete], enviada directamente a la base de datos sin leer antes a la persona (el equivalente de [ExecuteDeleteAsync] de [Entity Framework Core]). [@Modifying] indica que la consulta modifica datos: sin ella, [Spring Data JPA] la trataría como un [select]. Una consulta de este tipo debe ejecutarse dentro de una transacción que permita escrituras: la capa de negocio abre esta transacción. No pasa por el contexto de persistencia y, por lo tanto, tampoco por el bloqueo optimista;
  • Línea 67: la interfaz es genérica, pero una consulta [JPQL] debe especificar una entidad concreta: [delete from Doctor] o [delete from Client]. [#{...}] introduce una expresión SpEL (Spring Expression Language, el lenguaje de expresiones de [Spring]), que se evalúa al iniciar; la variable [#entityName] designa el nombre de la entidad en el repositorio concreto. Para [DoctorRepository], la consulta se convierte en [delete from Doctor p where p.id = :id];
  • líneas 67–68: [:id] es un parámetro con nombre de la consulta, asociado con el parámetro [id] del método (por nombre). Su valor se envía a la base de datos por separado del texto de la consulta: no hay concatenación de cadenas, por lo que no es posible una inyección SQL.

Estas son las consultas que realmente envía [Hibernate] para la lista de clientes (línea 48) y para buscar un homónimo entre los médicos (línea 62):

Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version from doctors d1_0 where d1_0.first_name=? and d1_0.last_name=? limit ?

La primera recupera los clientes y sus cuentas en una sola consulta ([left join users]); la segunda, sin [@EntityGraph], recupera únicamente la tabla [doctors].

11.11.2. repositories/DoctorRepository.java

// =========================================================================
// repositories/DoctorRepository.java
// -------------------------------------------------------------------------
// El DAO de los médicos: todo se hereda de PersonRepository.
// Spring Data construye su implementación al iniciar.
// =========================================================================
package rdvmedecins.repositories;

import rdvmedecins.entities.Doctor;

public interface DoctorRepository extends PersonRepository<Doctor> {
}

El repositorio de médicos (línea 11): [PersonRepository<Doctor>], sin nada más. Es esta interfaz—y no [@NoRepositoryBean]—la que [Spring Data JPA] implementa: todos los métodos heredados en ella se refieren a la entidad [Doctor].

11.11.3. repositories/ClientRepository.java

// =========================================================================
// repositories/ClientRepository.java
// -------------------------------------------------------------------------
// El DAO de los clientes: el de las personas, más un método de bloqueo.
// =========================================================================
package rdvmedecins.repositories;

import java.util.Optional;

import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Client;

public interface ClientRepository extends PersonRepository<Client> {

    // -----------------------------------------------------------------------
    // pone un BLOQUEO en la fila de un cliente hasta el final de la
    // transacción actual (SELECT ... FOR UPDATE), y devuelve su id
    // (Optional vacío si el cliente no existe). Una segunda transacción que
    // solicite el mismo bloqueo ESPERA a que la primera termine.
    // Se usa para reservar una cita (vea BusinessService.addAppointment):
    // dos reservas simultáneas para el mismo paciente se procesan así
    // una DESPUÉS de la otra, y la segunda ve la cita creada por la primera.
    //
    // nativeQuery = true: la consulta es SQL, enviada tal cual a la base de datos,
    // y no JPQL traducido por Hibernate. JPA también puede poner este bloqueo
    // (@Lock(LockModeType.PESSIMISTIC_WRITE) en una consulta JPQL), pero
    // Hibernate escribe entonces "FOR UPDATE OF c1_0", una sintaxis de MySQL 8 que
    // MariaDB (el "MySQL" de algunas distribuciones) rechaza. Este SQL
    // funciona con ambos.
    // :id es un PARÁMETRO de la consulta (sin concatenación de cadenas,
    // por lo tanto sin inyección SQL posible).
    // -----------------------------------------------------------------------
    @Query(value = "select id from clients where id = :id for update", nativeQuery = true)
    Optional<Integer> lock(int id);
}
  • Línea 14: el repositorio de clientes—el de las personas, con [T = Client], más un método;
  • Líneas 34–35: lectura de un cliente con un bloqueo. [SELECT ... FOR UPDATE] coloca un bloqueo sobre la fila hasta el final de la transacción en curso: otra transacción que solicite el mismo bloqueo espera hasta que la primera termine. La función de programación de citas ([BusinessService.addAppointment]) lo utiliza para procesar una tras otra dos reservas simultáneas para el mismo paciente: la segunda reserva ve la cita creada por la primera y, por lo tanto, respeta la regla de “una sola cita próxima”. El método devuelve solo el identificador del cliente ([select id]) en un [Optional] vacío si el cliente no existe: se usa únicamente para adquirir el bloqueo y verificar la existencia del cliente;
  • línea 34: [nativeQuery = true]: la consulta es en SQL, enviada tal cual a la base de datos, y no en [JPQL]. Sin embargo, [JPA] puede establecer este bloqueo por sí mismo: la anotación [@Lock(LockModeType.PESSIMISTIC_WRITE)], agregada a una consulta en [JPQL], indica a [Hibernate] que le añada la cláusula de bloqueo. Pero para [MySQL] 8, [Hibernate] escribe entonces [for update of c1_0] (el bloqueo se aplica solo a la tabla indicada), una sintaxis propia de [MySQL] 8 que [MariaDB]—que a menudo se instala en lugar de [MySQL]—rechaza. El SQL escrito a mano, [for update] sin [of], funciona con ambos. [:id] es, una vez más, un parámetro de la consulta.

La consulta, tal como aparece en la consola durante una reserva:

Hibernate: select id from clients where id = ? for update

11.11.4. repositories/SlotRepository.java

// =========================================================================
// repositories/SlotRepository.java
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Slot].
// =========================================================================
package rdvmedecins.repositories;

import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Slot;

public interface SlotRepository extends JpaRepository<Slot, Integer> {

    // una franja y su médico
    @EntityGraph(attributePaths = "doctor")
    Optional<Slot> findWithDoctorById(int id);

    // las franjas de un médico, en orden cronológico
    List<Slot> findByDoctorIdOrderByStartHourAscStartMinuteAsc(int doctorId);

    // elimina todas las franjas de un médico (eliminación de un médico):
    //   DELETE FROM slots WHERE doctor_id = ?
    @Modifying
    @Query("delete from Slot s where s.doctorId = :doctorId")
    void deleteByDoctor(int doctorId);
}
  • línea 18: un repositorio normal: entidad [Slot], clave primaria [Integer];
  • líneas 21–22: una franja horaria y su médico ([@EntityGraph(attributePaths = "doctor")]), siguiendo el modelo de [findWithUserById];
  • línea 25: las franjas horarias de un médico, en orden cronológico: [ByDoctorId] filtra por el campo [doctorId] (es decir, la columna [doctor_id]), [OrderByStartHourAscStartMinuteAsc] ordena por hora y luego por minuto de inicio. [Hibernate] envía [select ... from slots s1_0 where s1_0.doctor_id=? order by s1_0.start_hour,s1_0.start_minute];
  • Líneas 29–31: eliminación de las franjas horarias de un médico mediante un único [DELETE]. La capa de negocio llama a este método antes de eliminar al médico; de lo contrario, la clave externa [slots.doctor_id] impediría la eliminación. El método no se llama [deleteByDoctorId]: un nombre así también sería interpretado por [Spring Data JPA], pero la consulta deducida primero leería las franjas horarias y luego las eliminaría una por una; la consulta [@Query] envía un solo comando, [DELETE].

11.11.5. repositories/AppointmentRepository.java

// =========================================================================
// repositories/AppointmentRepository.java
// -------------------------------------------------------------------------
// Capa DAO de la entidad [Appointment].
//
// Las consultas JPQL navegan de una entidad a otra mediante los campos de
// relación (a.slot.doctorId): Hibernate escribe él mismo los joins SQL
// necesarios. "join fetch" también trae la entidad unida (el equivalente
// de un @EntityGraph).
// =========================================================================
package rdvmedecins.repositories;

import java.time.LocalDate;
import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Appointment;

public interface AppointmentRepository extends JpaRepository<Appointment, Integer> {

    // una cita, su cliente y su franja
    @Query("select a from Appointment a join fetch a.client join fetch a.slot where a.id = :id")
    Optional<Appointment> read(int id);

    // las citas de un médico en un día dado, cliente y franja incluidos.
    // La tabla [appointments] no referencia directamente al médico: pasamos por la franja.
    @Query("""
            select a from Appointment a join fetch a.client join fetch a.slot s
            where s.doctorId = :doctorId and a.day = :day""")
    List<Appointment> doctorDayAppointments(int doctorId, LocalDate day);

    // las citas de un cliente a partir del día [fromDay] (incluido), en
    // orden cronológico, con la franja Y el médico de esta franja
    @Query("""
            select a from Appointment a join fetch a.slot s join fetch s.doctor
            where a.clientId = :clientId and a.day >= :fromDay
            order by a.day, s.startHour, s.startMinute""")
    List<Appointment> clientUpcomingAppointments(int clientId, LocalDate fromDay);

    // número de citas de un cliente a partir del día [fromDay] (incluido)
    long countByClientIdAndDayGreaterThanEqual(int clientId, LocalDate fromDay);

    // número de citas (pasadas o futuras) de un médico
    @Query("select count(a) from Appointment a where a.slot.doctorId = :doctorId")
    long countByDoctor(int doctorId);

    // elimina una cita: DELETE FROM appointments WHERE id = ?
    @Modifying
    @Query("delete from Appointment a where a.id = :id")
    void remove(int id);

    // elimina TODAS las citas (pasadas y futuras) de un cliente
    @Modifying
    @Query("delete from Appointment a where a.clientId = :clientId")
    void deleteByClient(int clientId);
}

Comentemos este código:

  • Líneas 26–27: una cita con su cliente y su franja horaria. En [JPQL], [join fetch a.client] realiza un join y carga la entidad unida en el resultado: es el equivalente, escrito en la consulta, de [@EntityGraph]. Un join se realiza siguiendo un campo de relación ([a.client]): [Hibernate] conoce la clave externa ([@JoinColumn]) y escribe por sí mismo la condición [on]. Con [@Query], el nombre del método es arbitrario: la consulta escrita es la que se ejecuta. El nombre [findById] ya está ocupado por el método heredado de [JpaRepository], que no carga ni el cliente ni la franja horaria;
  • Líneas 31–34: las citas de un médico para un día dado, cada una con su cliente y su franja horaria. La consulta se escribe en un bloque de texto [Java] (desde [Java] 15): una cadena delimitada por tres comillas ["""], que puede ocupar varias líneas. La tabla [appointments] no hace referencia directa a los médicos: se pasa por la franja horaria, a la que el join asigna el alias [s], y luego se filtra por [s.doctorId]. [a.day = :day] compara dos fechas: [Hibernate] pasa [LocalDate] como un valor SQL [DATE];
  • Líneas 38–42: las citas de un paciente a partir del día [fromDay], junto con su franja horaria y el médico asignado a esa franja: [join fetch s.doctor] sigue la relación de la franja horaria a su médico (dos joins en cascada). El orden se basa en el día y luego en la hora de la franja horaria. Esto es lo que muestra “Mi cuenta”. El médico asignado no tiene su propia ficha ([user]): la página no la necesita;
  • Línea 45: el número de citas de un cliente a partir del día [fromDay], para la regla de “una sola cita próxima”: [count] genera un [select count(...)], [GreaterThanEqual] genera la comparación [>=]. El resultado es de tipo [long];
  • Líneas 48–49: el número de citas que tiene un médico, para impedir la eliminación de un médico que tenga alguna. [a.slot.doctorId] sigue la relación [slot] sin [join fetch]: [Hibernate] agrega el join con [slots] para filtrar, sin cargar nada;
  • líneas 52–54: cancelación de una cita mediante una llamada directa a [DELETE] . [JpaRepository] sí proporciona [deleteById], pero este método primero lee la cita y luego la elimina;
  • líneas 57–59: eliminación de todas las citas de un cliente, pasadas y futuras: la capa de negocio llama a este método antes de eliminar al cliente, algo que la clave externa [appointments.client_id] impediría de otro modo.

Esta es la consulta de la línea 42, tal como [Hibernate] la traduce a SQL: los dos [join fetch]s se han convertido en dos joins, y las columnas de la franja horaria y del médico se leen al mismo tiempo que las de la cita:

Hibernate: select a1_0.id,a1_0.client_id,a1_0.day,s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version,a1_0.slot_id,a1_0.version from appointments a1_0 join slots s1_0 on s1_0.id=a1_0.slot_id join doctors d1_0 on d1_0.id=s1_0.doctor_id where a1_0.client_id=? and a1_0.day>=? order by a1_0.day,s1_0.start_hour,s1_0.start_minute

Observe que un [join fetch] produce un inner join ([join]), mientras que el [@EntityGraph] de [PersonRepository] producía un outer join ([left join]): aquí, toda cita debe tener una franja horaria, y toda franja horaria debe tener un médico.

11.11.6. repositories/UserRepository.java

// =========================================================================
// repositories/UserRepository.java
// -------------------------------------------------------------------------
// Capa DAO de la entidad [User]. Crear (o eliminar) un médico o un
// cliente también crea (o elimina) su cuenta - vea business/BusinessService.java.
// =========================================================================
package rdvmedecins.repositories;

import java.util.Optional;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.User;

public interface UserRepository extends JpaRepository<User, Integer> {

    // Optional.empty() si ningún usuario tiene este login
    Optional<User> findByLogin(String login);

    @Modifying
    @Query("delete from User u where u.id = :id")
    void remove(int id);
}
  • Línea 20: la cuenta asociada a este nombre de usuario, o un [Optional] vacío. Se usa para iniciar sesión ([AuthService]) y para verificar que un nombre de usuario esté disponible antes de asignarlo;
  • Líneas 22–24: eliminación de una cuenta mediante una llamada directa a [DELETE]. El orden es inverso al de la creación: la capa de negocio elimina primero a la persona, que hace referencia a la cuenta, y luego elimina la cuenta.

La creación y la modificación de cuentas usan el método [save], heredado de [JpaRepository]: para una entidad nueva (identificador [null]), llama a [persist] de [EntityManager] (un [INSERT]); para una entidad ya registrada, llama a [merge]. Veremos que la capa de negocio solo necesita [save] para las creaciones.

11.12. La capa de negocio

La capa de negocio contiene las reglas de negocio de la aplicación: no se permiten citas en el pasado, solo una cita próxima por paciente, nombres de usuario y personas únicos, y la posibilidad de eliminar a un médico o a un cliente. Se apoya en la capa DAO (carpeta [repositories]) para leer y escribir, abre transacciones y no sabe nada de HTML ni del idioma de la interfaz. Más concretamente, esta es la capa [PersonsBusiness] del ejemplo 28.

11.12.1. business/Dates.java

// =========================================================================
// business/Dates.java
// -------------------------------------------------------------------------
// La fecha de hoy. La usan REGLAS DE NEGOCIO (ninguna reserva
// en el pasado, una sola cita PRÓXIMA por paciente): por lo tanto vive
// en la capa de negocio. La capa web la reutiliza.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;

public final class Dates {

    private Dates() {
    }

    // la fecha de hoy, en la zona horaria del servidor
    public static LocalDate today() {
        return LocalDate.now();
    }
}
  • Línea 12: una clase de utilidad que simplemente contiene un método [static], llamado por el nombre de la clase ([Dates.today()]). [final] impide heredar de ella;
  • líneas 14–15: un constructor [private] impide la creación de objetos [Dates], lo cual no tendría sentido;
  • líneas 18–20: la fecha de hoy, en la zona horaria del servidor, en forma de un [LocalDate] (una fecha sin hora, el tipo de [Appointment.day]). Dos objetos [LocalDate] se comparan mediante los siguientes métodos: [day.isBefore(today)], [isAfter], [equals]. La fecha actual se usa para las reglas de negocio, por lo que reside en la capa de negocio; la capa web la reutiliza (por ejemplo, en [ScheduleController], para determinar si un día aún se puede reservar).

11.12.2. business/BusinessException.java

// =========================================================================
// business/BusinessException.java
// -------------------------------------------------------------------------
// La excepción lanzada por la capa de negocio cuando se viola una REGLA DE
// NEGOCIO (login ya utilizado, médico que aún tiene citas, franja
// ya reservada...). No lleva un texto, sino una CLAVE de
// traducción (p. ej. "ERRORS.LOGIN_TAKEN"): es la capa web la que la
// traducirá al francés o al inglés al mostrar la página
// (vea i18n/fr.json, i18n/en.json).
//
// Una BusinessException no es una anomalía: es una respuesta normal
// ("este login ya está en uso"), que se muestra al usuario. Cualquier otra
// excepción es una verdadera anomalía, que lleva a la página de error 500.
//
// RuntimeException: una excepción "no comprobada" (unchecked); los métodos que
// la lanzan no tienen que declararla (throws), y Spring cancela (ROLLBACK) la
// transacción que interrumpe.
// =========================================================================
package rdvmedecins.business;

import java.util.Map;

public class BusinessException extends RuntimeException {

    // clave de traducción del mensaje
    private final String key;

    // posibles parámetros del mensaje ({minutes}...)
    private final Map<String, String> params;

    public BusinessException(String key) {
        this(key, Map.of());
    }

    public BusinessException(String key, Map<String, String> params) {
        super(key);
        this.key = key;
        this.params = params;
    }

    public String getKey() {
        return key;
    }

    public Map<String, String> getParams() {
        return params;
    }
}
  • Línea 23: la excepción que se lanza cuando una regla de negocio rechaza una operación (véase el ejemplo 28). Hereda de [RuntimeException]: es una excepción no comprobada. En [Java], un método que puede lanzar una excepción comprobada debe declararla ([throws ...]), y el llamador debe tratarla; una excepción no comprobada está exenta de este requisito. Otra consecuencia importante: [Spring] revierte ([ROLLBACK]) una transacción interrumpida por una excepción no comprobada (mientras que con [@Transactional], una excepción comprobada permitiría, de forma predeterminada, confirmar la transacción);
  • Líneas 26 y 29: la clave de traducción del mensaje ([ERRORS.LOGIN_TAKEN]) y los parámetros asociados, si los hay. Diferencia con el ejemplo 28: la excepción no lleva texto en francés, sino una clave. Así, la capa de negocio ignora el idioma de la interfaz: es la capa web la que traducirá la clave mediante los diccionarios [i18n/fr.json] y [i18n/en.json] (véase la sección “Diccionarios”). Los campos son [final]: establecidos por el constructor, no cambian;
  • líneas 31–33: el constructor sin parámetros de mensaje. [this(key, Map.of())] llama al otro constructor de la clase con un diccionario vacío: [Map.of()] crea un diccionario de solo lectura. De este modo, la capa web nunca tiene que comprobar [null]. En realidad, las excepciones lanzadas por [BusinessService] usan únicamente este constructor;
  • línea 36: [super(key)] pasa la clave al constructor de la clase padre, que la usa como mensaje de la excepción ([getMessage()]), útil en los registros de errores;
  • líneas 41–47: los accesores.

Una [BusinessException] no es un error: es una respuesta normal (“este nombre de usuario ya está en uso”), que los controladores interceptan para mostrarla al usuario, ya sea en la página o en un mensaje emergente. Cualquier otra excepción es un error real, que da lugar a una página de error 500.

11.12.3. business/Business.java

// =========================================================================
// business/Business.java
// -------------------------------------------------------------------------
// El contrato de la capa de negocio: lecturas, agenda, citas, gestión
// de los médicos y los clientes.
//
// Optional<T>: un resultado que puede estar ausente (un médico que no existe
// ...). El llamador está obligado a manejar este caso: ningún null olvidado.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;
import java.util.List;
import java.util.Optional;

import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;

public interface Business {

    // lecturas
    List<Client> getAllClients();

    List<Doctor> getAllDoctors();

    List<Slot> getAllSlots(int doctorId);

    List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day);

    Optional<Client> getClientById(int id);

    Optional<Doctor> getDoctorById(int id);

    Optional<Appointment> getAppointmentById(int id);

    Optional<Slot> getSlotById(int id);

    Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day);

    // el cliente (paciente) cuya cuenta de usuario es [userId]
    Optional<Client> getClientByUserId(int userId);

    // las citas de un cliente, de hoy o futuras, con franja y médico
    List<Appointment> getClientUpcomingAppointments(int clientId);

    // citas (ADMIN, DOCTOR, USER)
    // lanza una BusinessException si:
    //  - el día es pasado ("ERRORS.PAST_DATE");
    //  - el paciente ya tiene una cita próxima ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    //  - la franja ya está reservada ese día ("ERRORS.SLOT_ALREADY_BOOKED").
    Appointment addAppointment(LocalDate day, Slot slot, Client client);

    void deleteAppointment(Appointment appointment);

    // médicos (ADMIN)
    // crea al médico Y su cuenta de usuario (rol DOCTOR)
    Doctor addDoctor(PersonData data);

    // edita al médico Y su cuenta de usuario
    Doctor editDoctor(int id, PersonData data);

    // elimina al médico, sus franjas Y su cuenta - se rechaza si tiene citas
    void deleteDoctor(int id);

    // clientes
    // (el ADMIN; addClient también se usa para el registro de un paciente,
    // editClient y deleteClient los usa el paciente para su propia cuenta)
    // crea al cliente Y su cuenta de usuario (rol USER)
    Client addClient(PersonData data);

    Client editClient(int id, PersonData data);

    // elimina al cliente, su cuenta Y todas sus citas (pasadas y futuras)
    void deleteClient(int id);
}
  • línea 22: el contrato de la capa de negocio: lo que las demás capas pueden solicitarle, sin especificar cómo se hace (las interfaces se trataron en el ejemplo 06);
  • líneas 25–47: las lecturas. Las que pueden no encontrar nada (líneas 33–44) devuelven un [Optional]: un médico desconocido devuelve un [Optional] vacío, nunca un [null]. Las listas, en cambio, están vacías cuando no hay nada que devolver;
  • líneas 50–56: las citas. El comentario de [addAppointment] enumera los códigos de error posibles: esto forma parte del contrato que los controladores deben conocer;
  • líneas 60–66: gestión de médicos (reservada a ADMIN). Cada médico se crea, se modifica y se elimina junto con su cuenta de usuario;
  • líneas 72–77: gestión de clientes, con la misma lógica. [addClient] se usa también para registrar a un paciente, mientras que [editClient] y [deleteClient] se usan para los pacientes que administran su propia cuenta.

Los métodos de una interfaz son implícitamente [public] y [abstract]: no se definen de forma explícita. Dos beans implementan este contrato: [BusinessService], que se presenta más adelante, y [ApplicationModel] (carpeta [web]), que lo extiende con una caché de las listas de médicos y clientes y delega el resto en [BusinessService] (véase la sección “La capa web: servicios comunes”). Los controladores usan [ApplicationModel].

11.12.4. business/PersonData.java

// =========================================================================
// business/PersonData.java
// -------------------------------------------------------------------------
// Los datos escritos en el formulario de "médico" o de "cliente", tal como
// la capa web los pasa a la capa de negocio.
// =========================================================================
package rdvmedecins.business;

public record PersonData(
        String title, // Mr, Mme, Melle
        String lastName,
        String firstName,
        // creación: opcional (null), por defecto el apellido en minúsculas
        // edición: opcional, el login no cambia si falta
        String login,
        // creación: opcional, por defecto el login
        // edición: opcional, la contraseña no cambia si falta
        String password,
        // edición: la versión del registro en el momento en que se mostró el
        // formulario (bloqueo optimista, vea AbstractEntity.version)
        Integer version) {
}

Los datos de un médico o de un cliente que se va a crear o modificar, tal como los transmite la capa web (véase el ejemplo 28): un record, cuyos componentes se escriben aquí uno por línea para dejar espacio a los comentarios (líneas 9–21). El título, el apellido y el nombre siempre se proporcionan. El nombre de usuario y la contraseña (líneas 15 y 18) son opcionales y se establecen en [null] cuando no se ingresan: al crear, por defecto son el apellido en minúsculas; al modificar, permanecen sin cambios. [version] (línea 21) es la versión del registro leída cuando se muestra el formulario de edición: se usa para el bloqueo optimista. Su tipo es [Integer], no [int], para que pueda ser [null] (al crear, no hay versión).

11.12.5. business/BusinessService.java

Este es el archivo más completo de la aplicación. Lo mostraremos en cinco extractos consecutivos.

11.12.5.1. Los descriptores

// =========================================================================
// business/BusinessService.java
// -------------------------------------------------------------------------
// Implementación de la capa de negocio.
//
// La gestión de los médicos y clientes obedece a tres reglas de negocio:
//
//   1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
//      juntas: se crean, editan y eliminan juntas, en
//      la misma TRANSACCIÓN - o todo tiene éxito, o no se escribe nada;
//   2. el login es único en toda la aplicación, y dos médicos (o
//      dos clientes) no pueden tener el mismo nombre y apellido;
//   3. eliminación:
//      - un MÉDICO que tiene citas no puede eliminarse (sus
//        pacientes perderían su cita sin ser avisados): antes hay que
//        cancelarlas. Sus franjas horarias desaparecen con él;
//      - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y
//        futuras) - ya sea que la eliminación venga del ADMIN o del propio
//        paciente.
//
// Y dos reglas para reservar una cita, sea cual sea el rol de
// quien reserva (ADMIN, DOCTOR o el propio paciente):
//   4. ninguna cita en el pasado;
//   5. un paciente tiene solo UNA cita próxima a la vez.
//
// Médicos y clientes siguen exactamente las mismas reglas: el código común
// se escribe UNA SOLA VEZ (métodos privados genéricos xxxPerson), y se parametriza
// mediante un pequeño "descriptor" que indica con qué tipo de persona se trata.
//
// Las TRANSACCIONES se abren explícitamente, mediante un TransactionTemplate
// (vea el método transaction, al final del archivo), para traducir a
// BusinessException los errores que la base de datos informa en el COMMIT.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.IntToLongFunction;
import java.util.function.Supplier;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import org.springframework.core.NestedExceptionUtils;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.transaction.support.TransactionTemplate;

import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.domain.DoctorDaySlot;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.ClientRepository;
import rdvmedecins.repositories.SlotRepository;
import rdvmedecins.repositories.DoctorRepository;
import rdvmedecins.repositories.PersonRepository;
import rdvmedecins.repositories.AppointmentRepository;
import rdvmedecins.repositories.UserRepository;

// @Service: un bean de la capa de negocio; una única instancia (singleton)
// para toda la aplicación
@Service
public class BusinessService implements Business {

    // todo lo que distingue a un médico de un cliente para las reglas de negocio
    private record Descriptor<T extends Person>(
            PersonRepository<T> dao,
            Supplier<T> factory, // Doctor::new o Client::new
            Role role, // DOCTOR o USER
            String notFoundKey, // mensaje si la persona no existe
            String alreadyExistsKey, // mensaje si ya existen el mismo nombre y apellido
            // opcional (null): si está presente, la eliminación se RECHAZA mientras
            // la persona tenga citas (countAppointments > 0), con el mensaje hasAppointmentsKey
            IntToLongFunction countAppointments,
            String hasAppointmentsKey,
            // opcional: lo que debe eliminarse ANTES de la persona (las filas
            // que la referencian mediante una clave externa)
            IntConsumer beforeDelete) {
    }

    private final DoctorRepository doctorRepository;
    private final ClientRepository clientRepository;
    private final SlotRepository slotRepository;
    private final AppointmentRepository appointmentRepository;
    private final UserRepository userRepository;
    private final PasswordEncoder hasher;
    private final TransactionTemplate transactions;
    private final Descriptor<Doctor> doctorDescriptor;
    private final Descriptor<Client> clientDescriptor;

    // todas las dependencias las proporciona la inyección de dependencias de
    // Spring. TransactionTemplate: un bean proporcionado por Spring Boot, que ejecuta
    // código en una transacción.
    public BusinessService(DoctorRepository doctorRepository, ClientRepository clientRepository,
            SlotRepository slotRepository, AppointmentRepository appointmentRepository, UserRepository userRepository,
            PasswordEncoder hasher, TransactionTemplate transactions) {
        this.doctorRepository = doctorRepository;
        this.clientRepository = clientRepository;
        this.slotRepository = slotRepository;
        this.appointmentRepository = appointmentRepository;
        this.userRepository = userRepository;
        this.hasher = hasher;
        this.transactions = transactions;

        doctorDescriptor = new Descriptor<>(
                doctorRepository,
                Doctor::new,
                Role.DOCTOR,
                "ERRORS.DOCTOR_NOT_FOUND",
                "ERRORS.DOCTOR_ALREADY_EXISTS",
                appointmentRepository::countByDoctor,
                "ERRORS.DOCTOR_HAS_APPOINTMENTS",
                // un médico sin citas aún puede tener franjas horarias:
                // ya no tienen sentido sin él, las eliminamos junto con él (de lo contrario
                // la clave externa slots.doctor_id impediría la eliminación)
                slotRepository::deleteByDoctor);

        clientDescriptor = new Descriptor<>(
                clientRepository,
                Client::new,
                Role.USER,
                "ERRORS.PATIENT_NOT_FOUND",
                "ERRORS.PATIENT_ALREADY_EXISTS",
                // sin countAppointments: la eliminación de un cliente nunca se rechaza;
                // sus citas (pasadas y futuras) se eliminan junto con él (de lo contrario
                // la clave externa appointments.client_id impediría la eliminación)
                null,
                null,
                appointmentRepository::deleteByClient);
    }
  • líneas 6–24: el comentario de encabezado resume las cinco reglas de negocio que aplica la clase;
  • líneas 50–52: las excepciones de [Spring] que indican un error de base de datos y una utilidad para examinarlas (véase el último extracto);
  • línea 53: la interfaz [PasswordEncoder] de [Spring Security], que calcula los hashes [bcrypt] (véase el ejemplo 25). El bean correspondiente, un [BCryptPasswordEncoder] con un costo de 10 (el mismo que el de las contraseñas del script SQL), se declara en [config/SecurityConfig.java] (véase la sección “Autenticación”);
  • línea 55: [TransactionTemplate], que ejecuta código dentro de una transacción (véase el último extracto);
  • líneas 75–76: [@Service] convierte la clase en un bean de la capa de negocio. Como todos los beans predeterminados, es un singleton: una única instancia para toda la aplicación, compartida por todas las solicitudes. Esto no es un problema, ya que el objeto no almacena ningún dato específico de una solicitud: sus campos son dependencias, establecidas de una vez por todas. El nombre del bean es el de la clase, con la primera letra en minúscula: [businessService], el nombre al que hace referencia [ApplicationModel] en su [@Qualifier]. La clase implementa la interfaz [Business]: debe proporcionar todos sus métodos;
  • líneas 79–92: todo lo que distingue a un médico de un cliente en cuanto a reglas de negocio: su repositorio, cómo crear un objeto vacío, el rol de su cuenta ([DOCTOR] o [USER]), sus mensajes de error y lo que ocurre al eliminarlo. Como los médicos y los clientes siguen las mismas reglas, el código de estas reglas se escribe una sola vez, en métodos genéricos que reciben un descriptor. El descriptor es un record genérico, declarado dentro de la clase (y [private]: nadie más lo usa);
  • Líneas 81, 87 y 91: tres interfaces funcionales del paquete [java.util.function]—interfaces de un solo método que describen el tipo de una función. [Supplier<T>] es una función sin parámetros que devuelve un [T] (método [get()]); [IntToLongFunction], una función que recibe un [int] y devuelve un [long] (método [applyAsLong]); [IntConsumer], una función que recibe un [int] y no devuelve nada (método [accept]). Un valor de este tipo puede escribirse como una lambda ([x -> ...]) o una referencia a método ([Class::method]);
  • líneas 94–102: los campos de la clase: los cinco repositorios, el calculador de hashes, [TransactionTemplate] y los dos descriptores. [final] impide que se modifiquen después del constructor;
  • líneas 107–109: todas las dependencias se proporcionan mediante inyección de dependencias por [Spring]: la clase tiene un solo constructor, que [Spring] llama con los beans de los tipos solicitados. Los repositorios son las implementaciones escritas por [Spring Data JPA]; [TransactionTemplate] es creado por [Spring Boot];
  • Líneas 118–129: el descriptor de médicos. [new Descriptor<>(...)]: el símbolo diamante [<>] permite que el compilador infiera el parámetro de tipo ([Doctor]) de la variable que recibe el objeto. Los valores se dan en el orden de los componentes del record;
  • línea 120: [Doctor::new] es una referencia a constructor: una función sin parámetros que devuelve un [new Doctor()]. Tiene el tipo esperado [Supplier<Doctor>]. No se llama aquí; se llamará cada vez que se cree un médico;
  • línea 124: [appointmentRepository::countByDoctor] es una referencia a método: el método [countByDoctor] del objeto [appointmentRepository], que recibe un [int] y devuelve un [long]; es decir, un valor de tipo [IntToLongFunction]. Se rechazará la eliminación de un médico mientras tenga citas;
  • línea 129: de manera similar, [slotRepository::deleteByDoctor] (un [int], sin resultado) es un [IntConsumer]: las franjas horarias de un médico se eliminarán antes de eliminar al médico;
  • Líneas 131–142: el descriptor de clientes. [Java] no tiene parámetros con nombre ni opcionales: los dos componentes innecesarios ([countAppointments] y [hasAppointmentsKey]) se asignan a [null] (líneas 140–141). Por lo tanto, la eliminación de un cliente nunca se rechaza, y sus citas (pasadas y futuras) se eliminan antes que el propio cliente; de lo contrario, la clave externa [appointments.client_id] impediría la eliminación.

11.12.5.2. Operaciones de lectura y el calendario

    // =======================================================================
    // lecturas, fuera de cualquier transacción (cada consulta DAO se ejecuta sola,
    // con un EntityManager abierto durante la duración de la llamada)
    // =======================================================================

    @Override
    public List<Client> getAllClients() {
        return clientRepository.findAllByOrderByLastNameAscFirstNameAsc();
    }

    @Override
    public List<Doctor> getAllDoctors() {
        return doctorRepository.findAllByOrderByLastNameAscFirstNameAsc();
    }

    @Override
    public List<Slot> getAllSlots(int doctorId) {
        return slotRepository.findByDoctorIdOrderByStartHourAscStartMinuteAsc(doctorId);
    }

    @Override
    public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
        return appointmentRepository.doctorDayAppointments(doctorId, day);
    }

    @Override
    public Optional<Client> getClientById(int id) {
        return clientRepository.findWithUserById(id);
    }

    @Override
    public Optional<Doctor> getDoctorById(int id) {
        return doctorRepository.findWithUserById(id);
    }

    @Override
    public Optional<Appointment> getAppointmentById(int id) {
        return appointmentRepository.read(id);
    }

    @Override
    public Optional<Slot> getSlotById(int id) {
        return slotRepository.findWithDoctorById(id);
    }

    @Override
    public Optional<Client> getClientByUserId(int userId) {
        return clientRepository.findByUserId(userId);
    }

    @Override
    public List<Appointment> getClientUpcomingAppointments(int clientId) {
        return appointmentRepository.clientUpcomingAppointments(clientId, Dates.today());
    }

    // mismo algoritmo que el servidor JSON (y que el proyecto Spring original)
    @Override
    public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
        Optional<Doctor> doctor = getDoctorById(doctorId);
        if (doctor.isEmpty()) {
            return Optional.empty();
        }
        List<Slot> timeSlots = getAllSlots(doctorId);
        // n.º de franja -> cita reservada en esta franja
        Map<Integer, Appointment> bookings = getDoctorDayAppointments(doctorId, day).stream()
                .collect(Collectors.toMap(Appointment::getSlotId, Function.identity()));
        List<DoctorDaySlot> doctorDaySlots = timeSlots.stream()
                .map(slot -> new DoctorDaySlot(slot, bookings.get(slot.getId())))
                .toList();
        return Optional.of(new DoctorDaySchedule(doctor.get(), day, doctorDaySlots));
    }
  • Líneas 6–54: las operaciones de lectura simplemente delegan en la capa DAO, traduciendo los nombres de los métodos de los repositorios (a menudo impuestos por [Spring Data JPA]) a nombres de negocio. [@Override] indica un método que implementa un método de la interfaz: el compilador verifica que realmente exista en [Business]. Estos métodos no inician una transacción: cada consulta se ejecuta de forma independiente, con un [EntityManager] creado durante el tiempo que dura la llamada (vea la sección “JPA, Hibernate y Spring Data”). Cada uno carga las relaciones que requieren las páginas (la cuenta de una persona, el médico de una franja horaria, el cliente y la franja horaria de una cita): las entidades devueltas están desconectadas (detached), y los controladores y las vistas pueden leer estas relaciones sin riesgo;
  • línea 53: las próximas citas de un paciente: la capa de negocio proporciona la fecha actual al repositorio;
  • líneas 58–71: cálculo de la agenda de un médico para un día determinado. Un médico desconocido devuelve un [Optional] vacío ([Optional.empty()]); de lo contrario, se recuperan las franjas horarias del médico y las citas del día. La agenda realiza tres lecturas sucesivas, independientes entre sí: esto es aceptable para una página que se muestra, que el usuario volverá a cargar si es necesario;
  • líneas 65–66: las citas del día se almacenan en un diccionario ([Map]) cuya clave es el identificador de su franja horaria. [stream()] convierte la lista en un flujo: una secuencia de elementos que se procesan mediante operaciones encadenadas. [collect(Collectors.toMap(...))] almacena los elementos del flujo en un diccionario: la clave de cada cita se calcula mediante [Appointment::getSlotId] (una referencia a método, aplicada a cada cita), y el valor mediante [Function.identity()], la función que devuelve su argumento: la propia cita. [toMap] fallaría si dos claves fueran iguales, pero esto no puede ocurrir: la restricción [unq1_appointments] impide que se programen dos citas en la misma franja horaria el mismo día. El diccionario evita tener que recorrer toda la lista de citas para cada franja horaria;
  • líneas 67–69: cada franja horaria se asocia con su cita, o con [null]: [get] devuelve [null] cuando la clave está ausente, es decir, cuando la franja horaria está libre. [map] transforma cada elemento del flujo mediante la lambda [slot -> new DoctorDaySlot(...)]: una función anónima cuyo parámetro [slot] se escribe a la izquierda de la flecha y el resultado a la derecha. [toList()] recopila el resultado en una lista de solo lectura. Se conserva el orden cronológico de las franjas horarias, tal como lo especifica la consulta;
  • línea 70: la agenda, en un [Optional] lleno ([Optional.of]); [doctor.get()] extrae al médico de su [Optional], que aquí sabemos que no está vacío. El resultado es un objeto [DoctorDaySchedule] del [domain] record, que la vista de calendario mostrará.

11.12.5.3. Programación de una cita

    // =======================================================================
    // citas
    // =======================================================================

    // -----------------------------------------------------------------------
    // reserva de una cita, en una transacción:
    //   1. ninguna cita en el pasado;
    //   2. BLOQUEAMOS la fila del paciente (SELECT ... FOR UPDATE): si el
    //      mismo paciente reserva dos franjas en el mismo instante (dos pestañas,
    //      doble clic...), la segunda transacción espera el fin de la
    //      primera - y entonces ve la cita que esta acaba de crear;
    //   3. una sola cita próxima por paciente;
    //   4. por último la inserción. Si la franja acaba de ser tomada por OTRO
    //      paciente, es la restricción SQL unq1_appointments (day, slot_id) la que
    //      rechaza la inserción - traducida a BusinessException por [transaction].
    // -----------------------------------------------------------------------
    @Override
    public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
        return transaction(() -> {
            LocalDate today = Dates.today();
            if (day.isBefore(today)) {
                throw new BusinessException("ERRORS.PAST_DATE");
            }
            int patientId = clientRepository.lock(client.getId())
                    .orElseThrow(() -> new BusinessException("ERRORS.PATIENT_NOT_FOUND"));
            if (appointmentRepository.countByClientIdAndDayGreaterThanEqual(patientId, today) > 0) {
                throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
            }
            // getReferenceById: una "referencia" a la franja y al paciente,
            // sin volver a leerlos de la base de datos - conocer su id basta para
            // escribir las claves externas
            Slot slotRef = slotRepository.getReferenceById(slot.getId());
            Client patientRef = clientRepository.getReferenceById(patientId);
            return appointmentRepository.save(new Appointment(day, slotRef, patientRef));
        });
    }

    @Override
    public void deleteAppointment(Appointment appointment) {
        transaction(() -> {
            appointmentRepository.remove(appointment.getId());
            return null;
        });
    }
  • líneas 19 y 35: toda la reserva se realiza dentro de una transacción: el método pasa a [transaction] (vea el último fragmento) una lambda sin parámetros, [() -> { ... }], que realiza la tarea y devuelve la cita creada. Una lambda puede usar los parámetros del método que la contiene ([day], [slot], [client]), siempre que nunca se modifiquen;
  • Líneas 21–23: no se admiten citas en el pasado. Esta regla se aplica aquí independientemente del rol de la persona que realiza la reserva (ADMIN, DOCTOR o el paciente), incluso si la capa web ya ha ocultado los botones “Reservar” para las fechas pasadas: una solicitud puede crearse manualmente;
  • líneas 24–25: la fila del paciente está bloqueada mediante [SELECT ... FOR UPDATE] (vea [ClientRepository]). Se trata de un bloqueo pesimista: se adquiere antes de que comience cualquier trabajo, suponiendo un posible conflicto, y permanece hasta el final de la transacción. Sin él, dos reservas del mismo paciente enviadas al mismo tiempo (dos pestañas, un doble clic) podrían pasar ambas la siguiente verificación antes de que cualquiera haya escrito su cita en el disco. Con el bloqueo, la segunda transacción espera a que termine la primera y luego ve la cita que esta creó. Un paciente que no se encuentra (eliminado mientras tanto) se rechaza: [orElseThrow] devuelve el contenido del [Optional], o lanza la excepción generada por la lambda si está vacío;
  • líneas 26–28: solo una próxima cita por paciente;
  • Líneas 32–33: [getReferenceById] devuelve una referencia a una entidad (un proxy) que contiene solo el identificador, sin leer la fila de la base de datos. Para escribir las claves externas de la fila [appointments], solo se necesitan los identificadores de la franja horaria y del paciente; no es necesario leerlos de nuevo. No usamos directamente los objetos [slot] y [client] recibidos como parámetros: provienen de la capa web, están desconectados y no forman parte del contexto de persistencia de esta transacción;
  • Línea 34: la inserción. [save] guarda la nueva cita (clave [IDENTITY]: [INSERT] se envía inmediatamente) y la devuelve. Si otro paciente acaba de reservar la misma franja horaria, el bloqueo no lo impidió (el bloqueo se aplica al registro del paciente): es la restricción de unicidad de la base de datos [unq1_appointments (day, slot_id)] la que rechaza la inserción, y [transaction] traduce el error en una [BusinessException] con la clave [ERRORS.SLOT_ALREADY_BOOKED];
  • Líneas 39–44: cancelación de una cita, sin reglas específicas. El método [remove] del repositorio es una consulta de tipo [@Modifying]: requiere una transacción que acepte escrituras, de ahí la llamada a [transaction]. La lambda debe devolver un valor: devuelve [null], que nadie usa.

Estos son los comandos SQL enviados durante una reserva, tal como se registran en la consola. El primero lee la franja horaria y su médico ([getSlotById], llamado por el controlador antes de [addAppointment]); los tres siguientes son los de la transacción: el bloqueo, el conteo y la inserción. Gracias a [getReferenceById], ni la franja horaria ni el cliente se leen de nuevo:

1
2
3
4
Hibernate: select s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version from slots s1_0 left join doctors d1_0 on d1_0.id=s1_0.doctor_id where s1_0.id=?
Hibernate: select id from clients where id = ? for update
Hibernate: select count(a1_0.id) from appointments a1_0 where a1_0.client_id=? and a1_0.day>=?
Hibernate: insert into appointments (client_id,day,slot_id,version) values (?,?,?,?)

[INSERT] también escribe en la columna [version]: [Hibernate] asigna la versión 0 a toda entidad nueva.

11.12.5.4. Gestión de médicos y clientes

    // =======================================================================
    // médicos y clientes - los métodos públicos delegan en los métodos
    // privados comunes, con el descriptor adecuado
    // =======================================================================

    @Override
    public Doctor addDoctor(PersonData data) {
        return addPerson(doctorDescriptor, data);
    }

    @Override
    public Doctor editDoctor(int id, PersonData data) {
        return editPerson(doctorDescriptor, id, data);
    }

    @Override
    public void deleteDoctor(int id) {
        deletePerson(doctorDescriptor, id);
    }

    @Override
    public Client addClient(PersonData data) {
        return addPerson(clientDescriptor, data);
    }

    @Override
    public Client editClient(int id, PersonData data) {
        return editPerson(clientDescriptor, id, data);
    }

    // el cliente, su cuenta Y todas sus citas (el ADMIN, o el propio paciente
    // desde "Administrar mi cuenta": mismo método, misma regla)
    @Override
    public void deleteClient(int id) {
        deletePerson(clientDescriptor, id);
    }

    // -----------------------------------------------------------------------
    // creación: primero la cuenta de usuario (la persona la referencia),
    // luego la persona - todo en UNA transacción.
    // -----------------------------------------------------------------------
    private <T extends Person> T addPerson(Descriptor<T> d, PersonData data) {
        String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
        String firstName = data.firstName().trim();
        // las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
        // contraseña = login - a menos que el ADMIN haya escrito otros
        String login = (empty(data.login()) ? lastName : data.login()).toLowerCase(Locale.ROOT);
        String password = empty(data.password()) ? login : data.password();

        return transaction(() -> {
            checkPersonUnique(d, firstName, lastName, null);
            checkLoginFree(login);

            User user = new User();
            user.setLogin(login);
            user.setPassword(hasher.encode(password));
            user.setName(firstName + " " + lastName);
            user.setRole(d.role());
            userRepository.save(user);

            T person = d.factory().get();
            person.setTitle(data.title());
            person.setLastName(lastName);
            person.setFirstName(firstName);
            person.setUser(user);
            return d.dao().save(person);
        });
    }

    // -----------------------------------------------------------------------
    // edición: la persona Y su cuenta (el nombre mostrado "firstName LASTNAME"
    // debe seguirla; el login y la contraseña cambian solo si se han
    // escrito).
    // -----------------------------------------------------------------------
    private <T extends Person> T editPerson(Descriptor<T> d, int id, PersonData data) {
        return transaction(() -> {
            T person = d.dao().findWithUserById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));

            // bloqueo optimista: si la versión en la base de datos ya no es la del
            // formulario, alguien ha editado este registro entretanto - rechazamos
            // en lugar de sobrescribir silenciosamente sus cambios.
            // (Si la edición concurrente ocurre DESPUÉS de esta lectura, es
            // la cláusula "WHERE version = ..." del UPDATE la que la detecta.)
            if (data.version() != null && !data.version().equals(person.getVersion())) {
                throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
            }

            String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
            String firstName = data.firstName().trim();
            checkPersonUnique(d, firstName, lastName, id);

            // simplemente modificamos los objetos: la entidad leída en la
            // transacción está "administrada" por JPA, que enviará ella misma los UPDATE
            // necesarios en el COMMIT (no hace falta llamar a save)
            person.setTitle(data.title());
            person.setLastName(lastName);
            person.setFirstName(firstName);

            User user = person.getUser();
            user.setName(firstName + " " + lastName);
            if (!empty(data.login()) && !data.login().toLowerCase(Locale.ROOT).equals(user.getLogin())) {
                String login = data.login().toLowerCase(Locale.ROOT);
                checkLoginFree(login);
                user.setLogin(login);
            }
            if (!empty(data.password())) {
                user.setPassword(hasher.encode(data.password()));
            }
            return person;
        });
    }

    // -----------------------------------------------------------------------
    // eliminación, en UNA transacción, en el orden impuesto por las claves
    // externas:
    //   1. posible rechazo si quedan citas (médico);
    //   2. lo que referencia a la persona (franjas de un médico, citas
    //      de un cliente);
    //   3. la persona (referencia a su cuenta);
    //   4. su cuenta.
    // -----------------------------------------------------------------------
    private <T extends Person> void deletePerson(Descriptor<T> d, int id) {
        transaction(() -> {
            T person = d.dao().findById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));
            if (d.countAppointments() != null && d.countAppointments().applyAsLong(id) > 0) {
                throw new BusinessException(d.hasAppointmentsKey());
            }
            if (d.beforeDelete() != null) {
                d.beforeDelete().accept(id);
            }
            d.dao().remove(id);
            userRepository.remove(person.getUserId());
            return null; // [transaction] espera un resultado: aquí no necesitamos ninguno
        });
    }

    // rechaza nombres y apellidos ya usados por OTRA persona del mismo tipo
    // (currentId: la persona que se edita, que evidentemente tiene
    // derecho a conservar su propio nombre y apellido; null para una creación)
    private <T extends Person> void checkPersonUnique(Descriptor<T> d, String firstName, String lastName,
            Integer currentId) {
        Optional<T> namesake = d.dao().findFirstByFirstNameAndLastName(firstName, lastName);
        if (namesake.isPresent() && !Objects.equals(namesake.get().getId(), currentId)) {
            throw new BusinessException(d.alreadyExistsKey());
        }
    }

    private void checkLoginFree(String login) {
        if (userRepository.findByLogin(login).isPresent()) {
            throw new BusinessException("ERRORS.LOGIN_TAKEN");
        }
    }

    private static boolean empty(String text) {
        return text == null || text.isEmpty();
    }
  • líneas 6–36: los seis métodos públicos delegan en los tres métodos genéricos privados, usando el descriptor correcto. El compilador infiere [T] a partir del descriptor: [Doctor] para [doctorDescriptor], [Client] para [clientDescriptor];
  • línea 42: [<T extends Person>], escrito antes del tipo de retorno, hace de [addPerson] un método genérico: tiene su propio parámetro de tipo [T], que debe ser [Person] o una subclase;
  • Líneas 43–48: preparación de datos, fuera de la transacción. [trim()] elimina los espacios iniciales y finales de la cadena; el nombre se capitaliza. [Locale.ROOT] exige una conversión independiente del idioma del servidor (en turco, por ejemplo, la versión en minúscula de [I] no es [i]). De forma predeterminada, el nombre de usuario es igual al nombre, y siempre está en minúsculas; de forma predeterminada, la contraseña es igual al nombre de usuario: estas son las reglas de cuentas del script SQL. [a ? b : c] es el operador condicional: [b] si [a] es verdadero, [c] en caso contrario;
  • líneas 51–52: en la transacción, las dos reglas de unicidad: sin nombres duplicados, login libre. Se verifican antes de escribir en la base de datos para mostrar un mensaje claro (vea el Ejemplo 28);
  • líneas 54–59: la cuenta de usuario se crea primero, ya que la persona la referencia (clave externa). La contraseña nunca se almacena en texto plano: [hasher.encode] calcula su hash, [bcrypt]. [save] envía inmediatamente [INSERT] (clave [IDENTITY]): después de esta llamada, [user] tiene un identificador y ahora es una entidad administrada (managed);
  • Líneas 61–66: luego la persona. [d.factory().get()] hace referencia a la fábrica del descriptor: [new Doctor()] o [new Client()]. [setUser(user)] vincula a la persona con su cuenta: para el [INSERT] de la persona, [Hibernate] escribirá el ID de la cuenta en la columna [user]. Si esta segunda operación de escritura falla, la transacción también revierte la primera: una cuenta nunca puede existir sin una persona;
  • líneas 75–111: modificación de la persona y su cuenta en una sola transacción;
  • línea 77: la persona y su cuenta ([findWithUserById]), o una [BusinessException] con la clave del descriptor si no existe;
  • líneas 84–86: el bloqueo optimista (vea el Ejemplo 28): el formulario ha transportado la versión del registro leído al mostrarse; si la versión en la base de datos es diferente, alguien ha modificado el registro mientras tanto, y el sistema rechaza la actualización en lugar de sobrescribir silenciosamente su trabajo. A diferencia del bloqueo pesimista usado para las reservas, no se bloquea nada: se supone que los conflictos son raros, y simplemente se detectan. Las versiones son [Integer], que son objetos: se comparan con [equals], no con [!=], que compararía las referencias de los objetos. Si la modificación concurrente ocurre después de esta lectura, es la condición [WHERE version = ...] del [UPDATE] la que la detectará (vea el último fragmento);
  • líneas 88–90: el nuevo nombre y apellido, y la verificación de homónimos. Se transmite el identificador de la persona: evidentemente la persona tiene derecho a conservar su propio nombre y apellido;
  • líneas 95–97: el objeto leído simplemente se modifica. Leído dentro de la transacción, está administrado por [EntityManager], que enviará por sí mismo el [UPDATE] en el momento del [COMMIT], comparando el objeto con el estado leído (vea la sección “JPA, Hibernate y Spring Data”): no hay ningún [save] que llamar. El [UPDATE] incrementará la versión y verificará la anterior;
  • líneas 99–108: la cuenta sigue a la persona. Se cargó junto con la persona ([@EntityGraph]) y también está administrada: se recalcula su nombre para mostrar; su login cambia solo si se ingresó y difiere del actual (en ese caso debe estar disponible); su contraseña cambia solo si se ingresó; y también se le aplica el hash;
  • línea 109: se devuelve la persona modificada; después del [COMMIT], queda desconectada, pero su cuenta, que se ha cargado, sigue siendo legible por el controlador;
  • líneas 122–135: eliminación, dentro de una transacción, en el orden dictado por las claves externas;
  • línea 124: [findById] es suficiente: no se necesita la cuenta, solo su identificador, que proporciona el campo [userId] sin cargar la cuenta;
  • líneas 125–127: posible rechazo: no se puede eliminar un médico con citas programadas (sus pacientes perderían sus citas sin ser notificados). [d.countAppointments().applyAsLong(id)] llama a la función indicada en el descriptor, es decir, [appointmentRepository.countByDoctor(id)];
  • líneas 128–130: eliminación de las referencias a la persona: las franjas horarias de un médico, las citas de un cliente;
  • líneas 131–132: la persona, seguida de su cuenta, a la que la persona hacía referencia;
  • línea 133: [transaction] espera una función que devuelva un resultado: [null] se devuelve, y nadie lo usará;
  • líneas 140–146: se rechaza un homónimo, a menos que se refiera a la persona que se está editando ([currentId], [null] para una creación nueva). [Objects.equals(a, b)] compara dos objetos y acepta [null]: [namesake.get().getId().equals(null)] también funcionaría, pero [Objects.equals] evita tener que determinar cuál de los dos podría ser [null];
  • líneas 148–152: se rechaza un nombre de usuario ya utilizado, ya sea por un médico, un cliente o el administrador;
  • líneas 154–156: una cadena ausente ([null]) o vacía: así se maneja un campo opcional que no se ha ingresado.

Observe que solo las operaciones de creación llaman a [save]. Una actualización simplemente modifica entidades existentes, y una eliminación se realiza mediante consultas [delete]: esta es la forma estándar de trabajar con [JPA].

11.12.5.5. Transacciones y restricciones de unicidad

    // -----------------------------------------------------------------------
    // ejecuta [work] en una transacción:
    //   transactions.execute(...) -> START TRANSACTION, luego el trabajo, luego
    //   COMMIT si todo salió bien; si se lanza una excepción
    //   (BusinessException incluida), ROLLBACK: no se escribe nada.
    //
    // Las verificaciones de "login libre" y de "nombre + apellido únicos" se hacen ANTES de
    // la escritura, para dar un mensaje claro. Pero dos ADMIN podrían
    // guardar el mismo login (o el mismo médico) en el mismo instante: en este
    // caso poco frecuente, es una restricción SQL de unicidad la que rechaza la segunda
    // escritura - en el momento en que Hibernate envía las sentencias SQL, a menudo en el
    // COMMIT, por lo tanto DESPUÉS del fin del trabajo. Por eso interceptamos las
    // excepciones aquí, ALREDEDOR de la transacción, para traducirlas a la misma
    // BusinessException.
    // -----------------------------------------------------------------------
    private <R> R transaction(Supplier<R> work) {
        try {
            return transactions.execute(status -> work.get());
        } catch (BusinessException e) {
            throw e;
        } catch (RuntimeException e) {
            BusinessException businessError = translateDatabaseError(e);
            if (businessError != null) {
                throw businessError;
            }
            throw e; // una anomalía real: la dejamos propagar
        }
    }

    // -----------------------------------------------------------------------
    // Errores de la base de datos -> BusinessException
    //
    // Spring traduce las excepciones de Hibernate y del controlador JDBC a una
    // jerarquía de excepciones independiente de la base de datos (DataAccessException):
    // - OptimisticLockingFailureException: el UPDATE "WHERE id = ... AND
    //   version = ..." no modificó ninguna fila (bloqueo optimista);
    // - DataIntegrityViolationException: una restricción de la base de datos rechazó
    //   la escritura. Para una restricción UNIQUE, el mensaje de error de MySQL
    //   (la causa "más específica" de la excepción) cita el NOMBRE de la restricción:
    //     Duplicate entry 'marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
    //   (MySQL 8 antepone el nombre de la tabla, MariaDB no). Por eso
    //   el script SQL NOMBRA todas sus restricciones.
    // Cualquier otro error es una anomalía real: devolvemos null (sin traducir).
    // -----------------------------------------------------------------------
    private static final Map<String, String> CONSTRAINT_MESSAGES = Map.of(
            "unq_users_login", "ERRORS.LOGIN_TAKEN",
            "unq_doctors_first_name_last_name", "ERRORS.DOCTOR_ALREADY_EXISTS",
            "unq_clients_first_name_last_name", "ERRORS.PATIENT_ALREADY_EXISTS",
            "unq1_appointments", "ERRORS.SLOT_ALREADY_BOOKED");

    private static final Pattern CONSTRAINT = Pattern.compile("for key '(?:[^'.]*\\.)?([^']+)'");

    private static BusinessException translateDatabaseError(RuntimeException e) {
        if (e instanceof OptimisticLockingFailureException) {
            return new BusinessException("ERRORS.CONCURRENT_UPDATE");
        }
        if (e instanceof DataIntegrityViolationException) {
            String message = String.valueOf(NestedExceptionUtils.getMostSpecificCause(e).getMessage());
            Matcher match = CONSTRAINT.matcher(message);
            if (match.find() && CONSTRAINT_MESSAGES.containsKey(match.group(1))) {
                return new BusinessException(CONSTRAINT_MESSAGES.get(match.group(1)));
            }
        }
        return null;
    }
}
  • Línea 16: todas las escrituras pasan por este método genérico: [R] es el tipo del resultado del proceso ([Appointment], [Doctor], [Client], u [Object] cuando la lambda devuelve [null]), y [Supplier<R>] es el tipo de una función sin parámetros que devuelve un [R];
  • Línea 18: [transactions.execute(...)] abre una transacción ([START TRANSACTION]), ejecuta la lambda que se le pasa y luego confirma la transacción ([COMMIT]) y devuelve el resultado de la lambda. Si la lambda lanza una excepción no verificada (unchecked), incluida [BusinessException], la transacción se revierte ([ROLLBACK]) y la excepción se vuelve a lanzar. La función lambda recibe el estado de la transacción como parámetro ([status]), lo que le permitiría solicitar una reversión sin lanzar una excepción; sin embargo, no lo utiliza: simplemente llama a [work.get()];
  • líneas 19–20: una [BusinessException] (una regla de negocio rechazada) se devuelve sin cambios al controlador. Este bloque debe preceder al siguiente: [BusinessException] es a su vez una [RuntimeException], y [Java] prueba los bloques [catch] en orden;
  • líneas 21–26: cualquier otra excepción es manejada por [translateDatabaseError]: si es un error conocido de la base de datos, se lanza en su lugar la [BusinessException] correspondiente; de lo contrario, es una verdadera anomalía, que se vuelve a lanzar tal cual y generará una página de error 500;
  • Líneas 45–49: para cada restricción de unicidad con nombre en el script SQL, su clave de traducción. Por eso el script SQL nombra todas sus restricciones. [Map.of(k1, v1, k2, v2...)] crea un diccionario de solo lectura; [static final] lo convierte en una constante de clase, creada una sola vez;
  • línea 51: una expresión regular, compilada una vez por todas mediante [Pattern.compile]. Extrae el nombre de la restricción del mensaje de error de la base de datos (vea más abajo);
  • líneas 53–65: la traducción de un error de la base de datos en una [BusinessException], o en [null] si el error no se reconoce;
  • líneas 54–56: [UPDATE ... WHERE id = ... AND version = ...] no modificó ninguna fila: alguien modificó el registro entre la lectura y el guardado (bloqueo optimista). [instanceof] verifica el tipo real de un objeto. La excepción recibida es una [ObjectOptimisticLockingFailureException], hija de [OptimisticLockingFailureException];
  • líneas 57–63: una restricción de la base de datos rechazó la escritura;
  • línea 58: la excepción de [Spring] envuelve la excepción de [Hibernate], que a su vez envuelve la excepción del controlador (driver) [MySQL]: cada excepción conserva la anterior como su causa ([getCause()]). [NestedExceptionUtils.getMostSpecificCause(e)] remonta hasta la causa raíz, la del controlador, cuyo mensaje es el de [MySQL]. [String.valueOf] maneja un mensaje [null] (en ese caso devuelve la cadena ["null"]);
  • líneas 59–61: el nombre de la restricción se busca en este mensaje y se traduce si aparece en el diccionario. [find()] busca la expresión regular en el mensaje; [group(1)] devuelve lo que capturó el primer grupo entre paréntesis. Cualquier otro error, incluida una violación de una restricción que no se encuentra en el diccionario, se devuelve sin traducir: se trata de una verdadera anomalía.

El mensaje de error de una restricción de unicidad violada especifica el nombre de la restricción. Este es el que produce [MariaDB] cuando se ingresan dos veces el mismo nombre y apellido (la intercalación no distingue entre mayúsculas y minúsculas: [marie pelissier] es un duplicado de [Marie PELISSIER]):

ERROR 1062 (23000) at line 1: Duplicate entry 'marie-pelissier' for key 'unq_doctors_first_name_last_name'

[MySQL] 8 escribe [for key 'doctors.unq_doctors_first_name_last_name'], con el nombre de la tabla como prefijo. La expresión regular [for key '(?:[^'.]*\.)?([^']+)'] acepta ambas formas: [(?:[^'.]*\.)?] omite un prefijo opcional que termina con un punto (un grupo [(?:...)] que no captura nada), y el grupo [([^']+)] captura el nombre hasta el apóstrofo. En una cadena [Java], el punto se escribe como [\\.]: la barra invertida se duplica porque es en sí misma un carácter de escape dentro de una cadena [Java].

Queda por explicar por qué la aplicación usa [TransactionTemplate] en lugar de la anotación [@Transactional] del Ejemplo 28. Hay dos razones:

  • un error en la base de datos no siempre se manifiesta en el trabajo mismo. El [INSERT] de una entidad nueva se envía inmediatamente (clave [IDENTITY]): una restricción de unicidad violada por una creación lanza una excepción durante [save], dentro de la lambda. Sin embargo, el [UPDATE] de una entidad modificada no se envía hasta el [COMMIT] (vea [editPerson]): solo entonces la base de datos informa de un login ya utilizado o de una versión obsoleta. Con [@Transactional], el [COMMIT] se produce después de que el método retorna, dentro del código de [Spring] que lo envuelve: el método no puede interceptar los errores que provoca. El Ejemplo 28 eludió este problema llamando a [saveAndFlush], que fuerza el envío inmediato de los comandos SQL. Con [transactions.execute(...)], [COMMIT] se ejecuta dentro del método [transaction]: su [try] maneja todos los errores, ya ocurran durante el procesamiento o durante [COMMIT];
  • [@Transactional] funciona mediante un proxy: [Spring] envuelve el bean en un objeto que abre la transacción antes de llamar al método. Una llamada de un método a otro dentro del mismo objeto no pasa por este proxy: si se colocara en el método privado [addPerson], al que llama [addDoctor], la anotación no tendría ningún efecto. [TransactionTemplate] no tiene esta limitación: es una llamada de método normal.

Por último, en caso de fallo, no hay nada que limpiar: el contexto de persistencia está vinculado a la transacción y desaparece con ella en el [ROLLBACK]. La versión de [ASP.NET Core], en cambio, debía borrar el seguimiento de cambios de su [DbContext], que duraba toda la solicitud.

11.13. Autenticación

El archivo [auth] incluye, de forma más completa, los ejemplos 25 a 27: el token JWT en una cookie, los roles, el CAPTCHA y los límites de intentos. También incluye un “pase” para crear una cuenta de cliente. La configuración de [Spring Security] en sí, que reúne estos componentes, se almacena junto con las demás clases de configuración en el archivo [config/SecurityConfig.java]: por aquí empezaremos. El controlador [AuthController], que se analiza al final de esta sección, sirve la página de inicio de sesión.

11.13.1. config/SecurityConfig.java

El archivo se presenta en dos fragmentos. El primero declara los beans de criptografía: la clave, la generación y verificación de tokens, y el hash de contraseñas.

// =========================================================================
// config/SecurityConfig.java
// -------------------------------------------------------------------------
// La configuración de Spring Security (véase el capítulo 8): quién puede acceder
// a qué, y cómo se reconoce al usuario en cada solicitud.
//
// Spring Security es una CADENA DE FILTROS de servlet, colocada delante de Spring
// MVC. Para cada solicitud:
//   1. el filtro "resource server" de OAuth2 busca un token JWT (aquí, en
//      la cookie rdvmedecins_jwt), verifica su firma y su fecha de
//      expiración, y deriva de él al usuario (Authentication);
//   2. el filtro de autorización aplica las reglas de acceso por URL;
//   3. solo entonces Spring MVC llama a la acción, cuyas anotaciones
//      @PreAuthorize (habilitadas por @EnableMethodSecurity) verifican el rol.
// Dos casos de fallo, dos respuestas adecuadas para una aplicación HTML:
//   - ningún usuario autenticado (sin token, token expirado o falsificado)
//     -> redirección a la página de inicio de sesión;
//   - rol insuficiente -> respuesta 403, que ErrorController convierte en una página.
// =========================================================================
package rdvmedecins.config;

import java.nio.charset.StandardCharsets;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder.BCryptVersion;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;

import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.web.Flash;
import rdvmedecins.web.FlashMessage;

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

    // la clave que firma y verifica los tokens (algoritmo simétrico HMAC-SHA256)
    @Bean
    public SecretKey jwtKey(AuthProperties auth) {
        byte[] bytes = auth.jwtSecret().getBytes(StandardCharsets.UTF_8);
        if (bytes.length < 32) {
            // HMAC-SHA256 exige una clave de al menos 256 bits: lo decimos
            // claramente al arrancar y no en el primer inicio de sesión
            throw new IllegalStateException(
                    "rdvmedecins.auth.jwt-secret must be at least 32 characters long (see application.properties).");
        }
        return new SecretKeySpec(bytes, "HmacSHA256");
    }

    // la construcción de los tokens (véase auth/AuthService.java)
    @Bean
    public JwtEncoder jwtEncoder(SecretKey key) {
        return NimbusJwtEncoder.withSecretKey(key).algorithm(MacAlgorithm.HS256).build();
    }

    // la verificación de los tokens: firma y fecha de expiración
    @Bean
    public JwtDecoder jwtDecoder(SecretKey key) {
        return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
    }

    // el hash de las contraseñas: bcrypt, 10 rondas, versión $2b$ - como
    // los hashes del script SQL
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(BCryptVersion.$2B, 10);
    }

Comentemos este código:

  • Líneas 4–18: el comentario de encabezado recuerda el principio analizado en el Capítulo 8: [Spring Security] es una cadena de filtros de servlet, que se ejecutan antes de que la solicitud llegue a [Spring MVC]. Un filtro identifica al usuario a partir del token, otro aplica las reglas de acceso a las URL, y luego la anotación [@PreAuthorize] de cada acción verifica el rol;
  • Línea 54: [@Configuration] convierte la clase en una fuente de beans: cada uno de sus métodos anotados con [@Bean] se llama una vez al inicio, y el objeto que devuelve se convierte en un bean singleton, que [Spring] inyecta dondequiera que se solicite;
  • Línea 55: [@EnableMethodSecurity] habilita la validación de las anotaciones [@PreAuthorize("hasRole('ADMIN')")] colocadas en los controladores (vea el Ejemplo 26). Sin ella, estas anotaciones se ignorarían sin ningún mensaje de error;
  • líneas 59–69: la clave secreta que firma y verifica los tokens (vea el Ejemplo 25). El parámetro [AuthProperties auth] es el record que proporciona una estructura tipada para las propiedades [rdvmedecins.auth.*] de [application.properties] (vea “Configuración del proyecto”): [Spring] lo proporciona igual que cualquier otro bean. Una novedad respecto al Ejemplo 25: se rechaza una clave demasiado corta. El algoritmo HMAC-SHA256 requiere una clave de 256 bits, es decir, 32 bytes; la biblioteca [Nimbus], que genera los tokens, solo lo verificaría al generar el primer token, es decir, en la primera conexión. La excepción lanzada aquí, durante la creación del bean, impide en cambio que la aplicación se inicie, con un mensaje que especifica exactamente qué debe corregirse;
  • Líneas 72–81: generación de tokens ([JwtEncoder]) y verificación ([JwtDecoder]) con la misma clave; el algoritmo es simétrico. El decodificador verifica la firma y la fecha de expiración (claim [exp]). De forma predeterminada, permite una tolerancia de sesenta segundos para las discrepancias de reloj entre servidores: un token sigue siendo válido durante un minuto después de expirar;
  • líneas 85–88: hash de contraseñas con el algoritmo [bcrypt] (vea el Ejemplo 25). Esta vez hay dos parámetros: el costo (10: el algoritmo realiza 2^10 ciclos de cálculo, lo que hace muy costoso un ataque de fuerza bruta con millones de intentos de contraseña) y la versión del algoritmo. Las contraseñas del script SQL se hashearon con una biblioteca que escribe hashes que comienzan con [$2b$10$], mientras que [BCryptPasswordEncoder] escribe [$2a$] de forma predeterminada. Ambas versiones se verifican sin dificultad; imponer la versión [$2B] (una constante de la enumeración [BCryptVersion]: el carácter [$] está permitido en un identificador [Java]) simplemente da a las cuentas creadas por la aplicación hashes de la misma forma que los del script.

El segundo fragmento es la cadena de filtros en sí, con sus dos respuestas de respaldo.

    @Bean
    public SecurityFilterChain securityFilters(HttpSecurity http, Flash flash) throws Exception {
        AuthenticationEntryPoint toLogin = toLogin(flash);
        AccessDeniedHandler accessDenied = (request, response, exception) ->
                response.sendError(HttpServletResponse.SC_FORBIDDEN);
        http
                // 1. las reglas de acceso por URL, evaluadas en orden. Las páginas
                // públicas: inicio de sesión, creación de cuenta, elección de idioma,
                // archivos estáticos, página de error. Todas las demás exigen un
                // usuario autenticado; los roles los verifican los
                // @PreAuthorize de los controladores.
                .authorizeHttpRequests(access -> access
                        .requestMatchers("/", "/login", "/register", "/register/**", "/language/**",
                                "/css/**", "/js/**", "/lib/**", "/error")
                        .permitAll()
                        .anyRequest().authenticated())
                // 2. autenticación por token JWT, leído desde la cookie
                .oauth2ResourceServer(jwt -> jwt
                        .bearerTokenResolver(AuthService::tokenOf)
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied)
                        .jwt(config -> config.jwtAuthenticationConverter(converter())))
                // 3. los dos casos de fallo
                .exceptionHandling(errors -> errors
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied))
                // 4. cierre de sesión (POST /logout): borrar la cookie del token,
                // luego ir a la página de inicio de sesión. Solo POST: un simple
                // enlace (GET), colocado en otro sitio, no puede cerrar la sesión
                // del usuario sin que se entere
                .logout(out -> out
                        .logoutRequestMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/logout"))
                        .deleteCookies(AuthService.JWT_COOKIE)
                        .logoutSuccessUrl("/login"))
                // 5. el servidor no mantiene estado: nunca hay sesión HTTP
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // 6. sin token anti-CSRF: las cookies SameSite=Lax ya protegen
                // las solicitudes POST provenientes de otros sitios (véase AuthService)
                .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // -----------------------------------------------------------------------
    // ningún usuario autenticado -> página de inicio de sesión. Si había una cookie
    // presente, su token ya no es válido: la sesión ha expirado.
    // Entonces borramos la cookie y avisamos al usuario con un mensaje
    // flash (puesto fuera de Spring MVC, de ahí el bean Flash).
    // -----------------------------------------------------------------------
    private static AuthenticationEntryPoint toLogin(Flash flash) {
        return (request, response, exception) -> {
            if (AuthService.tokenOf(request) != null) {
                AuthService.clearToken(response);
                flash.put(request, response, FlashMessage.error("ERRORS.SESSION_EXPIRED"), "/login");
            }
            response.sendRedirect("/login");
        };
    }

    // -----------------------------------------------------------------------
    // del token al usuario autenticado: el claim [name] es su nombre
    // (Authentication.getName()), el claim [role] su rol. Spring Security
    // escribe los roles con el prefijo ROLE_: el claim role=ADMIN se convierte en
    // la autoridad ROLE_ADMIN, que hasRole('ADMIN') verifica.
    // -----------------------------------------------------------------------
    private static JwtAuthenticationConverter converter() {
        JwtGrantedAuthoritiesConverter roles = new JwtGrantedAuthoritiesConverter();
        roles.setAuthoritiesClaimName(ConnectedUser.ROLE);
        roles.setAuthorityPrefix("ROLE_");
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(roles);
        converter.setPrincipalClaimName(ConnectedUser.NAME);
        return converter;
    }
}

Analicemos este código:

  • línea 2: el bean [SecurityFilterChain] describe la cadena de filtros. [HttpSecurity] es un objeto constructor (builder) proporcionado por [Spring Security]: cada método al que se llama sobre él ([authorizeHttpRequests], [oauth2ResourceServer], [logout]...) configura un aspecto de la seguridad, y [build()] (línea 40) construye la cadena. Cada uno recibe una lambda (vea el Ejemplo 25) que configura el aspecto en cuestión. El parámetro [Flash flash] es un bean de la aplicación (carpeta [web]), que sirve para publicar un mensaje flash desde [Spring MVC];
  • Líneas 4–5: la respuesta ante un rol insuficiente: [sendError(403)]. La lambda implementa la interfaz [AccessDeniedHandler], que tiene un solo método (una interfaz funcional). [sendError] no genera una página por sí mismo: el servidor [Tomcat] reenvía la solicitud a [/error], donde [ErrorController] (vea “La capa web: controladores”) genera la página de error 403, como en el Ejemplo 26;
  • Líneas 12–16: las reglas de acceso a las URL, examinadas en orden: se aplica la primera que corresponde a la URL. La raíz, el inicio de sesión, la creación de cuentas, la selección de idioma, los archivos estáticos y la página de error son públicos ([/**] se refiere a todo lo que está bajo una ruta determinada). Cualquier otra URL requiere un usuario autenticado. Los roles no se verifican aquí, sino en cada acción, mediante [@PreAuthorize]: la regla se escribe así junto al código que protege. [/error] debe ser pública: de lo contrario, la página de error para un visitante que no ha iniciado sesión sería a su vez denegada;
  • líneas 18–22: autenticación basada en token JWT, manejada por el módulo de “servidor de recursos” ([OAuth2] “servidor de recursos”) de [Spring Security], como en el Ejemplo 25. De forma predeterminada, este módulo busca el token en el encabezado [Authorization: Bearer ...]; la línea 19 le proporciona otro [BearerTokenResolver], que lo lee de la cookie [rdvmedecins_jwt]. [AuthService::tokenOf] es una referencia a método: la notación abreviada de la lambda [request -> AuthService.tokenOf(request)]. El método estático [tokenOf] (archivo [auth/AuthService.java]) tiene, en efecto, exactamente la forma exigida por la interfaz funcional [BearerTokenResolver]: recibe la solicitud y devuelve el token, o [null]. Línea 22: el conversor que crea el usuario autenticado a partir del token verificado (líneas 65–73);
  • Líneas 20 y 25: el mismo punto de entrada, [toLogin], se especifica dos veces, porque hay dos maneras de no estar autenticado. Un token presente pero inválido (expirado, falsificado) es rechazado por el filtro del servidor de recursos, que llama a su propio punto de entrada (línea 20). Sin token: el filtro deja pasar la solicitud anónima, y el filtro de autorización la rechaza llamando al punto de entrada de [exceptionHandling] (línea 25). De manera similar, el manejador para rol insuficiente se especifica en ambos lugares (líneas 21 y 26). El manejador de [exceptionHandling] (línea 26) maneja los rechazos de [@PreAuthorize]; la línea 21 es una precaución para que las dos configuraciones sigan siendo simétricas. Sin ningún manejador, el servidor de recursos respondería con un error 403 a su manera, con un encabezado [WWW-Authenticate] destinado a un cliente [JavaScript], y sin página de error;
  • Líneas 31–34: el cierre de sesión es manejado por el propio [Spring Security] ; ningún controlador tiene una acción llamada [/logout]. [deleteCookies] borra la cookie del token y luego el navegador es redirigido a [/login]. La línea 32 acepta solo el método POST: cuando la protección CSRF está deshabilitada (línea 39), [Spring Security] acepta [/logout] con cualquier método, incluido GET, y una simple imagen ([<img src="http://.../logout">]) colocada en otro sitio bastaría para cerrar la sesión del usuario. [PathPatternRequestMatcher] describe una solicitud por su método y su ruta;
  • línea 36: [STATELESS]: [Spring Security] nunca crea una sesión HTTP (la cookie [JSESSIONID] de los ejemplos 20 y 23) y no la usa para hacer el seguimiento del usuario: el usuario se reconoce en cada solicitud a partir de su token. El servidor no almacena nada en memoria entre solicitudes;
  • línea 39: de forma predeterminada, [Spring Security] protege los formularios POST contra el ataque CSRF (una página trampa en otro sitio que envía un formulario a nuestro sitio) exigiendo que cada formulario incluya un campo oculto con un token aleatorio. Aquí no lo necesitamos, igual que en el Ejemplo 25: las cookies de la aplicación son [SameSite=Lax], y el navegador no las adjunta a un POST proveniente de otro sitio; la solicitud maliciosa llegaría por lo tanto sin el token JWT (anónima) y sería rechazada;
  • Líneas 49–57: el punto de entrada, es decir, la respuesta a una solicitud no autenticada: una redirección a la página de inicio de sesión (vea el Ejemplo 25). Novedad (líneas 51–54): si la solicitud contenía una cookie de token, significa que el usuario había iniciado sesión, pero su token ya no es válido (expirado o falsificado). Se elimina esta cookie, ahora inútil, y se establece un mensaje flash que dice “sesión expirada”, que la página de inicio de sesión mostrará en lugar de dejar al usuario preguntándose por qué llegó allí. El mensaje es una clave de traducción (vea el Ejemplo 22). Nos encontramos actualmente en un filtro de [Spring Security], anterior a [Spring MVC]: el objeto [RedirectAttributes] del Ejemplo 20 todavía no existe, de ahí el bean [Flash] (comentado junto con la carpeta [web]);
  • Líneas 65–73: el conversor del Ejemplo 26 toma el token verificado y crea el objeto [Authentication], que representa al usuario que hace la solicitud. El claim [role] proporciona las autorizaciones, con el prefijo [ROLE_]: el claim [role=ADMIN] se convierte en la autorización [ROLE_ADMIN], que es verificada por [hasRole('ADMIN')]. El claim [name] se convierte en el nombre de usuario ([Authentication.getName()]). Los nombres de los claims son las constantes del record [ConnectedUser] (siguiente archivo).

Este es el equivalente, en [Spring], de la configuración del manejador [JwtBearer] de [ASP.NET Core] y sus “eventos”: [BearerTokenResolver] actúa como el evento [OnMessageReceived], y [AuthenticationEntryPoint] actúa como [OnChallenge].

Examinemos estas respuestas con [curl], para solicitudes que no requieren inicio de sesión. Una página protegida, solicitada sin cookie, redirige a la página de inicio de sesión:

curl -i http://localhost:8081/schedule
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0

Para continuar, necesitamos un token. Este es el token del paciente [martin]; se generó para este fin usando la clave secreta de [application.properties], mediante un pequeño programa que realiza el cálculo HMAC-SHA256. Esto pone de relieve la importancia de mantener a salvo esta clave secreta: quien la conozca puede generar un token para cualquier persona. Sin embargo, el lector no necesita este cálculo: inicia sesión con su navegador y luego copia el valor de la cookie [rdvmedecins_jwt] desde las herramientas de desarrollo (F12). En producción, se reemplaza por una cadena aleatoria larga (vea “Configuración del proyecto”). Un token consta de tres partes codificadas en Base64, separadas por puntos: el encabezado, el contenido y la firma.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiVVNFUiIsImV4cCI6MTc5MDM2MjAzNiwiaWF0IjoxNzkwMzU0ODM2fQ.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ

Una vez decodificadas, las dos primeras partes son texto plano: el token está firmado, no cifrado.

{"alg":"HS256"}
{"sub":"5","login":"martin","name":"Jean MARTIN","role":"USER","exp":1790362036,"iat":1790354836}

Con este token, la raíz del sitio redirige al paciente a su página de inicio, “Mi cuenta”:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/my-area
Content-Length: 0

(el token está truncado en el comando). Se deniega el acceso a la sección de gestión de médicos, restringida a ADMIN: [@PreAuthorize] deniega el acceso, el manejador [accessDenied] responde con [sendError(403)], y la página de error es generada por [ErrorController]:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/doctors
1
2
3
4
5
6
7
8
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

El atacante intenta ahora hacerse pasar por ADMIN: reemplaza ["role":"USER"] por ["role":"ADMIN"] en el contenido del token, conservando la firma. El contenido modificado ya no coincide con la firma: el token es rechazado y tratado como una sesión expirada:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiQURNSU4iLCJleHAiOjE3OTAzNjIwMzYsImlhdCI6MTc5MDM1NDgzNn0.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ" http://localhost:8081/doctors
1
2
3
4
5
HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTA1OTIwNywiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0; Path=/; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0

El punto de entrada [toLogin] realizó las tres acciones esperadas: se borra la cookie del token (el primer encabezado, [Set-Cookie], la restablece a vacío con una duración de cero), se almacena un mensaje flash en la cookie [rdvmedecins_flash] (segundo encabezado, documentado en el archivo [web/CookieFlashMapManager.java]), y el navegador es redirigido a [/login], donde el mensaje aparece al final de la página:

Image

El mismo proceso se aplica a un token expirado, e incluso en una página pública como [/login]: el filtro del servidor de recursos verifica cualquier token presentado antes de que se examinen las reglas de acceso.

Solo queda el cierre de sesión. Con POST, elimina la cookie del token y redirige a la página de inicio de sesión:

curl -i -X POST http://localhost:8081/logout
1
2
3
4
HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/
Location: http://localhost:8081/login
Content-Length: 0

Con GET, la URL [/logout] es simplemente una página protegida como cualquier otra, y además desconocida: sin token, el punto de entrada redirige la solicitud a la página de inicio de sesión; con un token válido, devolvería una página 404. En ningún caso cierra la sesión del usuario:

curl -i http://localhost:8081/logout
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0

11.13.2. auth/ConnectedUser.java

// =========================================================================
// auth/ConnectedUser.java
// -------------------------------------------------------------------------
// Qué contiene el token JWT y cómo leerlo de nuevo.
//
// En Spring Security, el usuario de la solicitud es un objeto
// Authentication, almacenado en el SecurityContext de la solicitud. Con
// la autenticación por token JWT (véase config/SecurityConfig.java), es un
// JwtAuthenticationToken, que contiene el token verificado: un objeto Jwt, cuyos
// "claims" son los campos del token. Un controlador
// lo obtiene mediante un parámetro @AuthenticationPrincipal Jwt token.
//
// Los claims de nuestros tokens (véase AuthService.setToken):
//   sub   : el id de la cuenta de usuario (convención JWT: "subject")
//   login : el login
//   name  : el nombre para mostrar ("Marie PELISSIER"), para la barra de navegación
//   role  : ADMIN, DOCTOR o USER
// =========================================================================
package rdvmedecins.auth;

import org.springframework.security.oauth2.jwt.Jwt;

import rdvmedecins.entities.Role;

// el usuario conectado, en forma tipada
public record ConnectedUser(int userId, String login, String name, Role role) {

    // los nombres de los claims
    public static final String SUB = "sub";
    public static final String LOGIN = "login";
    public static final String NAME = "name";
    public static final String ROLE = "role";

    // el usuario descrito por un token ya verificado; null si el token
    // está ausente (solicitud no autenticada) o mal formado
    public static ConnectedUser of(Jwt token) {
        if (token == null) {
            return null;
        }
        try {
            return new ConnectedUser(
                    Integer.parseInt(token.getSubject()),
                    token.getClaimAsString(LOGIN),
                    token.getClaimAsString(NAME),
                    Role.valueOf(token.getClaimAsString(ROLE)));
        } catch (RuntimeException e) {
            // NumberFormatException, IllegalArgumentException, NullPointerException
            return null;
        }
    }

    public boolean isAdmin() {
        return role == Role.ADMIN;
    }

    public boolean isPatient() {
        return role == Role.USER;
    }
}

Analicemos este código:

  • Líneas 6–11: en [Spring Security], el usuario de la solicitud es un objeto [Authentication], almacenado en el [SecurityContext] de la solicitud. Con los tokens JWT, es un [JwtAuthenticationToken], que contiene el token verificado, un objeto [Jwt]. Una acción lo recibe mediante un parámetro anotado como [@AuthenticationPrincipal Jwt token] (vea el Ejemplo 25);
  • línea 26: el usuario conectado en forma tipada: un identificador entero, un rol de tipo [Role] (la enumeración [ADMIN], [DOCTOR], [USER] de la carpeta [entities]), en lugar de un token cuyos claims se identifican por nombre. Se trata de un record (vea “El dominio: el calendario”): [Java] genera el constructor y los accesores [userId()], [login()], [name()] y [role()] por nosotros;
  • Líneas 29–32: los nombres de los claims del token, agrupados en constantes: un error tipográfico en [ConnectedUser.NAME] es señalado por el compilador, mientras que un error en la cadena ["name"] solo se descubriría en tiempo de ejecución. Un record puede contener campos estáticos: estos pertenecen a la clase, no a cada objeto;
  • líneas 36–50: el método estático [of] crea al usuario a partir de un token que ya ha sido verificado (su firma es válida), o devuelve [null]. [getSubject()] devuelve el claim [sub], el ID de la cuenta, escrito como texto; [Integer.parseInt] lo convierte en un entero. [Role.valueOf] devuelve la constante de la enumeración con el nombre dado. Ambos métodos lanzan una excepción si el texto no es válido (o si es [null]): un token correctamente firmado pero incompleto devuelve por lo tanto [null], en lugar de un error 500;
  • líneas 52–58: dos métodos para vistas y controladores que evitan comparar roles: [isAdmin()] y [isPatient()]. Una vista [Thymeleaf] simplemente escribe [${user.isAdmin()}].

11.13.3. auth/AuthService.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// auth/AuthService.java
// -------------------------------------------------------------------------
// La lógica de autenticación:
//   - validateUser() : verifica un par login / contraseña;
//   - setToken()     : construye el token JWT de un usuario validado
//                      y lo almacena en una cookie;
//   - clearToken()   : elimina esa cookie;
//   - currentUser()  : el usuario conectado de la solicitud actual.
//
// ¿Por dónde viaja el token JWT?
// Con un cliente JavaScript, era el código del cliente el que guardaba el token
// y lo añadía él mismo a cada solicitud (encabezado "Authorization: Bearer
// ..."). Un navegador que muestra páginas HTML ordinarias no puede
// hacerlo: para que presente el token por sí solo en cada solicitud, debe
// almacenarse en una COOKIE. Las opciones de esta cookie importan para la
// seguridad:
//   - HttpOnly : el JavaScript de la página no puede leer la cookie (un
//     script inyectado no podría, por tanto, robar el token);
//   - SameSite=Lax : el navegador NO envía la cookie con un POST proveniente
//     de otro sitio. Como todas las acciones que modifican datos son
//     POST, una página trampa en otro sitio no puede reservar ni
//     eliminar nada haciéndose pasar por el usuario
//     (el llamado ataque CSRF);
//   - Secure : en producción (HTTPS), la cookie nunca viaja en texto plano;
//   - Max-Age : la cookie desaparece al mismo tiempo que expira el token.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Optional;

import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.security.oauth2.jwt.JwtException;
import org.springframework.stereotype.Service;
import org.springframework.web.util.WebUtils;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.config.AuthProperties;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.UserRepository;

@Service
public class AuthService {

    // el nombre de la cookie que transporta el token
    public static final String JWT_COOKIE = "rdvmedecins_jwt";

    private final UserRepository userRepository;
    private final PasswordEncoder hasher;
    private final JwtEncoder encoder;
    private final JwtDecoder decoder;
    private final AuthProperties auth;

    public AuthService(UserRepository userRepository, PasswordEncoder hasher, JwtEncoder encoder,
            JwtDecoder decoder, AuthProperties auth) {
        this.userRepository = userRepository;
        this.hasher = hasher;
        this.encoder = encoder;
        this.decoder = decoder;
        this.auth = auth;
    }

    // Optional.empty() si el login no existe o si la contraseña es incorrecta.
    // matches aplica un hash a la contraseña digitada con la "sal" contenida en el
    // hash almacenado, y luego compara los dos resultados.
    public Optional<User> validateUser(String login, String password) {
        return userRepository.findByLogin(login).filter(user -> hasher.matches(password, user.getPassword()));
    }

Comentemos este código:

  • líneas 11–26: el comentario explica por qué el token se envía en una cookie y la función de cada una de sus opciones (vea el Ejemplo 25). Un navegador que sigue enlaces y envía formularios no sabe cómo agregar un encabezado [Authorization] a sus solicitudes; en cambio, devuelve automáticamente las cookies que ha recibido;
  • línea 57: [@Service] convierte la clase en un bean singleton (vea el Ejemplo 06), al igual que [@Component]: las dos anotaciones son equivalentes, y [@Service] indica simplemente que se trata de un servicio;
  • línea 61: el nombre de la cookie que transporta el token;
  • líneas 63–76: el servicio recibe el DAO que contiene las cuentas de usuario ([UserRepository], vea “La capa DAO”), el codificador [bcrypt], el codificador y decodificador de tokens (los beans de [SecurityConfig]) y las propiedades de autenticación. Los campos son [final]: no cambian después de la construcción;
  • líneas 81–83: la cuenta, si el nombre de usuario y la contraseña son correctos (vea el Ejemplo 25). [findByLogin] devuelve un [Optional<User>], una caja que contiene una cuenta o está vacía (vea “La capa DAO”); [filter] conserva la cuenta solo si la condición es verdadera; de lo contrario, devuelve una caja vacía. La condición, [hasher.matches(...)], aplica el hash a la contraseña ingresada con la “sal” contenida en el hash almacenado y compara los dos resultados: la contraseña en sí nunca se almacena.
    // -----------------------------------------------------------------------
    // construye el token JWT de [user] y lo coloca en una cookie.
    // El token está FIRMADO (HMAC-SHA256) con la clave secreta: el navegador
    // puede leerlo (no está cifrado), pero no modificarlo - cualquier
    // modificación invalidaría la firma.
    // -----------------------------------------------------------------------
    public void setToken(HttpServletResponse response, User user) {
        Instant now = Instant.now();
        JwtClaimsSet claims = JwtClaimsSet.builder()
                .subject(String.valueOf(user.getId()))
                .claim(ConnectedUser.LOGIN, user.getLogin())
                .claim(ConnectedUser.NAME, user.getName())
                .claim(ConnectedUser.ROLE, user.getRole().name())
                .issuedAt(now)
                .expiresAt(now.plusSeconds(auth.jwtExpiresInSeconds()))
                .build();
        String token = encoder.encode(JwtEncoderParameters.from(JwsHeader.with(MacAlgorithm.HS256).build(), claims))
                .getTokenValue();
        ResponseCookie cookie = ResponseCookie.from(JWT_COOKIE, token)
                .httpOnly(true)
                .sameSite("Lax")
                .secure(auth.cookieSecure())
                .maxAge(Duration.ofSeconds(auth.jwtExpiresInSeconds()))
                .path("/")
                .build();
        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    }

    // borra la cookie: la establecemos de nuevo, vacía, con una duración cero
    public static void clearToken(HttpServletResponse response) {
        response.addHeader(HttpHeaders.SET_COOKIE, ResponseCookie.from(JWT_COOKIE, "").path("/").maxAge(0).build().toString());
    }

    // el token presente en la solicitud, sea válido o no
    public static String tokenOf(HttpServletRequest request) {
        Cookie cookie = WebUtils.getCookie(request, JWT_COOKIE);
        return cookie == null ? null : cookie.getValue();
    }

    // -----------------------------------------------------------------------
    // el usuario conectado, o null.
    // Normalmente, Spring Security ya lo ha establecido (SecurityContextHolder).
    // Pero una página de error se construye mediante una SEGUNDA solicitud interna,
    // enviada por el servidor a la dirección /error, que no pasa de nuevo por
    // la autenticación: entonces leemos nosotros mismos el token de la cookie, para
    // que la barra de navegación de la página de error muestre al usuario.
    // -----------------------------------------------------------------------
    public ConnectedUser currentUser(HttpServletRequest request) {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication != null && authentication.getPrincipal() instanceof Jwt token) {
            return ConnectedUser.of(token);
        }
        String token = tokenOf(request);
        if (token == null) {
            return null;
        }
        try {
            return ConnectedUser.of(decoder.decode(token));
        } catch (JwtException e) {
            return null; // token expirado o falsificado
        }
    }
}

Comentemos este código:

  • Líneas 8–19: el token, generado como en el Ejemplo 25. Contiene el ID de la cuenta (claim [sub]), el login, el nombre que se muestra en la barra de navegación, el rol, la fecha de emisión ([iat], “issued at”) y la fecha de expiración ([exp]), que es dos horas posterior de forma predeterminada. [JwtClaimsSet.builder()] devuelve un objeto constructor: se llama a un método por cada claim, seguido de [build()]. Línea 18: el encabezado del token especifica el algoritmo HS256 (HMAC-SHA256), y el codificador firma todo el token con la clave secreta;
  • Líneas 20–27: la cookie, con las opciones del Ejemplo 25 ([HttpOnly], [SameSite=Lax]) y dos adicionales: [Secure], habilitada en producción (sitio servido como [HTTPS]), impide que el navegador envíe la cookie por una conexión sin cifrar; [Path=/] garantiza que se incluya en todas las solicitudes al sitio. [Max-Age] elimina la cookie cuando el token expira. [ResponseCookie] genera el texto del encabezado [Set-Cookie], que la línea 27 agrega a la respuesta;
  • líneas 31–33: eliminar una cookie consiste en establecerla de nuevo, vacía, con una duración de cero; el navegador la elimina de inmediato. Para que el navegador reconozca la cookie que se va a eliminar, la ruta ([Path]) debe ser la misma que se usó al establecerla. El método es estático: no depende de ningún campo del objeto. Lo usan el punto de entrada [SecurityConfig] y el manejador de excepciones [HtmlExceptionHandler] (archivo [web]), que no necesitan una instancia de [AuthService];
  • líneas 36–39: el token presente en la solicitud, sin verificarlo. [WebUtils.getCookie] busca una cookie por nombre entre las de la solicitud. Este es el método que [SecurityConfig] proporciona como [BearerTokenResolver];
  • líneas 49–63: el usuario conectado, o [null]. En el caso típico (líneas 50–53), [Spring Security] ya lo ha establecido: [SecurityContextHolder.getContext().getAuthentication()] devuelve el objeto [Authentication] de la solicitud actual, cuyo “principal” es el token verificado. [instanceof Jwt token] verifica el tipo del objeto y, si la verificación tiene éxito, lo almacena en la variable [token], que ya ha sido convertida a [Jwt]. El segundo caso (líneas 54–62) concierne a la página de error: cuando una solicitud termina con un error 403 o 404, el servidor genera la página mediante una segunda solicitud interna a [/error]. El filtro del servidor de recursos no procesa esta solicitud interna: el usuario no está autenticado para ella. Para que la barra de navegación de la página de error siga mostrando al usuario, verificamos nosotros mismos el token de la cookie con el decodificador de [SecurityConfig]; un token expirado o falsificado provoca una [JwtException], y devolvemos [null].

El método [currentUser] es llamado para cada página por [web/CommonModel.java], que establece el usuario en el modelo para todas las vistas.

11.13.4. auth/InvalidSessionException.java

// =========================================================================
// auth/InvalidSessionException.java
// -------------------------------------------------------------------------
// El token es válido, pero la cuenta que designa ya no existe: fue
// eliminada desde el inicio de sesión (por el propio paciente en otra
// pestaña, o por el ADMIN). Tratamos este caso como una sesión expirada:
// web/HtmlExceptionHandler borra la cookie y redirige a la página de
// inicio de sesión.
// =========================================================================
package rdvmedecins.auth;

public class InvalidSessionException extends RuntimeException {

    public InvalidSessionException() {
        super("the account of the connected user no longer exists");
    }
}
  • Líneas 12–16: un token puede ser válido (correctamente firmado, no expirado) aunque la cuenta a la que se refiere haya sido eliminada desde que el usuario inició sesión. Las páginas de paciente lo detectan buscando el cliente asociado a la cuenta (método [connectedPatient] en el archivo [web/Utils.java]) y luego lanzan esta excepción; el manejador de excepciones [HtmlExceptionHandler] (vea el Ejemplo 24) la intercepta, elimina la cookie y redirige a la página de inicio de sesión con el mensaje “sesión expirada”. La excepción deriva de [RuntimeException]: es una excepción no verificada (unchecked), que los métodos no necesitan declarar mediante una cláusula [throws]. El constructor pasa su mensaje al constructor de la clase padre mediante [super(...)].

11.13.5. auth/Captcha.java

// =========================================================================
// auth/Captcha.java
// -------------------------------------------------------------------------
// Un captcha: id, para colocar en el campo oculto "captchaId" del formulario;
// svg, la imagen, para insertar tal cual en la página.
// =========================================================================
package rdvmedecins.auth;

public record Captcha(String id, String svg) {
}
  • Línea 9: un CAPTCHA, tal como lo recibe la página: el identificador, que se colocará en un campo oculto del formulario, y la imagen [SVG], que se insertará tal cual en la página. Basta con un solo record: el objeto es de solo lectura. La respuesta esperada no aparece aquí: nunca sale del servidor.

11.13.6. auth/CaptchaService.java

// =========================================================================
// auth/CaptchaService.java
// -------------------------------------------------------------------------
// Un CAPTCHA ("prueba para distinguir a un humano de un robot") creado por el
// propio servidor, sin ningún servicio externo: unos pocos caracteres distorsionados,
// confundidos con trazos, en una imagen SVG (véase CaptchaDrawing.java). Un
// humano los lee sin dificultad; un robot que se limita a enviar
// formularios en bucle no puede hacerlo.
//
// Cómo funciona:
//   1. generate() dibuja un texto aleatorio, lo convierte en imagen y almacena
//      la respuesta correcta EN LA MEMORIA DEL SERVIDOR, bajo un identificador aleatorio;
//   2. la página muestra la imagen y coloca el identificador en un campo oculto del
//      formulario (la respuesta nunca sale del servidor);
//   3. verify(id, input) compara la entrada con la respuesta esperada y luego
//      OLVIDA este captcha: cada imagen se usa una sola vez, un robot no puede
//      reutilizar una respuesta ya encontrada.
//
// Bean SINGLETON (una sola instancia para todo el servidor), usado por
// varias solicitudes EN PARALELO: de ahí el ConcurrentHashMap, un
// diccionario que varios hilos pueden leer y modificar al mismo tiempo
// sin corromperlo.
//
// Límite aceptado: la memoria de un solo proceso. Con varios servidores
// detrás de un balanceador de carga, haría falta un almacenamiento compartido.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.stereotype.Service;

@Service
public class CaptchaService {

    // duración de validez de una imagen: se dispone de 10 minutos para completar el formulario
    private static final Duration LIFETIME = Duration.ofMinutes(10);

    // salvaguarda de memoria: por encima de este valor, olvidamos todos los captchas pendientes
    private static final int MAX_CAPTCHAS = 10_000;

    // la respuesta esperada y su fecha de expiración
    private record Expected(String text, Instant expires) {
    }

    // id -> respuesta esperada
    private final Map<String, Expected> pending = new ConcurrentHashMap<>();

    public Captcha generate() {
        purge();
        String text = CaptchaDrawing.randomText(5); // 5 caracteres
        String id = UUID.randomUUID().toString(); // un identificador aleatorio, imposible de adivinar
        pending.put(id, new Expected(text, Instant.now().plus(LIFETIME)));
        return new Captcha(id, CaptchaDrawing.svg(text));
    }

    // true si [input] es la respuesta correcta al captcha [id] (sin distinguir
    // mayúsculas de minúsculas). El captcha se consume en todos los casos.
    // remove es ATÓMICO: si dos solicitudes presentan el mismo captcha en el
    // mismo instante, solo una lo elimina - la otra falla.
    public boolean verify(String id, String input) {
        Expected expected = id == null ? null : pending.remove(id);
        return expected != null && input != null
                && expected.expires().isAfter(Instant.now())
                && expected.text().equalsIgnoreCase(input.trim());
    }

    private void purge() {
        Instant now = Instant.now();
        pending.entrySet().removeIf(e -> !e.getValue().expires().isAfter(now));
        if (pending.size() >= MAX_CAPTCHAS) {
            pending.clear();
        }
    }
}

El servicio es el mismo que en el Ejemplo 27, con dos adiciones: un tiempo de expiración y un límite. Recorramos este código:

  • línea 37: un bean singleton: un único servicio para todo el servidor, es decir, una única lista de CAPTCHA pendientes compartida por todas las solicitudes;
  • líneas 41–44: una imagen es válida durante diez minutos, y el número de CAPTCHA pendientes tiene un tope. Cada vez que se muestra la página de inicio de sesión, se agrega un CAPTCHA a la memoria; sin un límite, un bot que solicitara esta página millones de veces sin responder terminaría por agotar la memoria del servidor. [10_000]: el carácter [_] separa los dígitos en grupos para facilitar la lectura;
  • líneas 47–48: la respuesta esperada y su fecha de expiración. El record es anidado y privado: existe solo para este servicio. [Instant] representa un instante específico en el tiempo, independiente de la zona horaria;
  • línea 51: identificador → respuesta esperada. El servicio es un singleton, usado por solicitudes concurrentes, cada una en su propio hilo de ejecución ([thread]): de ahí [ConcurrentHashMap] (vea el Ejemplo 27), un diccionario que varias instancias de [threads] pueden leer y modificar al mismo tiempo sin corromperlo. El campo se declara del tipo definido por la interfaz [Map]: el resto del código no depende de la implementación elegida;
  • líneas 53–59: limpieza, seguida de una cadena de texto de cinco caracteres generada aleatoriamente, almacenada bajo un identificador aleatorio ([UUID.randomUUID()], 122 bits aleatorios, imposible de adivinar), y dibujada por [CaptchaDrawing];
  • líneas 65–70: la verificación, idéntica a la del Ejemplo 27: el CAPTCHA se elimina del diccionario en todos los casos ([remove] devuelve el valor eliminado, o [null]), luego se verifica que existía, que no ha expirado y que la entrada (sin espacios) es correcta, sin distinguir mayúsculas de minúsculas ([equalsIgnoreCase]). [remove] es atómico: si dos solicitudes presentan el mismo CAPTCHA al mismo tiempo, solo una lo elimina; la otra recibe [null]. Por lo tanto, cada imagen se usa una sola vez: un bot no puede reutilizar una respuesta encontrada previamente;
  • Líneas 72–78: limpieza. [removeIf] elimina del diccionario las entradas para las que la función lambda devuelve [true], en este caso, los CAPTCHA expirados. Si aun así se alcanza el límite (hay un ataque en curso), se descartan todos los CAPTCHA pendientes: los usuarios legítimos que estaban completando el formulario en ese momento tendrán que volver a resolver con una imagen nueva. Esta situación solo se da en caso de ataque: esta solución simple es suficiente.

11.13.7. auth/CaptchaDrawing.java

La clase que dibuja la imagen es la del Ejemplo 27. Se presenta en dos secciones: la “fuente” de caracteres, seguida del dibujo.

// =========================================================================
// auth/CaptchaDrawing.java
// -------------------------------------------------------------------------
// El dibujo de la imagen SVG (150 x 50 píxeles) de un captcha, tomado tal cual
// del ejemplo 27. Un punto importante: cada carácter se dibuja con
// TRAZOS (<path>), nunca se escribe como texto (<text>) - de lo contrario un robot
// solo tendría que leer el código fuente de la imagen.
// =========================================================================
package rdvmedecins.auth;

import java.security.SecureRandom;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;

final class CaptchaDrawing {

    private static final int WIDTH = 150;
    private static final int HEIGHT = 50;

    // SecureRandom: un generador de números aleatorios "criptográfico",
    // impredecible (a diferencia de Random, cuya secuencia podría adivinarse)
    private static final SecureRandom RANDOM = new SecureRandom();

    // La "fuente": cada carácter es una lista de trazos, cada trazo una
    // secuencia de puntos (x, y) en una cuadrícula de 4 x 6 (y hacia abajo).
    // Caracteres demasiado fáciles de confundir entre sí: excluidos (0 O, 1 I L).
    private static final Map<Character, double[][]> FONT = new LinkedHashMap<>();

    static {
        FONT.put('A', new double[][] { { 0, 6, 2, 0, 4, 6 }, { 0.8, 3.8, 3.2, 3.8 } });
        FONT.put('B', new double[][] { { 0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 }, { 0, 0, 3, 0, 4, 1, 4, 2, 3, 3 } });
        FONT.put('C', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5 } });
        FONT.put('D', new double[][] { { 0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0 } });
        FONT.put('E', new double[][] { { 4, 0, 0, 0, 0, 6, 4, 6 }, { 0, 3, 3, 3 } });
        FONT.put('F', new double[][] { { 4, 0, 0, 0, 0, 6 }, { 0, 3, 3, 3 } });
        FONT.put('G', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5 } });
        FONT.put('H', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 4, 6 }, { 0, 3, 4, 3 } });
        FONT.put('J', new double[][] { { 4, 0, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('K', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 0, 3.5 }, { 1.3, 2.6, 4, 6 } });
        FONT.put('M', new double[][] { { 0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6 } });
        FONT.put('N', new double[][] { { 0, 6, 0, 0, 4, 6, 4, 0 } });
        FONT.put('P', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 } });
        FONT.put('Q', new double[][] { { 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0 }, { 2.5, 4.5, 4, 6.3 } });
        FONT.put('R', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 }, { 2, 3, 4, 6 } });
        FONT.put('S', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('T', new double[][] { { 0, 0, 4, 0 }, { 2, 0, 2, 6 } });
        FONT.put('U', new double[][] { { 0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0 } });
        FONT.put('V', new double[][] { { 0, 0, 2, 6, 4, 0 } });
        FONT.put('W', new double[][] { { 0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0 } });
        FONT.put('X', new double[][] { { 0, 0, 4, 6 }, { 4, 0, 0, 6 } });
        FONT.put('Y', new double[][] { { 0, 0, 2, 3, 4, 0 }, { 2, 3, 2, 6 } });
        FONT.put('Z', new double[][] { { 0, 0, 4, 0, 0, 6, 4, 6 } });
        FONT.put('2', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6 } });
        FONT.put('3', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3 }, { 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('4', new double[][] { { 3, 6, 3, 0, 0, 4, 4, 4 } });
        FONT.put('5', new double[][] { { 4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('6', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 } });
        FONT.put('7', new double[][] { { 0, 0, 4, 0, 1.5, 6 } });
        FONT.put('8', new double[][] { { 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3 } });
        FONT.put('9', new double[][] { { 4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5 } });
    }

    private static final char[] ALPHABET = FONT.keySet().stream()
            .map(String::valueOf).reduce("", String::concat).toCharArray();

    // unos pocos colores oscuros, fáciles de leer sobre el fondo claro
    private static final String[] COLORS = { "#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b" };

Comentemos este código:

  • línea 16: la clase no es [public]; sin modificador, solo es visible dentro de su paquete ([rdvmedecins.auth]), donde solo la usa [CaptchaService] . [final] prohíbe derivar otra clase a partir de ella;
  • línea 23: [SecureRandom] es un generador de números aleatorios “criptográfico”: sus salidas son impredecibles, mientras que las de [Random] podrían adivinarse a partir de salidas anteriores. Se usa un único generador para todos los sorteos; puede ser usado por varias instancias de [threads] al mismo tiempo;
  • líneas 28–62: la “fuente”: para cada carácter, una lista de trazos, siendo cada trazo una secuencia de coordenadas (x, y) en una cuadrícula de 4 × 6. [double[][]] es un arreglo de arreglos, escrito aquí en forma expandida con llaves. El diccionario se llena mediante un bloque [static { ... }] (líneas 30–62), que se ejecuta una vez al cargarse la clase. Se omiten los caracteres que se confunden fácilmente (0 y O, 1, I y L). Un [LinkedHashMap] conserva el orden de inserción de las claves;
  • líneas 64–65: los caracteres utilizables, es decir, las claves de la fuente, se recopilan en un arreglo de [char]. El flujo (vea “La capa de negocio”) de claves se convierte en cadenas de un solo carácter ([String::valueOf]), que se concatenan ([reduce("", String::concat)]), y luego la cadena resultante se divide en un arreglo ([toCharArray()]).
    private CaptchaDrawing() {
    }

    static String randomText(int length) {
        StringBuilder text = new StringBuilder();
        for (int i = 0; i < length; i++) {
            text.append(ALPHABET[RANDOM.nextInt(ALPHABET.length)]);
        }
        return text.toString();
    }

    private static double randomBetween(double min, double max) {
        return min + (max - min) * RANDOM.nextDouble();
    }

    private static String color() {
        return COLORS[RANDOM.nextInt(COLORS.length)];
    }

    static String svg(String text) {
        StringBuilder svg = new StringBuilder();
        svg.append("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"%d\" height=\"%d\" viewBox=\"0 0 %d %d\">"
                .formatted(WIDTH, HEIGHT, WIDTH, HEIGHT));
        svg.append("<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // los caracteres: cada uno ampliado, inclinado, desplazado, y cada punto
        // ligeramente movido al azar
        double step = (WIDTH - 20) / (double) text.length();
        for (int i = 0; i < text.length(); i++) {
            double scale = randomBetween(4.6, 5.6); // tamaño de una unidad de la cuadrícula, en píxeles
            double angle = randomBetween(-0.35, 0.35); // rotación, en radianes (aproximadamente ±20°)
            double cx = 10 + step * (i + 0.5) + randomBetween(-3, 3); // centro del carácter
            double cy = HEIGHT / 2.0 + randomBetween(-4, 4);
            StringBuilder d = new StringBuilder();
            for (double[] stroke : FONT.get(text.charAt(i))) {
                for (int k = 0; k < stroke.length; k += 2) {
                    // punto de la cuadrícula, centrado en (2, 3), distorsionado, rotado, colocado
                    double x = (stroke[k] - 2 + randomBetween(-0.2, 0.2)) * scale;
                    double y = (stroke[k + 1] - 3 + randomBetween(-0.2, 0.2)) * scale;
                    double px = cx + x * Math.cos(angle) - y * Math.sin(angle);
                    double py = cy + x * Math.sin(angle) + y * Math.cos(angle);
                    d.append(k == 0 ? 'M' : 'L').append(number(px)).append(' ').append(number(py)).append(' ');
                }
            }
            svg.append("<path d=\"%s\" fill=\"none\" stroke=\"%s\" stroke-width=\"%s\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>"
                    .formatted(d.toString().trim(), color(), number(randomBetween(2.2, 3))));
        }

        // 3 trazos de confusión: curvas que cruzan la imagen
        for (int n = 0; n < 3; n++) {
            svg.append("<path d=\"M%s %s C%s %s %s %s %s %s\" fill=\"none\" stroke=\"%s\" stroke-width=\"1.3\"/>"
                    .formatted(number(randomBetween(0, 20)), number(randomBetween(5, 45)),
                            number(randomBetween(30, 60)), number(randomBetween(0, 50)), number(randomBetween(90, 120)), number(randomBetween(0, 50)),
                            number(randomBetween(130, 150)), number(randomBetween(5, 45)), color()));
        }
        svg.append("</svg>");
        return svg.toString();
    }

    // un número con punto decimal, sea cual sea el idioma del servidor
    // (en francés, "%.1f" escribiría "12,5" - ilegible para SVG)
    private static String number(double value) {
        return String.format(Locale.ROOT, "%.1f", value);
    }
}

Comentemos este código:

  • líneas 1–2: un constructor privado: la clase contiene solo métodos estáticos, por lo que nunca se crean objetos;
  • líneas 4–18: selecciones aleatorias: un texto de la longitud solicitada, un número real entre dos límites, un color. [nextInt(n)] devuelve un entero entre 0 y n – 1, [nextDouble()] devuelve un número real entre 0 y 1;
  • Líneas 20–58: la imagen es un texto [SVG], ensamblado dentro de un [StringBuilder] (una cadena que se extiende sin tener que reescribirse cada vez que se agrega un elemento). El método [formatted] reemplaza el [%d] (un entero) y el [%s] (una cadena) por sus argumentos, en orden. Cada carácter (líneas 29–47) se convierte en un elemento [<path>] (una ruta): cada punto de la cuadrícula se desplaza ligeramente, se agranda, se gira y se coloca en su posición en la imagen, con un color y un grosor de línea seleccionados al azar. Los caracteres son líneas, nunca texto: un robot no puede leerlos en el código de la imagen. Luego, tres curvas de confusión cruzan la imagen (líneas 50–55);
  • líneas 62–64: los números en [SVG] se escriben con punto decimal. [Locale.ROOT] impone esta notación independientemente del idioma del servidor: con el francés como idioma, [%.1f] usaría una coma (vea el Capítulo 5).

11.13.8. auth/AttemptLimiterService.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// auth/AttemptLimiterService.java
// -------------------------------------------------------------------------
// Segunda barrera contra los robots (la primera es el captcha): CONTAMOS los
// intentos y, superado un umbral, BLOQUEAMOS durante un tiempo.
//
//   - login: tras loginMaxFailures fallos (captcha incorrecto o contraseña
//     incorrecta) para el mismo login desde la misma dirección IP, este par
//     se bloquea durante loginBlockMinutes minutos. La misma dirección IP también se
//     bloquea si acumula 5 veces más fallos, sumando todos los logins (un
//     robot que prueba miles de logins distintos);
//   - creación de cuenta: como máximo registrationMaxPerHour cuentas creadas por
//     hora desde la misma dirección IP.
//
// Cuidado en el aula: todas las computadoras suelen salir a Internet
// por la MISMA dirección IP. Por eso el bloqueo de inicio de sesión se aplica
// primero al par (IP, login) - un estudiante que digita una contraseña
// incorrecta no bloquea a sus compañeros - y por eso los umbrales se pueden ajustar
// en application.properties (rdvmedecins.protection.*).
//
// Bean singleton, llamado por solicitudes en paralelo: todos los métodos públicos
// son "synchronized" - un solo hilo a la vez lee Y modifica
// los contadores.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;

import org.springframework.stereotype.Service;

import rdvmedecins.config.ProtectionProperties;

@Service
public class AttemptLimiterService {

    private static class Counter {
        int count; // intentos contados en la ventana actual
        Instant start; // inicio de la ventana de conteo
        Instant blockedUntil = Instant.MIN; // Instant.MIN si no está bloqueado
    }

    private static final Duration ONE_HOUR = Duration.ofHours(1);

    private final Map<String, Counter> counters = new HashMap<>();

    private final int maxLoginFailures;
    private final Duration loginBlockDuration;
    private final int maxRegistrations;

    public AttemptLimiterService(ProtectionProperties protection) {
        this.maxLoginFailures = protection.loginMaxFailures();
        this.loginBlockDuration = Duration.ofMinutes(protection.loginBlockMinutes());
        this.maxRegistrations = protection.registrationMaxPerHour();
    }

    // ---------------------------------------------------------------- inicio de sesión

    // número de minutos de bloqueo restantes (0 = el intento está permitido)
    public synchronized long loginBlockMinutes(String ip, String login) {
        return Math.max(remainingMinutes(loginKey(ip, login)), remainingMinutes(ipKey(ip)));
    }

    public synchronized void loginFailure(String ip, String login) {
        count(loginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
        count(ipKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
    }

    // un inicio de sesión exitoso reinicia el contador de ESTE login
    public synchronized void loginSuccess(String ip, String login) {
        counters.remove(loginKey(ip, login));
    }

    // ---------------------------------------------------------------- registro

    public synchronized long registrationBlockMinutes(String ip) {
        return remainingMinutes("registration|" + ip);
    }

    // ventana de una hora; una vez alcanzada la cuota, bloqueado hasta el final de la hora
    public synchronized void registrationSuccess(String ip) {
        count("registration|" + ip, maxRegistrations, ONE_HOUR, ONE_HOUR);
    }

En comparación con [LimiterService] del Ejemplo 27, el limitador protege dos operaciones (la conexión y la creación de cuentas), el bloqueo de conexión se aplica al par (dirección IP, login), y los umbrales son configurables en [application.properties]. Comentemos este código:

  • líneas 40–44: un contador: el número de intentos, el inicio de la ventana de conteo y el fin del bloqueo ([Instant.MIN], el instante más antiguo posible, si no hay bloqueo). Se trata de una clase estática privada anidada: existe solo para este servicio. Es una clase normal, no un record: un contador leído del diccionario se modifica en el mismo lugar, lo cual no está permitido con un record;
  • línea 48: un [HashMap] común, no un [ConcurrentHashMap]: contar un intento implica leer un contador, modificarlo y posiblemente reemplazarlo, y toda esta secuencia de operaciones debe ejecutarse sin que otra solicitud la interrumpa. Este es el papel de la palabra clave [synchronized] (vea el Ejemplo 27), colocada en cada método público: solo un [thread] a la vez puede ejecutar uno de los métodos [synchronized] del objeto; los demás esperan su turno;
  • líneas 54–58: los umbrales, leídos una vez por todas del record [ProtectionProperties], que proporciona una forma tipada para las propiedades [rdvmedecins.protection.*]: el número de fallos de conexión permitidos (5 de forma predeterminada), la duración del bloqueo (15 minutos) y el número de cuentas creadas por hora (10);
  • líneas 63–65: el tiempo de bloqueo restante para un intento de inicio de sesión: el mayor de los dos posibles períodos de bloqueo, el del par (dirección IP, login) y el de la dirección IP sola;
  • líneas 67–70: un intento fallido se cuenta dos veces. Para el par (dirección IP, login): cinco intentos fallidos con el mismo login bloquean ese login, solo desde esa dirección. Para la dirección IP sola, con un umbral cinco veces mayor: un bot que prueba una gran cantidad de logins diferentes también queda bloqueado. En un aula, todas las computadoras suelen conectarse a Internet mediante la misma dirección IP: un estudiante que ingresa una contraseña incorrecta no debe bloquear a sus compañeros, de ahí el bloqueo por par;
  • líneas 73–75: un inicio de sesión exitoso restablece el contador de ese login específico (no el de la dirección IP);
  • líneas 79–86: para la creación de cuentas, solo se cuentan los intentos exitosos: un máximo de diez cuentas por hora desde la misma dirección IP. Una vez alcanzada la cuota, la dirección se bloquea durante una hora.
    // ---------------------------------------------------------------- mecánica compartida
    // (los métodos privados siempre son llamados por un método synchronized)

    private long remainingMinutes(String key) {
        Counter c = counters.get(key);
        if (c == null) {
            return 0;
        }
        Duration remaining = Duration.between(Instant.now(), c.blockedUntil);
        // redondeado HACIA ARRIBA al minuto: 30 s de bloqueo restante -> "1 minute"
        return remaining.isNegative() || remaining.isZero() ? 0 : (remaining.toSeconds() + 59) / 60;
    }

    // cuenta un intento; si se alcanza el umbral dentro de la ventana, bloquea
    private void count(String key, int max, Duration window, Duration block) {
        Instant now = Instant.now();
        purge(now);
        Counter c = counters.get(key);
        if (c == null || Duration.between(c.start, now).compareTo(window) > 0) {
            c = new Counter();
            c.start = now;
            counters.put(key, c);
        }
        c.count++;
        if (c.count >= max) {
            c.blockedUntil = now.plus(block);
            c.count = 0; // tras el bloqueo, se empieza de nuevo desde cero
            c.start = c.blockedUntil;
        }
    }

    // olvidamos los contadores que ya no son útiles (ni bloqueados, ni recientes)
    private void purge(Instant now) {
        if (counters.size() < 1000) {
            return;
        }
        counters.values().removeIf(c -> c.blockedUntil.isBefore(now)
                && Duration.between(c.start, now).compareTo(ONE_HOUR) > 0);
    }

    private static String loginKey(String ip, String login) {
        return "login|" + ip + "|" + login.trim().toLowerCase(Locale.ROOT);
    }

    private static String ipKey(String ip) {
        return "ip|" + ip;
    }
}

Analicemos este código:

  • líneas 4–12: el tiempo de bloqueo restante, redondeado hacia arriba al siguiente número entero: quedan “1 minuto”, no “0 minutos”, cuando faltan 20 segundos. [Duration.between] mide la diferencia de tiempo entre dos instantes. Estos métodos privados no son [synchronized]: siempre los llama un método público que ya tiene el bloqueo del objeto;
  • líneas 15–30: el conteo. Una clave desconocida, o cuya ventana de conteo ha expirado, comienza con un contador nuevo. Cuando se alcanza el umbral, la clave se bloquea, y el conteo se reanudará desde cero una vez que se libere el bloqueo;
  • líneas 33–39: limpieza de los contadores que ya no son necesarios (ni bloqueados ni recientes), que se realiza solo cuando el diccionario supera las 1000 entradas. [values()] es una vista de los valores del diccionario: [removeIf] elimina los contadores de ella, y las entradas correspondientes desaparecen del diccionario;
  • líneas 41–47: generación de las claves del diccionario. Al login se le quitan los espacios y se convierte a minúsculas: [Admin] y [admin] comparten el mismo contador; un bot no puede eludir el bloqueo cambiando las mayúsculas y minúsculas. [Locale.ROOT] hace que la conversión sea independiente del idioma del servidor.

Examinemos el bloqueo. Un bot que intenta el login [robot] sin poder leer la imagen falla el CAPTCHA; cada fallo se cuenta. En el sexto intento, el par (dirección IP, [robot]) queda bloqueado, y ni siquiera se verifica el CAPTCHA. Este es el mensaje que se muestra al final de la página en cada uno de los seis intentos:

curl -X POST -d "login=robot&password=x&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
1
2
3
4
5
6
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>Too many failed attempts. Try again in 15 minute(s).</div>

Los demás logins siguen siendo utilizables desde la misma dirección.

11.13.9. auth/RegistrationPassService.java

// =========================================================================
// auth/RegistrationPassService.java
// -------------------------------------------------------------------------
// El "pase" para la creación de cuentas.
//
// Para abrir la página "Create a client account", primero hay que haber
// copiado el captcha de la página de autenticación (véase
// RegistrationController, POST /register/access). Entonces el servidor emite
// un pase:
//   - un identificador aleatorio, almacenado en una cookie HttpOnly;
//   - válido durante 15 minutos (el tiempo para completar el formulario, incluso
//     tras varios intentos por errores de entrada);
//   - consumido en cuanto se crea una cuenta: UN captcha resuelto = UNA cuenta como
//     máximo. Un robot no puede crear cuentas en serie.
//
// Sin un pase válido, GET y POST /register redirigen a la página de
// autenticación: digitar directamente la URL /register no permite
// eludir el captcha.
//
// Al igual que el captcha, los pases viven en la memoria del proceso.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.http.ResponseCookie;
import org.springframework.stereotype.Service;

@Service
public class RegistrationPassService {

    public static final String COOKIE = "rdvmedecins_registration";

    private static final Duration LIFETIME = Duration.ofMinutes(15);
    private static final int MAX_PASSES = 10_000;

    // id -> fecha de expiración
    private final Map<String, Instant> passes = new ConcurrentHashMap<>();

    // emite un nuevo pase; devuelve su identificador
    public String issue() {
        purge();
        String id = UUID.randomUUID().toString();
        passes.put(id, Instant.now().plus(LIFETIME));
        return id;
    }

    // true si [id] es un pase existente y no expirado
    public boolean isValid(String id) {
        Instant expires = id == null ? null : passes.get(id);
        return expires != null && expires.isAfter(Instant.now());
    }

    // el pase se ha usado: lo olvidamos
    public void consume(String id) {
        if (id != null) {
            passes.remove(id);
        }
    }

    // el navegador solo envía la cookie a las direcciones /register...
    public static ResponseCookie cookie(String id) {
        return ResponseCookie.from(COOKIE, id).httpOnly(true).sameSite("Lax").maxAge(LIFETIME)
                .path("/register").build();
    }

    // ... y se borra estableciéndola de nuevo, vacía, con una duración cero
    public static ResponseCookie clearedCookie() {
        return ResponseCookie.from(COOKIE, "").maxAge(0).path("/register").build();
    }

    private void purge() {
        Instant now = Instant.now();
        passes.values().removeIf(expires -> !expires.isAfter(now));
        if (passes.size() >= MAX_PASSES) {
            passes.clear();
        }
    }
}

Se puede crear una cuenta de cliente desde la página de inicio de sesión, siempre que se haya resuelto el CAPTCHA. El formulario de registro se muestra y se envía mediante solicitudes posteriores: estas solicitudes deben saber que una solicitud previa resolvió correctamente el CAPTCHA. Este es el papel del token, emitido y verificado por [RegistrationController] (vea “La capa web: controladores”):

  • línea 36: el nombre de la cookie que transporta el token;
  • líneas 38–42: un token es válido durante quince minutos; los tokens pendientes se mantienen en memoria, como los CAPTCHA, con el mismo límite de tiempo;
  • líneas 45–50: un pase es un identificador aleatorio, almacenado junto con su fecha de expiración; el controlador lo coloca en una cookie;
  • líneas 53–56: el formulario de registro se muestra, y se acepta, solo con un token válido. La verificación no consume el token ([get], no [remove]): el usuario puede reenviar el formulario varias veces si cometió errores de ingreso;
  • líneas 59–63: la creación de una cuenta consume el pase: resolver un CAPTCHA da derecho a una cuenta, y nada más;
  • líneas 66–74: la cookie y su eliminación. [path("/register")] restringe el envío de la cookie a las solicitudes de URL que comienzan con [/register]: las demás solicitudes no la llevan innecesariamente. La cookie eliminada debe tener la misma ruta;
  • líneas 76–82: limpieza, idéntica a la del CAPTCHA.

11.13.10. controllers/AuthController.java

El controlador de la página de inicio de sesión se muestra en dos fragmentos.

// =========================================================================
// controllers/AuthController.java
// -------------------------------------------------------------------------
// Las rutas NO protegidas del inicio de sesión:
//   GET  /        redirige a la página de inicio del rol (o a /login)
//   GET  /login   muestra el formulario de inicio de sesión (con su captcha)
//   POST /login   verifica el límite de intentos, el captcha, login / contraseña
// (POST /logout, el cierre de sesión, lo maneja el propio Spring Security,
// véase config/SecurityConfig.java)
//
// Protección contra robots, en este orden:
//   1. ¿demasiados fallos recientes para este login desde esta dirección IP?
//      -> rechazo inmediato, sin siquiera mirar la contraseña;
//   2. ¿respuesta incorrecta al captcha? -> rechazo (contado como un fallo);
//   3. solo entonces, verificación de la contraseña.
// NUNCA verificamos la contraseña de un intento rechazado en los pasos
// 1 o 2: un robot no puede, por tanto, aprender nada insistiendo.
// =========================================================================
package rdvmedecins.controllers;

import java.util.Map;
import java.util.Optional;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.User;
import rdvmedecins.models.ViewModels.LoginModel;
import rdvmedecins.models.ViewModels.Message;

@Controller
public class AuthController {

    private final AuthService authService;
    private final CaptchaService captchaService;
    private final AttemptLimiterService limiter;

    public AuthController(AuthService authService, CaptchaService captchaService, AttemptLimiterService limiter) {
        this.authService = authService;
        this.captchaService = captchaService;
        this.limiter = limiter;
    }

    // la página de inicio de cada rol, justo después del inicio de sesión
    public static String homePage(Role role) {
        return role == Role.USER ? "/my-area" : "/schedule";
    }

    // -----------------------------------------------------------------------
    // GET /
    // La ruta es pública (véase SecurityConfig): Spring Security puede haber
    // establecido al usuario si la cookie contiene un token válido, pero
    // no exige nada. AuthService.currentUser() indica si hay uno (o null).
    // -----------------------------------------------------------------------
    @GetMapping("/")
    public String home(HttpServletRequest request) {
        ConnectedUser user = authService.currentUser(request);
        return "redirect:" + (user != null ? homePage(user.role()) : "/login");
    }

    // -----------------------------------------------------------------------
    // GET /login[?login=xxx]: el parámetro opcional rellena previamente el
    // campo login (se usa justo después de la creación de una cuenta, véase RegistrationController)
    // -----------------------------------------------------------------------
    @GetMapping("/login")
    public String showLogin(@RequestParam(required = false) String login, HttpServletRequest request,
            Model model) {
        // ya con sesión iniciada (token todavía válido): directo a la página de inicio
        ConnectedUser user = authService.currentUser(request);
        if (user != null) {
            return "redirect:" + homePage(user.role());
        }
        String input = login == null ? "" : login.substring(0, Math.min(login.length(), 30));
        return form(model, input, null);
    }

    // -----------------------------------------------------------------------
    // POST /login
    // Los parámetros de la acción se llenan con los campos del formulario
    // del mismo nombre. required = false: un campo ausente da null (y no un
    // error 400) - es el código el que decide qué hacer con él.
    // -----------------------------------------------------------------------

Comentemos este código:

  • líneas 11–17: el orden en que se realizan las verificaciones de inicio de sesión importa. La contraseña de un intento rechazado por un bloqueo o por un CAPTCHA incorrecto nunca se verifica: un bot persistente no aprende nada;
  • líneas 41–52: [@Controller] convierte la clase en un controlador cuyas acciones devuelven nombres de vistas (vea el Ejemplo 13). Recibe los tres servicios que necesita mediante su constructor. Sin anotaciones [@PreAuthorize]: sus páginas son públicas (vea [SecurityConfig]);
  • líneas 55–57: la página de inicio depende del rol: “Mi área” para un paciente, el calendario para los demás. El método es estático: no depende de ningún campo del objeto;
  • líneas 65–69: la raíz del sitio redirige (prefijo [redirect:], vea el Ejemplo 04) a la página de inicio del rol o a la página de inicio de sesión. La ruta es pública, pero el filtro del servidor de recursos se ejecuta para todas las solicitudes: si la cookie contiene un token válido, el usuario está autenticado, incluso aquí; [authService.currentUser] devuelve el usuario, o devuelve [null];
  • líneas 75–85: un usuario que ya inició sesión es redirigido a su página de inicio. El parámetro opcional [login], derivado de la URL ([@RequestParam(required = false)], vea el Ejemplo 07), rellena previamente el campo después de crear una cuenta. [substring] conserva como máximo los primeros treinta caracteres: los datos de la solicitud nunca se usan sin tomar precauciones.
    @PostMapping("/login")
    public String logIn(
            @RequestParam(required = false) String login,
            @RequestParam(required = false) String password,
            @RequestParam(required = false) String captchaId,
            @RequestParam(required = false) String captcha,
            HttpServletRequest request, HttpServletResponse response, Model model) {
        login = login == null ? "" : login.trim();
        password = password == null ? "" : password;
        String ip = ipAddress(request);

        // 1. ¿demasiados fallos recientes?
        long minutes = limiter.loginBlockMinutes(ip, login);
        if (minutes > 0) {
            return form(model, login,
                    new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes))));
        }

        // 2. el captcha
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, login);
            return form(model, login, Message.of("ERRORS.WRONG_CAPTCHA"));
        }

        // 3. la contraseña
        Optional<User> user = login.isEmpty() || password.isEmpty()
                ? Optional.empty()
                : authService.validateUser(login, password);
        if (user.isEmpty()) {
            limiter.loginFailure(ip, login);
            return form(model, login, Message.of("LOGIN.ERROR"));
        }

        limiter.loginSuccess(ip, login);
        authService.setToken(response, user.get());
        return "redirect:" + homePage(user.get().getRole());
    }

    // la dirección IP del visitante. Detrás de un proxy inverso (nginx...), habría
    // que habilitar server.forward-headers-strategy=native para obtener
    // la del visitante y no la del proxy.
    public static String ipAddress(HttpServletRequest request) {
        return request.getRemoteAddr();
    }

    // el formulario, siempre con un captcha NUEVO (cada imagen se usa
    // una sola vez); mostramos de nuevo el login digitado, nunca la contraseña
    private String form(Model model, String login, Message error) {
        model.addAttribute("model", new LoginModel("LOGIN.TITLE", error, login, captchaService.generate()));
        return "login";
    }
}

Analicemos este código:

  • líneas 2–7: los campos del formulario de inicio de sesión (vea el Ejemplo 11), incluidos el ID del CAPTCHA, transmitido mediante un campo oculto, y la entrada del usuario. Todos son opcionales ([required = false]): un campo ausente da como resultado [null] en lugar de un error 400, y le corresponde a la acción decidir qué hacer con él. La acción también recibe la solicitud (para la dirección IP y el CAPTCHA), la respuesta (para almacenar allí la cookie del token) y el modelo de la vista;
  • líneas 8–9: un nombre de usuario ausente se convierte en una cadena vacía sin espacios; una contraseña ausente se convierte en una cadena vacía;
  • líneas 13–17: 1. Un par bloqueado ni siquiera se procesa: no se verifica ni el CAPTCHA ni la contraseña. El error es un mensaje que debe traducirse (record [Message], archivo [models]): una clave de traducción y un parámetro: el número de minutos que hay que esperar. [Map.of] crea un diccionario de solo lectura;
  • líneas 20–23: 2. el CAPTCHA. Un CAPTCHA incorrecto cuenta como un fallo (vea el ejemplo 27);
  • líneas 26–32: 3. Solo entonces, la contraseña. Un nombre de usuario o una contraseña vacíos no se someten al cálculo costoso de [bcrypt]: se usa directamente una caja vacía ([Optional.empty()]). Nombre de usuario desconocido o contraseña incorrecta: el mismo mensaje, intencionalmente vago (vea el ejemplo 25), y un fallo más;
  • líneas 34–36: éxito: contador restablecido a cero, token almacenado en la cookie, redirección a la página de inicio del rol. [user.get()] recupera la cuenta de su caja, que sabemos que no está vacía;
  • líneas 42–44: la dirección IP del cliente, proporcionada por la conexión de red. El método es público y estático: [RegistrationController] y [PatientAreaController] también lo usan para el limitador de frecuencia. Detrás de un servidor intermediario (un proxy inverso como [nginx]), esta dirección sería la del proxy: el comentario indica que en ese caso debe habilitarse la propiedad de [Spring Boot];
  • Líneas 48–51: la página de inicio de sesión, que siempre muestra un nuevo CAPTCHA: cada imagen se usa una sola vez. Su modelo, el record [LoginModel] (carpeta [models]), contiene la clave de traducción del título de la página, los posibles mensajes de error, el nombre de usuario ingresado (nunca la contraseña) y el CAPTCHA. Se almacena en el modelo con el nombre [model], el nombre que usan todas las vistas de la aplicación. La vista es [login] (archivo [templates/login.html]).

El manejo de un intento con un CAPTCHA incorrecto puede verse en [curl]: se devuelve la página de inicio de sesión (código de estado 200), con el nombre de usuario ingresado, una imagen nueva y el mensaje de error al final de la página:

curl -i -X POST -d "login=admin&password=admin&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
1
2
3
4
5
6
7
8
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
...
                 value="admin" required>
...
  <div class="error-zone" role="alert">
    <div>The characters you typed do not match the image. A new image is shown.</div>
...

La respuesta no menciona la contraseña, que no se verificó. En cambio, un inicio de sesión exitoso no se puede mostrar con [curl], ya que hay que leer la imagen; es visible en el navegador (vea “Uso de la aplicación”): la respuesta al POST es una redirección (302) a la página de inicio del rol, con el encabezado [Set-Cookie] que establece el token.

11.14. La capa web: servicios compartidos

Antes de llegar a los controladores y las vistas, veamos lo que tienen en común: la traducción, los atributos compartidos por todas las vistas, los mensajes flash, el manejo de excepciones, el almacenamiento en caché de las listas de médicos y clientes, la preparación de formularios para volver a mostrarlos y algunas funciones de utilidad. Todos estos archivos están en la carpeta [web]. Esta reúne la mayoría de las técnicas de los Ejemplos 15 a 24.

11.14.1. web/Translator.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// web/Translator.java
// -------------------------------------------------------------------------
// Traducción francés / inglés de la interfaz (véase el ejemplo 22).
//
// Los diccionarios son los MISMOS archivos que los de las versiones NestJS y
// ASP.NET Core de la aplicación (i18n/fr.json, i18n/en.json), leídos una sola
// vez al arrancar.
//
// El bean se llama [messageSource] e implementa la interfaz MessageSource
// de Spring: es, por tanto, el que usa Thymeleaf para las expresiones
// #{KEY} de las vistas. Los parámetros de un texto ({name}, {minutes}...) se
// pasan de dos maneras:
//   #{AREA.HELLO('name', ${patient})}           por pares (nombre, valor);
//   #{${message.key}(${message.params})}        por un diccionario (Map).
//
// EL IDIOMA ACTUAL: lo determina el LocaleResolver (véase config/WebConfig.java)
// en cada solicitud, a partir de una cookie. Spring lo almacena en
// LocaleContextHolder y se lo pasa a Thymeleaf.
// =========================================================================
package rdvmedecins.web;

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;

@Component("messageSource")
public class Translator implements MessageSource {

    public static final List<String> LANGUAGES = List.of("fr", "en");
    public static final String DEFAULT_LANGUAGE = "en";

    // {name}: un parámetro en un texto
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // idioma -> (clave completa "LOGIN.TITLE" -> texto)
    private final Map<String, Map<String, String>> dictionaries = new HashMap<>();

    public Translator() throws IOException {
        ObjectMapper json = new ObjectMapper();
        for (String language : LANGUAGES) {
            try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
                Map<String, String> dictionary = new HashMap<>();
                flatten(json.readTree(stream), "", dictionary);
                dictionaries.put(language, dictionary);
            }
        }
    }

    // el idioma admitido que corresponde a [locale]: "fr_FR" -> "fr" ; "de" -> "en"
    public static String language(Locale locale) {
        String language = locale == null ? "" : locale.getLanguage();
        return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
    }

    // -----------------------------------------------------------------------
    // translate("DOCTORS.ADDED", { name: "Marie PELISSIER" }, en)
    //   -> busca "DOCTORS.ADDED" en el diccionario del idioma y
    //      reemplaza {name} por su valor. Una clave ausente del idioma solicitado
    //      se busca en inglés; si falta en todas partes, mostramos la clave
    //      misma (así una omisión se detecta de inmediato).
    // -----------------------------------------------------------------------
    public String translate(String key, Map<String, String> params, Locale locale) {
        if (key == null || key.isEmpty()) {
            return "";
        }
        String text = dictionaries.get(language(locale)).get(key);
        if (text == null) {
            text = dictionaries.get(DEFAULT_LANGUAGE).getOrDefault(key, key);
        }
        if (params == null || params.isEmpty()) {
            return text;
        }
        Matcher m = PARAMETER.matcher(text);
        return m.replaceAll(r -> Matcher.quoteReplacement(params.getOrDefault(r.group(1), r.group())));
    }

Este es el servicio de traducción del Ejemplo 22. Los diccionarios [i18n/fr.json] y [i18n/en.json] son los mismos archivos que los de la versión [ASP.NET Core], que se leen una sola vez al inicio (vea “Diccionarios”). Comentemos este código:

  • líneas 40–41: la clase implementa la interfaz [MessageSource] de [Spring], que es la interfaz de los servicios que proporcionan texto, y el bean se llama [messageSource] (el argumento de [@Component]). Con este nombre [Spring] busca el [MessageSource] de la aplicación: nuestro bean reemplaza por lo tanto al que [Spring Boot] habría configurado, y es este bean el que [Thymeleaf] consulta para cada expresión [#{KEY}] de las vistas (vea el Ejemplo 22);
  • líneas 43–44: los idiomas admitidos y el idioma predeterminado. [List.of] crea una lista de solo lectura;
  • línea 47: una expresión regular que reconoce un parámetro en el texto: [{], uno o más caracteres de palabra ([\w+], capturados por paréntesis), [}]. En una cadena [Java], la barra invertida se escribe como [\\]. El patrón se compila una vez ([Pattern.compile]) y luego se reutiliza;
  • línea 50: para cada idioma, un diccionario “clave completa → texto”. El bean es un singleton usado por solicitudes concurrentes; sin embargo, un simple [HashMap] es suficiente, ya que los diccionarios, llenados por el constructor, posteriormente solo se leen;
  • Líneas 52–61: el constructor lee los dos archivos JSON. [ClassPathResource] hace referencia a un archivo en el “classpath”, el conjunto de carpetas y archivos comprimidos donde la máquina virtual busca las clases: la carpeta [src/main/resources] se copia allí durante la compilación. [ObjectMapper] es la herramienta para leer y escribir JSON de la biblioteca [Jackson] (versión 3, de ahí el paquete [tools.jackson]). [readTree] devuelve el árbol del documento a partir de JSON, que el método [flatten] convierte en un diccionario. La construcción [try (...)] cierra el flujo al final del bloque, incluso si se produce una excepción. Si falta un archivo, la excepción [IOException], declarada mediante [throws], impide que la aplicación se inicie;
  • Líneas 64–67: el idioma admitido correspondiente a [Locale], el objeto de [Java] que describe un idioma y, opcionalmente, un país: [en_US] da como resultado [en]; un idioma no admitido da como resultado [en];
  • líneas 76–89: la traducción. Si falta una clave en el diccionario del idioma solicitado, se busca en el diccionario en inglés; si falta en todas partes, se devuelve la propia clave ([getOrDefault(key, key)]): una omisión es inmediatamente visible en la pantalla. Los parámetros del texto [{name}] se reemplazan entonces por sus valores (línea 88): [replaceAll] llama a la función lambda por cada parámetro encontrado; [r.group(1)] es el nombre capturado entre las llaves, [r.group()] es todo el texto encontrado, y [{name}] se deja tal cual si no se proporciona ningún valor. [Matcher.quoteReplacement] escapa los caracteres [$] y [\], que de otro modo tendrían un significado específico para [replaceAll].
    // los parámetros pasados por Thymeleaf (o por Spring): un único
    // diccionario, o pares (nombre, valor)
    @SuppressWarnings("unchecked")
    private static Map<String, String> params(Object[] args) {
        Map<String, String> params = new HashMap<>();
        if (args == null || args.length == 0) {
            return params;
        }
        if (args.length == 1 && args[0] instanceof Map<?, ?> dictionary) {
            dictionary.forEach((name, value) -> params.put(String.valueOf(name), String.valueOf(value)));
            return params;
        }
        for (int i = 0; i + 1 < args.length; i += 2) {
            params.put(String.valueOf(args[i]), String.valueOf(args[i + 1]));
        }
        return params;
    }

    // { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
    private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
        for (Map.Entry<String, JsonNode> property : node.properties()) {
            String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
            if (property.getValue().isObject()) {
                flatten(property.getValue(), key, result);
            } else {
                result.put(key, property.getValue().asString());
            }
        }
    }

    // la interfaz MessageSource

    @Override
    public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
        return translate(code, params(args), locale);
    }

    @Override
    public String getMessage(String code, Object[] args, Locale locale) {
        return translate(code, params(args), locale);
    }

    // un mensaje descrito por varios códigos posibles (un error de
    // validación, por ejemplo): gana el primer código presente en el diccionario;
    // de lo contrario, el mensaje por defecto, que es a su vez una clave
    @Override
    public String getMessage(MessageSourceResolvable message, Locale locale) {
        Map<String, String> dictionary = dictionaries.get(language(locale));
        String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
        for (String code : codes) {
            if (dictionary.containsKey(code)) {
                return translate(code, params(message.getArguments()), locale);
            }
        }
        return translate(message.getDefaultMessage(), Map.of(), locale);
    }
}

Analicemos este código:

  • Líneas 5–18: los parámetros de un mensaje se pasan como un arreglo de objetos ([Object[]]) de una de dos maneras posibles. Una vista que escribe [#{AREA.HELLO('name', ${patient})}] pasa pares (nombre, valor) (líneas 14–16). Una vista que muestra un mensaje flash o un error escribe [#{${message.key}(${message.params})}]: pasa un único argumento, el diccionario de parámetros (líneas 10–13). [instanceof Map<?, ?> dictionary] verifica el tipo y almacena el objeto convertido en la variable [dictionary]; [<?, ?>] significa «claves y valores de cualquier tipo». [String.valueOf] convierte cualquier objeto en texto;
  • líneas 21–30: aplanamiento de JSON: [{ "LOGIN": { "TITLE": "Login" } }] se convierte en [{ "LOGIN.TITLE": "Login" }]. El método es recursivo: se llama a sí mismo para cada objeto anidado, ampliando el prefijo de la clave;
  • líneas 34–42: los dos métodos principales de la interfaz [MessageSource]: un código (la clave), sus argumentos y el idioma. [@Override] indica al compilador que verifique que el método efectivamente redefine un método de la interfaz. El mensaje predeterminado que proporciona el primer método se ignora: una clave ausente se muestra tal cual;
  • líneas 47–57: el tercer método recibe un mensaje descrito por varios códigos posibles, como los que genera [Spring] para un error de validación o de conversión ([typeMismatch.version], [typeMismatch]...). El primer código encontrado en el diccionario tiene prioridad; de lo contrario, se traduce el mensaje predeterminado. En esta aplicación, los mensajes de las restricciones de validación son claves de traducción (véase [models/Forms.java]): el mensaje predeterminado es, por lo tanto, en sí mismo una clave.

El idioma de la solicitud no aparece en ninguna parte de los controladores: es el [LocaleResolver] (bean [localeResolver] de [config/WebConfig.java], véase «Configuración del proyecto») quien lo lee de la cookie [rdvmedecins_language] al comienzo de cada solicitud; [Spring] se lo pasa luego a [Thymeleaf], que se lo pasa a [getMessage].

11.14.2. web/CommonModel.java

// =========================================================================
// web/CommonModel.java
// -------------------------------------------------------------------------
// Lo que NECESITAN TODAS las vistas, sea cual sea la página (véase el ejemplo
// 15): @ControllerAdvice convierte esta clase en un complemento de todos los
// controladores, y cada método @ModelAttribute, ejecutado antes de cada
// acción, añade un atributo al modelo de la vista:
//   - user     : el usuario conectado (o null), para la barra de navegación;
//   - language : "fr" o "en";
//   - path     : la URL solicitada (menú activo de la barra de navegación,
//                enlace "Another image" del captcha).
// El mensaje flash lo añade al modelo el propio Spring MVC,
// con el nombre [flash] (véase CookieFlashMapManager.java).
// =========================================================================
package rdvmedecins.web;

import java.util.Locale;

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ModelAttribute;

import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;

@ControllerAdvice
public class CommonModel {

    private final AuthService authService;

    public CommonModel(AuthService authService) {
        this.authService = authService;
    }

    @ModelAttribute("user")
    public ConnectedUser user(HttpServletRequest request) {
        return authService.currentUser(request);
    }

    // Locale: el idioma de la solicitud, proporcionado por Spring (véase config/WebConfig.java)
    @ModelAttribute("language")
    public String language(Locale locale) {
        return Translator.language(locale);
    }

    @ModelAttribute("path")
    public String path(HttpServletRequest request) {
        return request.getRequestURI();
    }
}

Todas las páginas muestran la misma barra de navegación: el nombre del usuario conectado, sus menús según el rol, el menú seleccionado resaltado y los botones FR / EN. Por lo tanto, el modelo de cada vista debe contener el usuario, el idioma y la URL solicitada. En lugar de agregarlos en cada acción, los agregamos de una vez por todas, como en el Ejemplo 15:

  • línea 26: [@ControllerAdvice] convierte la clase en un componente de todos los controladores (véanse los Ejemplos 15 y 24);
  • Líneas 35–38: un método llamado [@ModelAttribute("user")] se ejecuta antes de cada acción, y el valor que devuelve se agrega al modelo con el nombre especificado. Aquí, el usuario conectado, o [null], obtenido mediante [AuthService.currentUser] (véase [auth/AuthService.java]): la barra de navegación muestra [${user.name}], [${user.isAdmin()}]... Al igual que las acciones, estos métodos reciben los parámetros que necesitan; en este caso, la solicitud;
  • líneas 41–44: el idioma actual ([fr] o [en]), para el atributo [lang] de la página y los botones FR / EN. Un parámetro de tipo [Locale] recibe el idioma de la solicitud, establecido por [LocaleResolver];
  • líneas 47–49: la ruta de la URL solicitada, por ejemplo [/my-area]: la barra de navegación resalta el menú cuya ruta comienza así (véase el Ejemplo 16), y el enlace «Another image» del CAPTCHA recarga la página actual.

El mensaje flash, el cuarto dato común, no requiere un método: [Spring MVC] lo agrega por sí mismo al modelo (véase [CookieFlashMapManager.java], más adelante). En [ASP.NET Core MVC], estos datos consistían en propiedades de una clase padre compartida por todas las vistas; [Thymeleaf] no tiene una clase padre para las vistas y, en cambio, el modelo de cada vista recibe estos datos.

11.14.3. web/FlashType.java

1
2
3
4
5
6
7
8
9
// =========================================================================
// web/FlashType.java - los dos tipos de mensajes flash (véase Flash.java)
// =========================================================================
package rdvmedecins.web;

public enum FlashType {
    SUCCESS, // clase Bootstrap alert-success: en la parte superior de la página
    DANGER // un error: en la parte inferior de la página (véase templates/fragments/errors.html)
}
  • líneas 6–9: los dos tipos de mensajes flash, en forma de enumeración: un tipo cuyos valores posibles se fijan de una vez por todas. Un mensaje de éxito se muestra en la parte superior de la página (fragmento [templates/fragments/flash.html]) y un mensaje de error en la parte inferior (fragmento [templates/fragments/errors.html]; véase «Vistas»).

11.14.4. web/FlashMessage.java

// =========================================================================
// web/FlashMessage.java
// -------------------------------------------------------------------------
// Un mensaje "flash": un mensaje que se muestra UNA SOLA VEZ, en la página SIGUIENTE
// (véase el ejemplo 20). key: clave de traducción; params: sus parámetros
// ({name}, {login}...).
// =========================================================================
package rdvmedecins.web;

import java.util.Map;

public record FlashMessage(FlashType type, String key, Map<String, String> params) {

    // el nombre del atributo flash, en el modelo de las vistas
    public static final String ATTRIBUTE = "flash";

    public static FlashMessage success(String key) {
        return new FlashMessage(FlashType.SUCCESS, key, Map.of());
    }

    public static FlashMessage success(String key, Map<String, String> params) {
        return new FlashMessage(FlashType.SUCCESS, key, params);
    }

    public static FlashMessage error(String key) {
        return new FlashMessage(FlashType.DANGER, key, Map.of());
    }

    public static FlashMessage error(String key, Map<String, String> params) {
        return new FlashMessage(FlashType.DANGER, key, params);
    }

    public boolean successful() {
        return type == FlashType.SUCCESS;
    }
}
  • línea 12: un mensaje flash (véase el Ejemplo 20) consta de un tipo, una clave de traducción y sus parámetros —no de texto ya traducido— y la página siguiente lo traducirá al idioma de esa página;
  • línea 15: el nombre con el que se pasa el mensaje y con el que las vistas lo encuentran en su modelo: [flash]. Un controlador escribe, por ejemplo, [redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"))];
  • líneas 17–31: cuatro métodos estáticos que crean un mensaje, con o sin parámetros. Los métodos con el mismo nombre pero con parámetros distintos son sobrecargas: el compilador selecciona la correcta según los argumentos. [Map.of()] es un diccionario vacío;
  • líneas 33–35: una prueba para las vistas: [${flash.successful()}].

11.14.5. web/CookieFlashMapManager.java

// =========================================================================
// web/CookieFlashMapManager.java
// -------------------------------------------------------------------------
// Los mensajes "flash": un mensaje que se muestra UNA SOLA VEZ, en la página
// SIGUIENTE. Es el complemento natural del patrón "Post / Redirect / Get"
// usado por todos los formularios de la aplicación: un POST exitoso no
// construye una página, sino que redirige (302) a una página GET; el mensaje
// debe sobrevivir a la redirección.
//
// Spring MVC lo ofrece de serie: un controlador coloca un atributo flash
// (RedirectAttributes.addFlashAttribute, véase el ejemplo 20), que termina
// en el modelo de la solicitud SIGUIENTE y luego desaparece. Por defecto, Spring
// lo guarda en la SESIÓN HTTP (SessionFlashMapManager). Pero nuestro
// servidor NO MANTIENE ESTADO: no conserva nada entre dos solicitudes (el token
// JWT está en una cookie). Por eso reemplazamos el "administrador de atributos
// flash" (FlashMapManager) de Spring por el nuestro, que los almacena en una
// COOKIE - es el bean [flashMapManager] de config/WebConfig.java.
//
// AbstractFlashMapManager hace la mayor parte del trabajo (a qué solicitud
// está destinado el mensaje, expiración...): solo queda leer y escribir la
// lista de atributos flash. Conservamos uno solo, como texto JSON
// codificado en base64 (una cookie no puede contener cualquier carácter).
//
// La cookie no está cifrada ni firmada: contiene solo una
// CLAVE de traducción y sus parámetros, mostrados con escape. Un usuario que
// la modificara solo cambiaría el mensaje que él mismo ve.
// =========================================================================
package rdvmedecins.web;

import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;

import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.support.AbstractFlashMapManager;
import org.springframework.web.util.WebUtils;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import tools.jackson.databind.ObjectMapper;

public class CookieFlashMapManager extends AbstractFlashMapManager {

    public static final String COOKIE = "rdvmedecins_flash";

    // lo que contiene la cookie: la página a la que está destinado el mensaje, la
    // fecha de expiración (en milisegundos), el mensaje
    private record CookieContent(String path, long expires, FlashMessage flash) {
    }

    private final ObjectMapper json = new ObjectMapper();

    // los atributos flash de la solicitud anterior (null: ninguno)
    @Override
    protected List<FlashMap> retrieveFlashMaps(HttpServletRequest request) {
        Cookie cookie = WebUtils.getCookie(request, COOKIE);
        if (cookie == null) {
            return null;
        }
        try {
            byte[] bytes = Base64.getUrlDecoder().decode(cookie.getValue());
            CookieContent content = json.readValue(bytes, CookieContent.class);
            FlashMap flashMap = new FlashMap();
            flashMap.put(FlashMessage.ATTRIBUTE, content.flash());
            flashMap.setTargetRequestPath(content.path());
            flashMap.setExpirationTime(content.expires());
            // una lista MODIFICABLE: Spring elimina por sí mismo los mensajes consumidos
            // de ella (List.of(...) daría una lista inmodificable)
            return new ArrayList<>(List.of(flashMap));
        } catch (RuntimeException e) {
            return null; // cookie ilegible: la ignoramos
        }
    }

    // la lista a conservar para las siguientes solicitudes: vacía -> borramos la cookie
    @Override
    protected void updateFlashMaps(List<FlashMap> flashMaps, HttpServletRequest request,
            HttpServletResponse response) {
        ResponseCookie cookie;
        if (flashMaps.isEmpty() || !(flashMaps.getLast().get(FlashMessage.ATTRIBUTE) instanceof FlashMessage flash)) {
            cookie = ResponseCookie.from(COOKIE, "").path("/").maxAge(0).build();
        } else {
            FlashMap last = flashMaps.getLast();
            CookieContent content = new CookieContent(last.getTargetRequestPath(), last.getExpirationTime(), flash);
            String value = Base64.getUrlEncoder().withoutPadding()
                    .encodeToString(json.writeValueAsString(content).getBytes(StandardCharsets.UTF_8));
            cookie = ResponseCookie.from(COOKIE, value).path("/").httpOnly(true).sameSite("Lax").build();
        }
        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    }
}

En el Ejemplo 20, los atributos flash de [Spring MVC] se conservaban entre la redirección y la página siguiente en la sesión HTTP: un espacio de memoria del servidor propio de cada navegador, identificado por la cookie [JSESSIONID]. Sin embargo, nuestro servidor no tiene estado: no conserva nada en memoria entre solicitudes, ya que el usuario se identifica mediante su token. Por lo tanto, esta clase almacena los atributos flash en una cookie, tal como lo hacía [TempData] en la versión [ASP.NET Core]. Comentemos este código:

  • línea 46: [Spring MVC] delega el almacenamiento de los atributos flash en un bean de tipo [FlashMapManager]. [AbstractFlashMapManager] hace la mayor parte del trabajo: sabe para qué solicitud está destinado un atributo flash, cuándo expira y cuándo ha sido consumido. Una clase derivada solo necesita implementar dos métodos: leer la lista de atributos flash pendientes (líneas 58–77) y guardarla (líneas 80–94). El bean [flashMapManager] de [config/WebConfig.java] crea un objeto de esta clase; lleva el nombre con el que [Spring MVC] busca este manejador y, por lo tanto, reemplaza al de [Spring MVC];
  • líneas 52–53: el contenido de la cookie: la ruta de la página a la que está destinado el mensaje, su fecha de expiración (en milisegundos) y el mensaje;
  • línea 55: [Jackson] convierte un objeto en texto JSON y viceversa, incluido un record;
  • líneas 58–77: el proceso de análisis, que se invoca al comienzo de cada solicitud. La cookie se decodifica (base64 y luego JSON) y el mensaje se coloca de nuevo en un objeto [FlashMap] (un diccionario de atributos flash, con su ruta de destino y su fecha de expiración), el único de la lista. La lista devuelta debe ser modificable (líneas 71–73): [Spring MVC] elimina el mensaje de la lista por sí mismo cuando lo consume. Una cookie ilegible (modificada manualmente, por ejemplo) no debe provocar el fallo de la página: la excepción se captura y la cookie se ignora;
  • Líneas 80–94: la función que se invoca cuando la lista ha cambiado: un mensaje se ha publicado, consumido o ha expirado. Una lista vacía borra la cookie; de lo contrario, el último mensaje publicado se escribe en la cookie. La expresión [instanceof FlashMessage flash], colocada en la condición, verifica el tipo del atributo y lo almacena en la variable [flash], que se utiliza en la línea 88. El texto JSON se codifica en Base64 ([Base64.getUrlEncoder()], una variante sin los caracteres [+] y [/]) porque una cookie no puede contener cualquier carácter; las comillas y los acentos de JSON no están permitidos. La cookie no tiene tiempo de expiración ([Max-Age]): es una cookie de sesión del navegador, y lo que importa es el tiempo de expiración del contenido (tres minutos de forma predeterminada);
  • Líneas 24–26: la cookie no está cifrada ni firmada, a diferencia de la cookie de [TempData] y [ASP.NET Core]. Esto es innecesario: contiene solo una clave de traducción y sus parámetros, que las vistas muestran con escape; un usuario que la modificara solo cambiaría el mensaje que él mismo ve.

Vimos, con [SecurityConfig], que un mensaje de «sesión expirada» se almacenaba en esta cookie. Este es el contenido decodificado de la cookie utilizada en el siguiente comando (capturada durante una prueba distinta de la anterior: solo difiere la fecha de expiración):

{"path":"/login","expires":1790355130312,"flash":{"type":"DANGER","key":"ERRORS.SESSION_EXPIRED","params":{}}}

La siguiente solicitud, a [/login], consume el mensaje: la página lo muestra y la respuesta elimina la cookie.

curl -i -H "Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTEzMDMxMiwiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0" http://localhost:8081/login
1
2
3
4
5
6
7
8
9
HTTP/1.1 200
Set-Cookie: rdvmedecins_flash=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html;charset=UTF-8
...
  <div class="error-zone" role="alert">

    <div>Your session has expired: please log in again.</div>
  </div>
...

El mensaje se muestra una sola vez: cuando se recarga la página, ya no lo muestra.

11.14.6. web/Flash.java

// =========================================================================
// web/Flash.java
// -------------------------------------------------------------------------
// Colocar un mensaje flash desde CUALQUIER LUGAR, incluso fuera de
// Spring MVC: la autenticación JWT (sesión expirada, véase
// config/SecurityConfig.java) se ejecuta en un filtro de Spring Security,
// ANTES de Spring MVC - allí todavía no existe un RedirectAttributes.
// Entonces nos dirigimos directamente al FlashMapManager (CookieFlashMapManager).
// En un controlador, usamos más bien RedirectAttributes.addFlashAttribute.
// =========================================================================
package rdvmedecins.web;

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.FlashMapManager;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
public class Flash {

    private final FlashMapManager manager;

    public Flash(FlashMapManager manager) {
        this.manager = manager;
    }

    // coloca [message], destinado a la página [target] (la siguiente solicitud)
    public void put(HttpServletRequest request, HttpServletResponse response, FlashMessage message, String target) {
        FlashMap flashMap = new FlashMap();
        flashMap.put(FlashMessage.ATTRIBUTE, message);
        flashMap.setTargetRequestPath(target);
        manager.saveOutputFlashMap(flashMap, request, response);
    }
}

En un controlador, un mensaje flash se muestra con [RedirectAttributes.addFlashAttribute] (véase el Ejemplo 20). En cambio, el punto de entrada de [SecurityConfig]se ejecuta en un filtro de [Spring Security], antes de que [Spring MVC] haya tomado el control de la solicitud:

  • línea 20: [@Component] convierte la clase en un bean, que [SecurityConfig] recibe como parámetro;
  • líneas 25–27: el bean recibe el manejador de atributos flash, es decir, nuestro [CookieFlashMapManager];
  • líneas 30–35: creamos nosotros mismos el [FlashMap] —que normalmente [Spring MVC] crea—, con el mensaje y la ruta de la página que debe recibirlo ([/login]). [saveOutputFlashMap] se lo pasa al manejador, que escribe la cookie en la respuesta.

11.14.7. web/HtmlExceptionHandler.java

// =========================================================================
// web/HtmlExceptionHandler.java
// -------------------------------------------------------------------------
// Cómo los errores se convierten en páginas HTML. Tres mecanismos
// se reparten el trabajo (véase el ejemplo 24):
//
//   1. esta clase: una InvalidSessionException (cuenta eliminada desde
//      el inicio de sesión) -> de vuelta a la página de inicio de sesión;
//   2. una respuesta de error 400, 403 o 404 (ResponseStatusException lanzada
//      por un controlador, rol insuficiente, página desconocida...) la pasa
//      el servidor a la dirección /error: ErrorController la convierte en una página;
//   3. cualquier otra excepción (una anomalía real) se escribe en el
//      registro del servidor y luego también se pasa a /error: el usuario
//      ve la página de error 500 - nunca el seguimiento de la pila.
// =========================================================================
package rdvmedecins.web;

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.support.RequestContextUtils;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.InvalidSessionException;

@ControllerAdvice
public class HtmlExceptionHandler {

    @ExceptionHandler(InvalidSessionException.class)
    public String invalidSession(HttpServletRequest request, HttpServletResponse response) {
        AuthService.clearToken(response);
        // el atributo flash de la redirección que sigue (el equivalente de
        // RedirectAttributes.addFlashAttribute, para un método @ExceptionHandler)
        RequestContextUtils.getOutputFlashMap(request)
                .put(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.SESSION_EXPIRED"));
        return "redirect:/login";
    }
    // las demás excepciones no se manejan aquí: se propagan
    // hasta el servidor, que las pasa a /error (página 500)
}

El comentario de encabezado (líneas 4–14) describe los tres mecanismos que convierten los errores en páginas HTML (véase el Ejemplo 24). Dos de ellos no requieren código: una respuesta de error ([sendError(403)], una [ResponseStatusException] lanzada por un controlador, una URL desconocida) la envía el servidor a la dirección [/error], donde [ErrorController] genera la página; una excepción no controlada se registra en el log del servidor, junto con su pila de llamadas, y luego también se reenvía a [/error], que muestra la página de error 500. El usuario nunca ve la pila de llamadas, que ayudaría a un atacante (propiedad [spring.web.error.include-stacktrace=never]; véase «Configuración del proyecto»). Queda un caso especial, que se aborda aquí:

  • línea 27: [@ControllerAdvice], como con [CommonModel]: los métodos de la clase se aplican a todos los controladores;
  • líneas 30–31: un método [@ExceptionHandler] se invoca cuando una acción lanza la excepción especificada (véase el Ejemplo 24). Puede recibir la solicitud y la respuesta, y devolver el nombre de una vista o una redirección, igual que una acción;
  • líneas 32–37: la cuenta del usuario conectado se ha eliminado desde que inició sesión, aunque su token siga siendo válido (véase [auth/InvalidSessionException.java]). Borramos la cookie del token, mostramos un mensaje flash de «sesión expirada» y redirigimos a la página de inicio de sesión: al usuario se le trata como si su sesión hubiera expirado. Un método anotado con [@ExceptionHandler] no puede aceptar un parámetro de tipo [RedirectAttributes]: [RequestContextUtils.getOutputFlashMap(request)] devuelve directamente el [FlashMap] que la redirección pasará a la página siguiente.

11.14.8. web/ApplicationModel.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// web/ApplicationModel.java
// -------------------------------------------------------------------------
// El caché / fachada ya presente en el servidor JSON (equivalente de la
// clase [ApplicationModel] del proyecto Spring original): las listas de
// médicos y de clientes se leen una vez al arrancar y luego se sirven
// desde la memoria.
//
// Estas listas pueden CAMBIAR (el ADMIN agrega, edita y elimina
// médicos y clientes): por eso cada escritura pasa por esta fachada,
// que recarga la lista afectada inmediatamente después. Ese es todo el sentido de un
// ÚNICO punto de entrada a la capa de negocio: la regla "escritura =>
// recarga del caché" se escribe solo aquí.
//
// La fachada es un bean SINGLETON, como la propia capa de negocio: con
// Spring, los DAO y la capa de negocio no dependen de ninguna solicitud (es
// Spring quien asocia a cada hilo SU transacción y SU conexión). El
// caché y la fachada pueden ser, por tanto, el mismo objeto.
//
// Spring procesa las solicitudes EN PARALELO, en varios hilos. Por eso nunca
// modificamos una lista en el sitio: la REEMPLAZAMOS por completo por una
// nueva. Intercambiar una referencia es atómico; "volatile" garantiza que
// todos los hilos vean de inmediato la nueva lista.
// =========================================================================
package rdvmedecins.web;

import java.time.LocalDate;
import java.util.List;
import java.util.Objects;
import java.util.Optional;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

import jakarta.annotation.PostConstruct;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.Business;

// mismo contrato que la capa de negocio (Business)
@Service
public class ApplicationModel implements Business {

    private final Business business;

    private volatile List<Doctor> doctors = List.of();
    private volatile List<Client> clients = List.of();

    // dos beans implementan Business: BusinessService y el propio
    // ApplicationModel. @Qualifier designa el que queremos, por su nombre.
    public ApplicationModel(@Qualifier("businessService") Business business) {
        this.business = business;
    }

    // -----------------------------------------------------------------------
    // carga inicial de las dos listas. @PostConstruct: Spring llama a
    // este método una vez creado el objeto e inyectadas sus dependencias, al
    // arrancar la aplicación. Un error de lectura no se captura:
    // detiene el servidor, en lugar de dejarlo arrancar "vacío" (una base de datos
    // inaccesible lo detiene incluso antes, en cuanto arranca Hibernate).
    // -----------------------------------------------------------------------
    @PostConstruct
    public void load() {
        reloadDoctors();
        reloadClients();
    }

    private void reloadDoctors() {
        doctors = List.copyOf(business.getAllDoctors());
    }

    private void reloadClients() {
        clients = List.copyOf(business.getAllClients());
    }

    // ------------------------------------------------ lecturas desde el caché

    @Override
    public List<Doctor> getAllDoctors() {
        return doctors;
    }

    @Override
    public List<Client> getAllClients() {
        return clients;
    }

    // el médico cuya cuenta de usuario es [userId] - sirve para preseleccionar,
    // para un médico conectado, su propia agenda
    public Optional<Doctor> getDoctorByUserId(int userId) {
        return doctors.stream().filter(d -> Objects.equals(d.getUserId(), userId)).findFirst();
    }

Las listas de médicos y de clientes se muestran en casi todas las páginas (listas desplegables del calendario, páginas de administración). En lugar de obtenerlas de la base de datos en cada solicitud, las mantenemos en memoria: son datos de ámbito de aplicación (véase el Ejemplo 23). Comentemos este código:

  • Líneas 45–46: la clase es un bean singleton que implementa la interfaz [Business], que es la interfaz de la capa de negocio (véase «La capa de negocio»): para los controladores, esta clase es la capa de negocio, y es la única que reciben (por ejemplo, [public ScheduleController(ApplicationModel application)]). Es una fachada: un único punto de entrada que oculta lo que hay detrás. En [ASP.NET Core], la caché tenía que ser un servicio separado de la fachada, porque allí la capa de negocio vive solo durante una solicitud; con [Spring], la propia capa de negocio es un singleton (es [Spring] quien asocia cada [thread] con su transacción y su conexión a la base de datos): basta un único objeto (líneas 15–18);
  • línea 48: la capa de negocio propiamente dicha, [BusinessService], a la que la fachada reenvía las solicitudes;
  • líneas 50–51: la caché propiamente dicha: las dos listas, que inicialmente están vacías ([List.of()]). [Spring] procesa las solicitudes en paralelo en varias [threads] instancias. Por lo tanto, una lista compartida nunca debe modificarse mientras otra solicitud la está recorriendo. La regla elegida es simple: nunca modificar una lista; en su lugar, reemplazarla por una nueva. Reemplazar una referencia se hace en una sola operación, y la palabra clave [volatile] garantiza que todos los [threads] vean de inmediato la nueva lista; sin ella, un [thread] podría seguir leyendo un valor antiguo, almacenado en la caché de su procesador;
  • Líneas 55–57: dos beans son de tipo [Business]: [BusinessService] y [ApplicationModel] mismo. Solicitar simplemente «un [Business]» sería ambiguo, y [Spring] se negaría a iniciar. [@Qualifier("businessService")] se refiere al bean deseado por su nombre; un bean declarado con [@Service] se nombra de forma predeterminada según su clase, con la primera letra en minúscula;
  • Líneas 66–70: la carga inicial de las dos listas. [@PostConstruct] hace que [Spring] invoque el método una vez creado el objeto e inyectadas sus dependencias, durante el inicio de la aplicación, antes de que el servidor acepte cualquier solicitud. Un error de lectura no se captura: termina la aplicación, lo cual es preferible a que un servidor arranque con listas vacías (una base de datos inaccesible, por cierto, termina la aplicación aún antes, desde que [Hibernate] se inicia; véase «Instalación y ejecución»);
  • líneas 72–78: recarga de una lista: la lista completa se lee de la base de datos y reemplaza a la de la caché. [List.copyOf] crea una copia de solo lectura de la lista;
  • líneas 82–90: las listas se sirven desde la memoria. La lista devuelta es la propia lista de la caché: como es de solo lectura, un llamador que intentara agregarle un elemento provocaría una excepción, y la caché no puede modificarse accidentalmente;
  • líneas 94–96: el médico asociado a una cuenta, obtenido de la caché: un médico conectado ve de inmediato su propia agenda. El flujo de médicos se filtra ([filter]), y [findFirst] devuelve el primer médico seleccionado dentro de un [Optional], que está vacío si ninguno es adecuado. [getUserId()] devuelve un [Integer] (un objeto), y [userId] es un [int]: [Objects.equals] compara los dos valores sin riesgo de error, incluso si [Integer] fuera igual a [null].
    // ------------------------------------------------ delegaciones simples

    @Override
    public List<Slot> getAllSlots(int doctorId) {
        return business.getAllSlots(doctorId);
    }

    @Override
    public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
        return business.getDoctorDayAppointments(doctorId, day);
    }

    @Override
    public Optional<Client> getClientById(int id) {
        return business.getClientById(id);
    }

    @Override
    public Optional<Doctor> getDoctorById(int id) {
        return business.getDoctorById(id);
    }

    @Override
    public Optional<Appointment> getAppointmentById(int id) {
        return business.getAppointmentById(id);
    }

    @Override
    public Optional<Slot> getSlotById(int id) {
        return business.getSlotById(id);
    }

    @Override
    public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
        return business.getDoctorDaySchedule(doctorId, day);
    }

    // sin caché aquí: lo que importa son los datos más recientes (un paciente
    // que acaba de editar o eliminar su cuenta)
    @Override
    public Optional<Client> getClientByUserId(int userId) {
        return business.getClientByUserId(userId);
    }

    @Override
    public List<Appointment> getClientUpcomingAppointments(int clientId) {
        return business.getClientUpcomingAppointments(clientId);
    }

    @Override
    public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
        return business.addAppointment(day, slot, client);
    }

    @Override
    public void deleteAppointment(Appointment appointment) {
        business.deleteAppointment(appointment);
    }

    // ------------------------------------------------ escrituras => recarga

    @Override
    public Doctor addDoctor(PersonData data) {
        Doctor doctor = business.addDoctor(data);
        reloadDoctors();
        return doctor;
    }

    @Override
    public Doctor editDoctor(int id, PersonData data) {
        Doctor doctor = business.editDoctor(id, data);
        reloadDoctors();
        return doctor;
    }

    @Override
    public void deleteDoctor(int id) {
        business.deleteDoctor(id);
        reloadDoctors();
    }

    @Override
    public Client addClient(PersonData data) {
        Client client = business.addClient(data);
        reloadClients();
        return client;
    }

    @Override
    public Client editClient(int id, PersonData data) {
        Client client = business.editClient(id, data);
        reloadClients();
        return client;
    }

    @Override
    public void deleteClient(int id) {
        business.deleteClient(id);
        reloadClients();
    }
}

Comentemos este código:

  • líneas 3–58: las demás solicitudes se transmiten tal cual a la capa de negocio;
  • líneas 38–43: el titular de la cuenta no se busca intencionalmente en la caché; un paciente que acaba de modificar o eliminar su cuenta debe verse tal como aparece en la base de datos;
  • líneas 60–101: toda operación de escritura que involucre a médicos o clientes va seguida de una recarga de la lista correspondiente. Como este bean es el único punto de entrada de los controladores a la capa de negocio, la regla «escritura = recarga de la caché» se implementa solo aquí, y la caché no puede quedar obsoleta. Si la capa de negocio rechaza la operación ([BusinessException]), la excepción termina el método antes de que se recargue la caché, ya que este paso deja de ser necesario.

11.14.9. web/Validation.java

// =========================================================================
// web/Validation.java
// -------------------------------------------------------------------------
// Lo necesario para MOSTRAR DE NUEVO un formulario rechazado: los errores de entrada
// campo por campo, y los campos que se resaltan en rojo.
// =========================================================================
package rdvmedecins.web;

import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;

import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.Message;

public final class Validation {

    private Validation() {
    }

    // -----------------------------------------------------------------------
    // BindingResult (llenado por Spring durante el enlace y la validación
    // del formulario) -> el diccionario campo -> clave del mensaje, conservando
    // solo el primer mensaje de cada campo: { "lastName": "ERRORS.LASTNAME_REQUIRED", ... }
    //
    // Un error de CONVERSIÓN (un texto donde se espera un número:
    // version="abc") tiene el código "typeMismatch" y un mensaje técnico, en
    // inglés: lo reemplazamos por la clave ERRORS.INVALID_FORM.
    // -----------------------------------------------------------------------
    public static Map<String, String> errorsOf(BindingResult result) {
        Map<String, String> errors = new HashMap<>();
        for (FieldError error : result.getFieldErrors()) {
            String key = error.isBindingFailure() || error.getDefaultMessage() == null
                    ? "ERRORS.INVALID_FORM"
                    : error.getDefaultMessage();
            errors.putIfAbsent(error.getField(), key);
        }
        return errors;
    }

    // -----------------------------------------------------------------------
    // los campos del formulario afectados por cada error de negocio de "entrada"
    // (un duplicado): se resaltan en rojo, estando el mensaje en la parte inferior de la página
    // -----------------------------------------------------------------------
    public static final Map<String, List<String>> BUSINESS_ERROR_FIELDS = Map.of(
            "ERRORS.LOGIN_TAKEN", List.of("login"),
            "ERRORS.DOCTOR_ALREADY_EXISTS", List.of("firstName", "lastName"),
            "ERRORS.PATIENT_ALREADY_EXISTS", List.of("firstName", "lastName"));

    // el estado de un formulario a (re)mostrar: un mensaje bajo cada campo
    // rechazado por la validación (errors), y los campos que se resaltan en rojo,
    // esos más posiblemente otros (otherFields)
    public static FormState state(Map<String, String> errors, Collection<String> otherFields) {
        Set<String> fields = new HashSet<>(errors.keySet());
        if (otherFields != null) {
            fields.addAll(otherFields);
        }
        return new FormState(errors, fields);
    }

    // EL mensaje de error de la página, mostrado en la parte inferior de la página: [error] si
    // hay uno, si no "The form contains errors." si hay
    // errores de campo, si no nada
    public static Message pageMessage(Map<String, String> errors, Message error) {
        if (error != null) {
            return error;
        }
        return errors.isEmpty() ? null : Message.of("ERRORS.INVALID_FORM");
    }
}

Cuando se rechaza un formulario, la página se vuelve a mostrar con los datos introducidos, un mensaje debajo de cada campo no válido, los campos no válidos resaltados en rojo y un mensaje en la parte inferior de la página. Esta clase prepara esta información para los controladores:

  • líneas 22–25: una clase utilitaria: [final] (no puede tener subclases), un constructor privado (no se pueden crear objetos de esta clase) y solo métodos estáticos;
  • líneas 36–45: convierte el [BindingResult] (véanse los ejemplos 09 y 19) —poblado por [Spring] durante el enlace y la validación del formulario— en un diccionario simple «campo → clave de mensaje». [putIfAbsent] agrega una entrada solo si el campo aún no tiene una: solo se conserva el primer mensaje de cada campo, y solo se muestra un mensaje debajo del campo. Los mensajes de las restricciones de validación son claves de traducción (véase [models/Forms.java]); en cambio, un error de conversión ([isBindingFailure()]: texto donde se espera un número) tiene un mensaje técnico en inglés, que se reemplaza por la clave [ERRORS.INVALID_FORM];
  • líneas 51–54: ciertos errores de la capa de negocio se refieren a campos específicos: un nombre de usuario que ya está en uso, o un médico o un cliente con el mismo nombre. Estos campos se resaltarán en rojo, y el mensaje se mostrará en la parte inferior de la página. [Map.of] genera el diccionario en una sola expresión;
  • líneas 59–65: el estado del formulario que se va a mostrar: los mensajes debajo de los campos y los campos que se resaltarán en rojo —es decir, los que tienen un mensaje—, más los campos [otherFields] (los que indican un error de negocio). Un [HashSet] es un conjunto: cada elemento aparece una sola vez. El resultado es un record [FormState] (véase [models/ViewModels.java]);
  • líneas 70–75: el mensaje de la parte inferior de la página: el mensaje de error específico, si lo hay; de lo contrario, si hay errores de campo, el mensaje «El formulario contiene errores»; de lo contrario, nada ([null]).

11.14.10. web/Utils.java

// =========================================================================
// web/Utils.java
// -------------------------------------------------------------------------
// Pequeñas funciones utilitarias de la capa web:
//   - etiquetas: "Mme Alice DURAND";
//   - fechas: "yyyy-MM-dd", horas "8:05", días "Wednesday 23 September 2026";
//   - entrada: lectura de un entero positivo enviado por el navegador;
//   - paciente: el paciente (entidad Client) del usuario conectado.
//
// Una clase "utilitaria": solo métodos estáticos, nunca creamos
// un objeto de esta clase (constructor privado).
// =========================================================================
package rdvmedecins.web;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;
import java.util.Locale;
import java.util.Optional;

import org.springframework.security.oauth2.jwt.Jwt;

import rdvmedecins.auth.InvalidSessionException;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;

public final class Utils {

    private Utils() {
    }

    // ----------------------------------------------------------------- etiquetas

    // "Mme Alice DURAND"
    public static String label(Person p) {
        return p.getTitle() + " " + p.getFirstName() + " " + p.getLastName();
    }

    // ----------------------------------------------------------------- fechas

    // el formato de las fechas en las URL y en el campo <input type="date">;
    // ESTRICTO: "2026-02-30" se rechaza (y no se lleva al 2 de marzo)
    private static final DateTimeFormatter ISO = DateTimeFormatter.ofPattern("uuuu-MM-dd")
            .withResolverStyle(ResolverStyle.STRICT);

    // la fecha, si [text] es una fecha que existe en el formato yyyy-MM-dd
    public static Optional<LocalDate> validDate(String text) {
        try {
            return Optional.of(LocalDate.parse(text, ISO));
        } catch (DateTimeParseException | NullPointerException e) {
            return Optional.empty();
        }
    }

    public static String iso(LocalDate day) {
        return day.format(ISO);
    }

    // "8:05" en lugar de "8:5"
    public static String formatTime(int h, int m) {
        return "%d:%02d".formatted(h, m);
    }

    public static String time(Slot s) {
        return formatTime(s.getStartHour(), s.getStartMinute()) + " - " + formatTime(s.getEndHour(), s.getEndMinute());
    }

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el
    // idioma de la solicitud
    public static String formatDay(LocalDate day, Locale language) {
        return day.format(DateTimeFormatter.ofPattern("EEEE d MMMM yyyy", language));
    }

    // ----------------------------------------------------------------- entrada

    // "3" -> 3 ; "", "abc", "-2", "+2", null -> null
    public static Integer positiveInteger(String value) {
        if (value == null || !value.matches("\\d{1,9}")) {
            return null;
        }
        int n = Integer.parseInt(value);
        return n > 0 ? n : null;
    }

    // ----------------------------------------------------------------- usuario

    // el usuario descrito por el token de la solicitud (parámetro
    // @AuthenticationPrincipal Jwt token de una acción). Un token válido pero
    // incompleto (con claims faltantes) se trata como una sesión expirada.
    public static ConnectedUser user(Jwt token) {
        ConnectedUser user = ConnectedUser.of(token);
        if (user == null) {
            throw new InvalidSessionException();
        }
        return user;
    }

    // ----------------------------------------------------------------- paciente

    // -----------------------------------------------------------------------
    // El paciente (entidad Client) que corresponde al usuario conectado.
    //
    // El token JWT solo contiene el id de la CUENTA (users.id). Para un rol
    // USER, encontramos el cliente correspondiente gracias a la columna clients.user.
    //
    // Si no hay ninguno, la cuenta fue eliminada desde el inicio de sesión
    // mientras su token sigue siendo válido: lo tratamos como una sesión
    // expirada (véase InvalidSessionException).
    // -----------------------------------------------------------------------
    public static Client connectedPatient(ApplicationModel application, ConnectedUser user) {
        if (user == null) {
            throw new InvalidSessionException();
        }
        return application.getClientByUserId(user.userId()).orElseThrow(InvalidSessionException::new);
    }
}

Comentemos este código:

  • líneas 38–40: el nombre de un médico o de un cliente: «Mme Alice DURAND». El parámetro es de tipo [Person], la clase padre de las entidades [Doctor] y [Client] (véase «Entidades»): la misma función sirve para ambas;
  • Líneas 46–47: el formato de fecha en las URL y en el campo [<input type="date">]. El modo [STRICT] rechaza una fecha que no existe: [2026-02-30] es un error, en lugar de convertirse en el 2 de marzo (véase el Ejemplo 12). En este modo, el año se escribe como [uuuu]: [yyyy] se referiría al año «de la era», lo que exigiría especificar también la era (antes o después de J.-C);
  • líneas 50–56: la fecha, si el texto es una fecha válida en el formato [yyyy-MM-dd]; de lo contrario, está vacía. Un texto en el formato [null] provoca una [NullPointerException], que se intercepta como una fecha mal escrita: el formato [catch (A | B e)] intercepta dos tipos de excepciones;
  • líneas 58–60: la operación inversa: una fecha convertida en el texto [yyyy-MM-dd];
  • líneas 63–69: una hora en el formato [8:05] (el formato [%02d] escribe un entero con al menos dos dígitos, rellenado con ceros) y la hora de una franja horaria: [8:00 - 8:20];
  • líneas 73–75: un día escrito completo, en el idioma de la solicitud, que el controlador recibe como parámetro ([Locale]): «mercredi 23 septembre 2026» o «Wednesday 23 September 2026». [EEEE] es el día de la semana escrito completo, y [MMMM] es el mes;
  • líneas 80–86: un identificador enviado por el navegador (en la URL o en un campo de formulario): un entero estrictamente positivo, o [null]. La expresión regular [\d{1,9}] acepta solo dígitos, hasta nueve: sin signos, sin espacios y sin números demasiado grandes para un [int]. El controlador solo necesita entonces probar [null];
  • líneas 93–99: el usuario identificado por el token de la solicitud, que una acción recibe mediante un parámetro declarado como [@AuthenticationPrincipal Jwt token]. Un token correctamente firmado pero incompleto se trata como una sesión expirada;
  • Líneas 113–118: el paciente (entidad [Client]) asociado al usuario conectado. El token JWT contiene únicamente el identificador de la cuenta; buscamos el cliente asociado a esa cuenta. Si ya no existe, significa que la cuenta se eliminó desde que el usuario inició sesión: [InvalidSessionException] será manejada por [HtmlExceptionHandler], como se vio antes, que redirige a la página de inicio de sesión. [orElseThrow] cierra la sesión del cliente a partir de su [Optional] , o lanza la excepción generada por su argumento si [Optional] está vacío. [InvalidSessionException::new] es una referencia a constructor: la forma abreviada de la lambda [() -> new InvalidSessionException()].

11.15. Plantillas de formularios y de vistas

Dos tipos de clases transfieren datos entre el navegador, los controladores y las vistas: los formularios, que el enlace de modelo puebla a partir de lo que envía el navegador y que luego se validan; y los modelos de vista, que los controladores preparan para las vistas. Los primeros son JavaBeans, los segundos son records; veremos por qué. Se almacenan en la carpeta [models], junto con las reglas de validación de entrada que comparten.

11.15.1. models/InputRules.java

// =========================================================================
// models/InputRules.java
// -------------------------------------------------------------------------
// Las reglas de entrada comunes a los formularios de "persona".
// =========================================================================
package rdvmedecins.models;

import java.util.List;

public final class InputRules {

    private InputRules() {
    }

    public static final List<String> TITLES = List.of("Mr", "Mme", "Melle");

    // login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
    public static final String LOGIN_FORMAT = "^[a-z0-9._-]{1,30}$";

    // longitud mínima de una contraseña ELEGIDA por un paciente
    public static final int PASSWORD_MIN = 6;

    // "  dupont " -> "dupont" ; "   " -> null
    public static String clean(String value) {
        return value == null || value.isBlank() ? null : value.trim();
    }

    // un campo vacío -> null; en una contraseña, NO quitamos los
    // espacios (pueden formar parte de ella)
    public static String emptyToNull(String value) {
        return value == null || value.isEmpty() ? null : value;
    }
}
  • línea 15: los títulos posibles. Se utilizan para generar la lista desplegable de los formularios (véase [ViewModels.java], más adelante);
  • línea 18: el formato de un nombre de usuario, descrito mediante una expresión regular: de 1 a 30 caracteres formados por letras minúsculas, dígitos, un punto, un guion bajo y un guion. [^] y [$] indican el comienzo y el final del texto;
  • línea 21: la longitud mínima de una contraseña elegida por un paciente;
  • líneas 18 y 21: estos dos campos son constantes: [static final], inicializadas con un valor escrito directamente en el programa. El compilador conoce sus valores, lo que permite usarlas como argumentos de una anotación, por ejemplo, [@Size(min = InputRules.PASSWORD_MIN)]. No ocurre lo mismo con la lista [TITLES] (línea 15), que se crea en tiempo de ejecución;
  • líneas 24–26: limpieza de una entrada: se eliminan los espacios iniciales y finales, y un campo vacío o formado solo por espacios ([isBlank()]) se convierte en [null], es decir, ausente;
  • líneas 30–32: en el caso de una contraseña, un campo vacío se convierte en [null], pero los espacios se conservan: forman parte de la contraseña.

11.15.2. models/Forms.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// models/Forms.java
// -------------------------------------------------------------------------
// Los campos de los formularios de "persona" y sus restricciones. Tres
// formularios comparten los mismos campos de identidad (título, nombre, apellido):
//
//   PersonFields                  título, nombre, apellido
//    ├─ PersonForm                + login / contraseña OPCIONALES, version
//    │                              (el ADMIN agrega o edita un médico / cliente)
//    ├─ RegistrationForm          + login / contraseña / confirmación OBLIGATORIOS
//    │                              (un paciente crea su cuenta)
//    └─ MyAccountForm             + login, nueva contraseña opcional,
//                                   contraseña ACTUAL obligatoria, version
//                                   (un paciente edita su cuenta)
//
// ENLACE DEL MODELO (MODEL BINDING): cuando una acción de un controlador recibe un parámetro de
// una de estas clases, Spring MVC crea el objeto y llena cada campo, mediante
// su setter, con el parámetro del mismo nombre (véase el ejemplo 18).
//
// VALIDACIÓN: con @Valid, Spring verifica luego las restricciones
// (@NotBlank, @Size...) y almacena los errores en el BindingResult que sigue
// al parámetro (véanse los ejemplos 09 y 19).
//
// Los mensajes de error son CLAVES de traducción (véase i18n/*.json).
//
// LIMPIEZA DE ENTRADA: los setters eliminan los espacios sobrantes
// (una entrada vacía se convierte en null) y ponen el login en minúsculas. Una
// contraseña, en cambio, no se "limpia" (los espacios pueden formar parte de ella).
//
// Las clases están "anidadas" (static) en la clase Forms: un solo
// archivo para cuatro clases pequeñas. Se designan como
// Forms.PersonForm...
// =========================================================================
package rdvmedecins.models;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;

public final class Forms {

    private Forms() {
    }

    // ------------------------------------------------------------------ base común
    public abstract static class PersonFields {

        @NotNull(message = "ERRORS.INVALID_TITLE")
        @Pattern(regexp = "Mr|Mme|Melle", message = "ERRORS.INVALID_TITLE")
        private String title;

        // longitudes máximas = las de las columnas SQL (VARCHAR(20))
        @NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")
        @Size(max = 20, message = "ERRORS.FIRSTNAME_TOO_LONG")
        private String firstName;

        @NotBlank(message = "ERRORS.LASTNAME_REQUIRED")
        @Size(max = 20, message = "ERRORS.LASTNAME_TOO_LONG")
        private String lastName;

        public String getTitle() { return title; }
        public void setTitle(String title) { this.title = title; }

        public String getFirstName() { return firstName; }
        public void setFirstName(String firstName) { this.firstName = InputRules.clean(firstName); }

        public String getLastName() { return lastName; }
        public void setLastName(String lastName) { this.lastName = InputRules.clean(lastName); }
    }

El comentario de encabezado (líneas 4–32) describe los tres formularios de «persona» y su base común. Los formularios siguen el enfoque utilizado en los Ejemplos 18 y 19: una acción recibe un parámetro anotado con [@Valid], seguido de un parámetro [BindingResult]. [Spring MVC] crea el objeto, lo puebla con los campos recibidos (enlace de modelo), luego verifica las restricciones establecidas por las anotaciones (validación) y almacena los errores, si los hay, en [BindingResult]. Estas anotaciones ([@NotNull], [@NotBlank], [@Size], [@Pattern]) son las del estándar [Bean Validation] (paquete [jakarta.validation]), incorporado por el starter [spring-boot-starter-validation] junto con su implementación, [Hibernate Validator]. Comentemos este código:

  • líneas 41–44: una clase cuyo único propósito es agrupar cuatro pequeñas clases anidadas en un solo archivo. Declaradas como [static], son independientes de cualquier instancia de [Forms]: se las designa como [Forms.PersonForm], o simplemente [PersonForm] después de un [import];
  • Línea 47: los campos de identidad, comunes a los tres formularios. La clase es abstracta ([abstract]): no se puede crear un objeto de ella, solo derivar de ella;
  • Líneas 49–51: el título, que es obligatorio ([@NotNull]) y se selecciona de la lista ([@Pattern]). Los valores se repiten en la expresión regular [Mr|Mme|Melle] ([|] significa «o»): el argumento de una anotación debe ser una constante, y la lista [InputRules.TITLES] no lo es. [@Pattern] exige que todo el texto coincida con la expresión;
  • líneas 53–60: el nombre y el apellido, que son obligatorios y no deben exceder los 20 caracteres: el ancho de las columnas SQL (véase «La base de datos»). [@NotBlank] rechaza [null], el texto vacío y el texto formado únicamente por espacios. Cada restricción tiene su propio mensaje; los mensajes son claves de traducción (véase el Ejemplo 22), que la vista traduce al idioma del usuario;
  • líneas 62–69: los getters, cada uno escrito en una sola línea. Los setters limpian la entrada a medida que la reciben: como el enlace de modelo actualiza los campos mediante los setters antes de la validación, lo que se valida es el valor ya limpiado. Un nombre formado por espacios se convierte en [null], y es [@NotBlank] quien lo rechaza.

¿Por qué JavaBeans y no records? Un JavaBean es una clase ordinaria que tiene un constructor sin parámetros y, para cada propiedad, un par [getXxx()] y [setXxx()]. [Spring MVC] crea el objeto vacío y luego llama a un setter por cada campo recibido: cada campo se procesa por separado. [Spring MVC] también puede poblar un record, pero llamando a su constructor con todos los campos a la vez: si un solo campo no se puede convertir (como texto en el campo numérico [version]), el objeto no se construye y no se verifica ninguna restricción. Con un JavaBean, un error de conversión en un campo no impide la validación de los demás: el usuario ve todos los errores a la vez. El JavaBean también permite limpiar la entrada en los setters.

    // ------------------------------------------------------------------ ADMIN
    public static class PersonForm extends PersonFields {

        // opcional (véase business/PersonData.java)
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // opcional; 72 caracteres como máximo (más allá, bcrypt ignora el resto)
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        // campo oculto del formulario de edición (bloqueo optimista).
        // Integer: un campo ausente o vacío da null; un texto que no es
        // un número produce un error de enlace (typeMismatch)
        private Integer version;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public Integer getVersion() { return version; }
        public void setVersion(Integer version) { this.version = version; }
    }

    // ------------------------------------------------------------------ registro de un paciente
    public static class RegistrationForm extends PersonFields {

        @NotNull(message = "ERRORS.LOGIN_REQUIRED")
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // dos restricciones @Size, cada una con su mensaje
        @NotNull(message = "ERRORS.PASSWORD_REQUIRED")
        @Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        @NotNull(message = "ERRORS.CONFIRMATION_REQUIRED")
        private String confirmation;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public String getConfirmation() { return confirmation; }
        public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }
    }

    // ------------------------------------------------------------------ "Manage my account"
    public static class MyAccountForm extends PersonFields {

        @NotNull(message = "ERRORS.LOGIN_REQUIRED")
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // opcional: vacío = contraseña sin cambios
        @Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        private String confirmation;

        // la contraseña ACTUAL, requerida para cualquier edición de la cuenta
        @NotNull(message = "ERRORS.CURRENT_PASSWORD_REQUIRED")
        private String currentPassword;

        private Integer version;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public String getConfirmation() { return confirmation; }
        public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }

        public String getCurrentPassword() { return currentPassword; }
        public void setCurrentPassword(String password) { this.currentPassword = InputRules.emptyToNull(password); }

        public Integer getVersion() { return version; }
        public void setVersion(Integer version) { this.version = version; }
    }

    private static String lowerCase(String text) {
        return text == null ? null : text.toLowerCase(java.util.Locale.ROOT);
    }
}

Comentemos este código:

  • línea 2: el formulario de ADMIN, para agregar o modificar un médico o un cliente. La clase hereda los campos de identidad, sus restricciones y sus accesores;
  • líneas 4–6: el identificador de usuario, que aquí es opcional (si se deja en blanco, por defecto es el apellido en minúsculas al crear y permanece sin cambios al modificar; véase «La capa de negocio»), pero debe tener el formato correcto si se proporciona. Como todas las restricciones de [Bean Validation] excepto [@NotNull] y [@NotBlank], [@Pattern] acepta el valor [null]: esto es lo que hace que el campo sea opcional. El setter (línea 18) limpia el identificador y lo convierte a minúsculas (método [lowerCase], líneas 89–91);
  • líneas 8–10: la contraseña, que también es opcional, con un máximo de 72 caracteres: el algoritmo [bcrypt] ignora los caracteres siguientes. No se limpia, sino que simplemente se establece en [null] si está vacía (línea 21);
  • líneas 12–15: la versión del registro, en un campo oculto del formulario de actualización (bloqueo optimista; véase el Ejemplo 28). El tipo [Integer] —no [int]— acepta el valor [null]: un campo ausente o vacío da como resultado [null]. Un texto que no es un número produce un error de conversión, que [web/Validation.java] convierte en el mensaje «El formulario contiene errores»;
  • línea 28: un paciente crea una cuenta. El identificador es obligatorio (línea 30): [@NotNull] basta, ya que el setter convierte una entrada vacía en [null];
  • líneas 34–38: la contraseña, obligatoria, de 6 a 72 caracteres. Dos anotaciones [@Size] en el mismo campo: una anotación declarada como repetible puede aparecer varias veces, en este caso para que cada límite tenga su propio mensaje;
  • líneas 40–41: confirmación de la contraseña, obligatoria. Verificar que la contraseña coincida con su confirmación involucra dos campos: lo comprueba el controlador ([RegistrationController], véase «La capa web: controladores»);
  • línea 54: un paciente que modifica su cuenta. El identificador es obligatorio; la nueva contraseña es opcional (líneas 60–63): si se deja en blanco, permanece sin cambios y, por lo tanto, su confirmación (línea 65) no es obligatoria aquí. En cambio, la contraseña actual es obligatoria para cualquier cambio (líneas 67–69), al igual que la versión del registro de viaje en un campo oculto (línea 71);
  • líneas 89–91: conversión del nombre de usuario a minúsculas. [Locale.ROOT] hace que la conversión sea independiente del idioma del servidor (en turco, por ejemplo, la minúscula de [I] no es [i]). El nombre completo [java.util.Locale] evita una línea como [import].

11.15.3. models/ViewModels.java

El archivo se presenta en dos fragmentos.

// =========================================================================
// models/ViewModels.java
// -------------------------------------------------------------------------
// Los "modelos de vista": lo que cada controlador pasa a
// su vista, con el nombre [model]. Son records: objetos inmutables,
// construidos de una sola vez por el controlador, que la vista se limita a leer
// (${model.schedule.rows}...).
//
// Regla seguida por todas las páginas: ninguna lógica en las vistas. Los
// controladores preparan datos YA formateados ("Mme Marie
// PELISSIER", "8:00 - 8:20", selected = true...) y ya filtrados según
// el rol del usuario; las vistas se limitan a colocarlos en el HTML.
// =========================================================================
package rdvmedecins.models;

import java.util.List;
import java.util.Map;
import java.util.Set;

import rdvmedecins.auth.Captcha;

public final class ViewModels {

    private ViewModels() {
    }

    // -------------------------------------------------------------------------
    // lo que TODAS las páginas tienen en común, leído por el layout
    // (templates/layout.html): la clave del título de la página, y EL mensaje
    // de error de la página, mostrado en la parte inferior de la página (null: sin error)
    // -------------------------------------------------------------------------
    public interface ViewModel {
        String pageTitle();

        Message error();
    }

    // un mensaje por traducir: su clave y sus parámetros
    public record Message(String key, Map<String, String> params) {

        public static Message of(String key) {
            return new Message(key, Map.of());
        }
    }

    // una opción de una lista desplegable (médico, paciente)
    public record OptionView(int id, String label, boolean selected) {
    }

    // ------------------------------------------------------------------ inicio de sesión
    public record LoginModel(String pageTitle, Message error, String login, Captcha captcha) implements ViewModel {
    }

    // ------------------------------------------------------------------ agenda
    public record ScheduleRowView(
            int slotId,
            String time, // "8:00 - 8:20"
            boolean free,
            String patient, // nombre mostrado para una franja reservada; null = "Booked"
            boolean mine, // la cita del paciente conectado
            boolean bookable, // ¿mostrar el botón "Book"?
            String bookUrl,
            Integer appointmentId) { // se llena solo si se muestra el botón "Cancel"
    }

    public record ScheduleView(String doctor, String day, List<ScheduleRowView> rows) {
    }

    public record BookingView(
            int slotId,
            String time,
            List<OptionView> clients, // ADMIN / DOCTOR: los pacientes entre los que elegir
            String patient) { // USER: el paciente es él mismo
    }

    public record ScheduleModel(
            String pageTitle,
            Message error,
            List<OptionView> doctors,
            Integer doctorId,
            String day, // "yyyy-MM-dd"
            ScheduleView schedule,
            BookingView booking,
            String backUrl, // la agenda mostrada, sin diálogo de reserva
            // paciente que ya tiene una cita futura: el mensaje que explica
            // por qué no hay botón "Book"
            String info) implements ViewModel {
    }

Los modelos de vista siguen una regla ya aplicada en los ejemplos: nada de lógica en las vistas. Los controladores preparan datos ya formateados («Mme Marie PELISSIER», «8:00 – 8:20») y ya filtrados según el rol del usuario; las vistas simplemente los colocan en el HTML. Se trata de records: construidos una sola vez por el controlador, la vista solo los lee y escribe, por ejemplo, [${model.schedule.rows}]; [Thymeleaf] llama entonces a los accesores [schedule()], seguido de [rows()]. Cada controlador almacena el modelo de su vista con el nombre [model]. Comentemos este código:

  • líneas 32–36: lo que todas las páginas tienen en común, leído por la plantilla [templates/layout.html] (véase «Vistas»): la clave de traducción del título de la página y el mensaje de error de la página, que se muestra en la parte inferior, o [null]. Esto es una interfaz, no una clase padre: un record no puede heredar de una clase, pero sí puede implementar interfaces. Un record que tiene los componentes [pageTitle] y [error] tiene automáticamente los accesores [pageTitle()] y [error()]: implementa la interfaz sin una sola línea de código adicional;
  • líneas 39–44: un mensaje que se debe traducir: su clave y sus parámetros. El método estático [of] crea un mensaje sin parámetros;
  • líneas 47–48: una opción de una lista desplegable (un médico, un paciente), ya marcada como seleccionada o no seleccionada (véase el Ejemplo 18);
  • líneas 51–52: la página de inicio de sesión: el nombre de usuario ya introducido y el CAPTCHA que se mostrará. El cuerpo del record está vacío: todo está en sus componentes;
  • líneas 55–64: una entrada del calendario, es decir, una franja horaria. El controlador ya ha determinado todo: si se muestra o no el nombre del paciente (un paciente no puede ver los nombres de los demás: [patient] equivale entonces a [null], y la vista muestra «Booked»), si se muestra o no el botón «Book» y si se muestra o no el botón «Cancel» ([appointmentId] tiene valor). [appointmentId] es un [Integer], que puede equivaler a [null];
  • líneas 66–67: la agenda de un médico para un día determinado: el médico, el día escrito completo y las filas;
  • líneas 69–74: la ventana de reserva: la lista de pacientes para ADMIN y los médicos, o solo el nombre del paciente conectado cuando se trata de un único paciente;
  • líneas 76–88: la página del calendario de citas: la lista de médicos, el médico y el día seleccionados, el calendario de citas ([null] mientras no se haya seleccionado ningún médico), la ventana de reserva (si corresponde), la URL del calendario de citas sin esta ventana (línea 84) y el mensaje que explica a un paciente por qué no puede hacer una reserva.
    // ------------------------------------------------------------------ formularios de "persona"

    // los valores mostrados en los campos del formulario (nunca la contraseña)
    public record PersonValues(String title, String firstName, String lastName, String login, Integer version) {

        public static PersonValues empty() {
            return new PersonValues("Mr", "", "", "", null);
        }
    }

    // el estado de un formulario rechazado: el mensaje mostrado BAJO cada campo
    // (campo -> clave del mensaje), y los campos que se resaltan en rojo (clase
    // de Bootstrap is-invalid): los que tienen un mensaje, más posiblemente otros
    // (nombre + apellido duplicados, login ocupado...)
    public record FormState(Map<String, String> errors, Set<String> invalidFields) {

        public static FormState empty() {
            return new FormState(Map.of(), Set.of());
        }

        public String errorOf(String field) {
            return errors.get(field);
        }

        public String invalidClass(String field) {
            return invalidFields.contains(field) ? "is-invalid" : "";
        }
    }

    // una opción de la lista de títulos
    public record TitleOption(String value, boolean selected) {
    }

    // lo que usa el fragmento común person-fields.html (título, nombre, apellido)
    public interface FormView extends ViewModel {
        PersonValues values();

        FormState state();

        // un método "default": escrito en la interfaz, heredado por los records
        default List<TitleOption> titles() {
            return InputRules.TITLES.stream().map(t -> new TitleOption(t, t.equals(values().title()))).toList();
        }
    }

    public record PersonFormModel(
            String pageTitle,
            Message error,
            PersonValues values,
            FormState state,
            boolean creating, // true: agregar; false: editar
            String action, // URL del POST
            String listUrl) implements FormView {
    }

    public record RegistrationModel(String pageTitle, Message error, PersonValues values, FormState state)
            implements FormView {

        public int passwordMin() {
            return InputRules.PASSWORD_MIN;
        }
    }

    public record MyAccountModel(String pageTitle, Message error, PersonValues values, FormState state)
            implements FormView {

        public int passwordMin() {
            return InputRules.PASSWORD_MIN;
        }
    }

    // ------------------------------------------------------------------ listas de médicos / clientes

    // las claves de traducción específicas de cada tipo de persona
    public record PersonKeys(
            String title, // "Doctors"
            String add, // "Add a doctor"
            String edit, // "Edit a doctor"
            String empty, // "No doctors."
            String confirmDelete, // "Delete this doctor and their account?"
            String added, // "Doctor {name} has been added (login: {login})."
            String edited,
            String deleted) {
    }

    public record PersonView(String title, String firstName, String lastName, String login, String editUrl,
            String deleteUrl) {
    }

    public record PersonListModel(String pageTitle, Message error, PersonKeys keys, String addUrl,
            List<PersonView> persons) implements ViewModel {
    }

    // ------------------------------------------------------------------ área del paciente
    public record AppointmentView(int id, String day, String time, String doctor, String scheduleUrl) {
    }

    public record AreaModel(String pageTitle, Message error, String patient, List<AppointmentView> appointments)
            implements ViewModel {
    }

    // ------------------------------------------------------------------ página de error
    public record ErrorModel(String pageTitle, Message error, int code, String message) implements ViewModel {
    }
}

Analicemos este código:

  • líneas 4–9: los valores que se muestran en los campos de un formulario de «persona»; nunca la contraseña: una contraseña no se devuelve al navegador. [empty()] proporciona los valores de un formulario de alta;
  • líneas 15–28: el estado de un formulario, preparado por [web/Validation.java]: los mensajes debajo de los campos y los campos que se resaltarán en rojo. Un record puede tener métodos: [errorOf] devuelve el mensaje de un campo (o [null]), [invalidClass] devuelve la clase [Bootstrap] [is-invalid], que enmarca un campo en rojo, o una cadena vacía. Por ejemplo, las vistas escriben [th:classappend="${state.invalidClass('login')}"], donde [state] se refiere a [model.state];
  • líneas 31–32: una opción de la lista de títulos, con la seleccionada marcada (véase el Ejemplo 18);
  • líneas 35–44: lo que utiliza el fragmento común [person-fields.html], que muestra los campos de título, nombre y apellido de los tres formularios: los valores y el estado. Una interfaz puede heredar de otra ([extends ViewModel]). Líneas 41–43: un método default ([default]) es un método cuyo código se escribe dentro de la propia interfaz; las clases y los records que implementan la interfaz lo heredan. Aquí, la lista de títulos, generada a partir de los valores del formulario: el flujo de títulos se transforma ([map]) en opciones, y [toList()] reúne el resultado en una lista. Las tres plantillas de formulario se benefician de esto sin necesidad de código adicional;
  • líneas 46–54: el formulario de ADMIN, utilizado para agregar y modificar entradas (véase el Ejemplo 28): el modo, la URL de envío del formulario y la URL de la lista para el botón de regreso;
  • líneas 56–70: los formularios de registro y de gestión de la cuenta; pasan a la vista la longitud mínima de la contraseña, que se utiliza como parámetro [{min}] en el mensaje de error del campo y, en el caso del registro, en el texto de ayuda. Basta un método ordinario en el cuerpo del record: la vista escribe [${model.passwordMin()}];
  • líneas 75–84: las páginas de gestión de médicos y de clientes son las mismas vistas; solo difieren sus textos. Este record contiene las claves de traducción específicas de cada tipo de persona;
  • líneas 86–92: una fila de la lista de médicos o de clientes, con las direcciones de sus botones Edit y Delete, y el modelo de la página de lista;
  • líneas 95–100: el área del paciente: su nombre y sus próximas citas, cada una con un enlace al calendario del día;
  • líneas 103–104: la página de error: el código HTTP y la clave del mensaje.

11.16. La capa web: controladores

Los controladores son la parte visible de la capa web: cada uno recibe las solicitudes de un grupo de páginas, lee sus parámetros, consulta la capa de negocio (siempre a través del servicio [ApplicationModel]), y luego selecciona una vista y le pasa un modelo, o redirige la solicitud. Una acción devuelve una cadena: o bien el nombre de una vista (["schedule"] se refiere al archivo [templates/schedule.html]; véase el Ejemplo 13), o bien una redirección (["redirect:/login"]; véase el Ejemplo 04). El modelo de la vista es siempre un único objeto, un [record] del archivo [models/ViewModels.java], almacenado en el [Model] de Spring con el nombre [model]. Todos los formularios POST siguen el patrón Post/Redirect/Get (véase el Ejemplo 20); todos los mensajes son claves de traducción, que la vista traduce. El controlador de inicio de sesión, [AuthController], se ha comentado junto con la autenticación.

11.16.1. controllers/LanguageController.java

// =========================================================================
// controllers/LanguageController.java
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: los dos botones FR / EN de la barra de
// navegación. Ruta no protegida: debe ser posible cambiar de idioma antes de
// iniciar sesión.
//
// La elección se recuerda en la cookie del CookieLocaleResolver (véase
// config/WebConfig.java): en cada solicitud siguiente, Spring MVC la lee de nuevo
// y establece el idioma de la solicitud (el parámetro Locale de las acciones, el
// idioma de los mensajes #{...} de las vistas). Luego volvemos a la página de
// donde estábamos.
// =========================================================================
package rdvmedecins.controllers;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.web.Translator;

@Controller
public class LanguageController {

    private final LocaleResolver localeResolver;

    public LanguageController(LocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    @GetMapping("/language/{language}")
    public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
        if (!Translator.LANGUAGES.contains(language)) {
            // -> página de error 404 (véase ErrorController)
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // establece la cookie del idioma
        localeResolver.setLocale(request, response, Locale.of(language));
        return "redirect:" + originPage(request);
    }

    // -----------------------------------------------------------------------
    // la página anterior, según el encabezado HTTP "Referer" enviado por el
    // navegador. Conservamos solo su ruta (/schedule?...): redirigir a
    // una dirección completa proporcionada por la solicitud permitiría enviar
    // al usuario a otro sitio (la llamada vulnerabilidad de "open redirect").
    // -----------------------------------------------------------------------
    private static String originPage(HttpServletRequest request) {
        String referer = request.getHeader(HttpHeaders.REFERER);
        if (referer == null) {
            return "/";
        }
        try {
            URI url = new URI(referer);
            String path = url.getRawPath();
            // "//site.com/..." sería interpretado por el navegador como una dirección
            // en OTRO sitio: también se rechaza
            if (!url.isAbsolute() || path == null || !path.startsWith("/") || path.startsWith("//")
                    || path.startsWith("/language/")) {
                return "/";
            }
            return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
        } catch (URISyntaxException e) {
            return "/";
        }
    }
}

Este es, más o menos, el controlador del Ejemplo 22: la misma ruta [/language/{language}], la misma cookie de [CookieLocaleResolver], el mismo regreso a la página de origen mediante el encabezado [Referer]. Comentémoslo:

  • línea 32: [@Controller] convierte la clase en un controlador MVC, detectado al inicio y creado por [Spring] como un bean (un objeto cuya creación gestiona Spring y que puede inyectar en otros lugares, véase el Ejemplo 06);
  • líneas 35–39: el controlador recibe, mediante inyección de dependencias, el [LocaleResolver] definido en [config/WebConfig.java]. La clase tiene un solo constructor: Spring lo invoca proporcionando los beans solicitados, sin necesidad de anotarlo con [@Autowired]. Todos los controladores de la aplicación se escriben así;
  • líneas 41–42: la ruta [GET /language/{language}]. [@PathVariable] asocia el parámetro [language] con el segmento [{language}] de la URL (véase el Ejemplo 02). La acción también recibe la solicitud y la respuesta del servidor ([Servlet]): basta declararlas como parámetros, y Spring MVC las proporcionará;
  • líneas 43–46: un idioma desconocido ([/language/de]) devuelve una página 404. La acción no genera esta página: lanza una [ResponseStatusException], que Spring MVC convierte en una respuesta de error 404; el servidor reenvía entonces la solicitud a [/error], donde [ErrorController] (más adelante) genera la página;
  • línea 48: [setLocale] establece la cookie del idioma (su nombre, [rdvmedecins_language], su duración de un año y sus opciones [HttpOnly] y [SameSite=Lax] se definieron en [WebConfig]). En cada solicitud posterior, [CookieLocaleResolver] lee esta cookie y establece el idioma de la solicitud;
  • línea 49: regreso a la página anterior. El prefijo [redirect:] solicita a Spring MVC una respuesta 302;
  • líneas 58–76: la página anterior, a partir del encabezado [Referer]. Solo conservamos la ruta y los parámetros ([/schedule?doctorId=1&day=...]): redirigir a una URL completa proporcionada por la solicitud podría enviar al usuario a otro sitio (una vulnerabilidad conocida como «open redirect»);
  • Líneas 68–71: se rechazan los siguientes casos, lo que da lugar a un regreso a la raíz del sitio: una dirección relativa, una ruta que comienza con [//] (que el navegador interpretaría como la dirección de otro sitio) y una página llamada [/language/...], que haría que el navegador entrara en un bucle. [getRawPath] y [getRawQuery] restauran la ruta y los parámetros tal como aparecían en la URL, todavía codificados ([%20]...), listos para reinsertarse en una URL.

Verifiquemos esto con [curl]:

curl -i -H "Referer: http://localhost:8081/login" http://localhost:8081/language/en
1
2
3
4
HTTP/1.1 302
Set-Cookie: rdvmedecins_language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:47:10 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0

La cookie se establece y el navegador es redirigido a la página de inicio de sesión, que ahora se mostrará en inglés.

11.16.2. controllers/ScheduleController.java

La página principal de la aplicación y el controlador con más funciones. Analicémoslo sección por sección.

11.16.2.1. El código de la URL de la página

// =========================================================================
// controllers/ScheduleController.java
// -------------------------------------------------------------------------
// La página de la agenda: elección de un médico y de un día, agenda de ese
// médico en ese día, reserva y cancelación de citas.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               la página
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        la misma página, con
//                                                          el diálogo de reserva
//                                                          de la franja 7 abierto
//   POST /schedule/book                                    crea una cita
//   POST /schedule/cancel                                  cancela una cita
//
// Toda la página queda descrita por su URL: se puede recargar, guardar
// en los marcadores, usar el botón "Atrás" del navegador - sin una línea
// de JavaScript.
//
// Lo que cada quien ve y puede hacer:
//
//   | rol           | franja reservada mostrada         | Book               | Cancel  |
//   |---------------|-----------------------------------|--------------------|---------|
//   | ADMIN, DOCTOR | nombre del paciente               | para un paciente   | sí      |
//   |               |                                   | elegido en una lista |         |
//   | USER (paciente)| "Booked", o SU nombre si es      | para sí mismo, si  | no (*)  |
//   |               | su propia cita                    | no tiene           |         |
//   |               |                                   | cita futura        |         |
//
//   (*) el paciente cancela su cita desde su página "My area".
//
// CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no
// simplemente lo oculta la vista - nunca se coloca en el modelo
// pasado a la vista. Por tanto, el HTML enviado al navegador no lo contiene,
// ni siquiera oculto (un simple "Ver código fuente de la página" lo revelaría en caso contrario).
//
// Sin reservas en el pasado: el botón "Book" aparece solo
// para hoy y los días siguientes (y la capa de negocio lo rechazaría
// de todos modos).
//
// Seguridad: todas las URL /schedule exigen un usuario autenticado
// (véase SecurityConfig: anyRequest().authenticated()). @PreAuthorize en una
// acción exige además uno de los roles indicados. Sin un token válido: de vuelta a
// /login; rol insuficiente: página 403.
// =========================================================================
package rdvmedecins.controllers;

import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Optional;

import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.Dates;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.ViewModels.ScheduleModel;
import rdvmedecins.models.ViewModels.ScheduleView;
import rdvmedecins.models.ViewModels.ScheduleRowView;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.OptionView;
import rdvmedecins.models.ViewModels.BookingView;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;

@Controller
@RequestMapping("/schedule")
public class ScheduleController {

    // lo que el controlador sabe del usuario, para decidir qué mostrar
    private record Rights(
            boolean manager, // ADMIN o DOCTOR
            Client patient, // el cliente conectado (rol USER), si no null
            boolean patientCanBook) { // USER sin cita futura
    }

    // los campos ocultos doctorId / day, comunes a los dos formularios POST
    private record ScheduleRequest(int doctorId, LocalDate day) {
    }

    private final ApplicationModel application;

    public ScheduleController(ApplicationModel application) {
        this.application = application;
    }
  • líneas 7–12: las rutas de la página. Observe que la ventana de reserva no la abre [JavaScript]: es un parámetro de la URL ([book=7]) que indica al servidor que genere la página con la ventana abierta. El botón «Book» es, por lo tanto, simplemente un enlace. La página completa se describe mediante su URL: se puede recargar, guardar como marcador o usar el botón «Atrás» del navegador;
  • líneas 20–28: lo que cada rol ve y puede hacer. Esta tabla es la «especificación» de la página: el resto del controlador la implementa;
  • líneas 30–33: la regla de privacidad, a la que volveremos: los nombres de los demás pacientes no los oculta la vista; nunca se envían al navegador;
  • líneas 39–42: seguridad. La clase no tiene anotaciones de seguridad: es la configuración de [Spring Security] ([anyRequest().authenticated()], véase [config/SecurityConfig.java]) la que exige un usuario conectado para cualquier dirección [/schedule...]. Las acciones que además requieren un rol se anotan con [@PreAuthorize] (véase el Ejemplo 26);
  • líneas 84–86: [@RequestMapping("/schedule")], aplicada a la clase, es el prefijo de todas las rutas del controlador (véase el Ejemplo 02);
  • líneas 88–93: lo que el controlador sabe del usuario conectado, calculado una vez por solicitud (véase el método [rights], más adelante). Es un record (véase «El dominio: el calendario»), cuyos accesores son [rights.manager()], [rights.patient()]... Este [record] es privado y se declara dentro de la clase: solo esa clase lo utiliza. Un gestor es un ADMIN o un DOCTOR; [patient] solo se rellena para un cliente (rol USER);
  • líneas 95–97: el nombre del médico y la fecha leídos de los campos ocultos de los dos formularios POST de la página, una vez convertidos;
  • líneas 99–103: el servicio [ApplicationModel] (véase «La capa web: servicios comunes»), recibido por el constructor.

11.16.2.2. GET /schedule

    // -----------------------------------------------------------------------
    // GET /schedule
    // Los parámetros de la URL se leen en bruto (request.getParameter), para
    // distinguir un parámetro AUSENTE (null) de un parámetro VACÍO (?doctorId=).
    // -----------------------------------------------------------------------
    @GetMapping
    public String show(@AuthenticationPrincipal Jwt token, HttpServletRequest request,
            Locale locale, Model model) {
        String error = null;
        ConnectedUser user = Utils.user(token);
        Rights rights = rights(user);

        // el día: el de la URL si es válido, si no hoy
        LocalDate day = Dates.today();
        String rawDay = request.getParameter("day");
        if (rawDay != null) {
            Optional<LocalDate> requestedDay = Utils.validDate(rawDay);
            if (requestedDay.isPresent()) {
                day = requestedDay.get();
            } else {
                error = "ERRORS.INVALID_DATE";
            }
        }
        boolean dayBookable = !day.isBefore(Dates.today());

        // el médico: el de la URL; en su defecto, para un médico conectado, él mismo
        String rawDoctorId = request.getParameter("doctorId");
        Integer doctorId = Utils.positiveInteger(rawDoctorId);
        if (rawDoctorId == null && user.role() == Role.DOCTOR) {
            doctorId = application.getDoctorByUserId(user.userId()).map(d -> d.getId()).orElse(null);
        }

        // la lista desplegable de médicos ("final": utilizable en la lambda)
        final Integer chosenId = doctorId;
        List<OptionView> doctors = application.getAllDoctors().stream()
                .map(d -> option(d, d.getId().equals(chosenId)))
                .toList();

        // la agenda, si se ha elegido un médico (y la fecha es válida)
        ScheduleView schedule = null;
        if (doctorId != null && error == null) {
            Optional<DoctorDaySchedule> doctorSchedule = application.getDoctorDaySchedule(doctorId, day);
            if (doctorSchedule.isEmpty()) {
                error = "ERRORS.DOCTOR_NOT_FOUND";
            } else {
                schedule = scheduleView(doctorSchedule.get(), rights, dayBookable, locale);
            }
        }
  • línea 7: [@GetMapping] sin ruta: la acción responde a [GET /schedule], el prefijo del controlador;
  • Líneas 8–9: los parámetros de la acción, todos proporcionados por Spring MVC. [@AuthenticationPrincipal Jwt token] es el token [JWT] del usuario conectado, ya verificado por [Spring Security] (véase «Autenticación»); [request] da acceso a los parámetros sin procesar de la URL; [locale] es el idioma de la solicitud, establecido por [CookieLocaleResolver]; [model] es el modelo, que la acción puebla para la vista. La acción no declara los parámetros [doctorId] ni [day]: los lee ella misma de la solicitud ([HttpServletRequest], véase el Ejemplo 05): [request.getParameter] devuelve [null] para un parámetro ausente y una cadena vacía para un parámetro vacío ([?doctorId=]). Estos dos casos deben distinguirse (véase más adelante);
  • Líneas 11–12: el usuario conectado y sus permisos. [Utils.user] (carpeta [web]) lee la información del token (claims: ID, identificador, nombre, rol) y la convierte en un objeto [ConnectedUser];
  • líneas 15–25: la fecha solicitada, si es válida; de lo contrario, hoy. Si el parámetro [day] está ausente, devuelve hoy sin mensaje de error. Si está presente pero no es válido ([day=2026-02-30]), genera un mensaje de error. [Utils.validDate] devuelve un [Optional] (véase «La capa DAO»), que se prueba con [isPresent()] antes de extraer su valor con [get()]. Las reservas solo pueden hacerse a partir de hoy ([dayBookable]);
  • líneas 28–32: el médico solicitado. [Utils.positiveInteger] devuelve un entero estrictamente positivo, o [null] si el valor está ausente, vacío o no es válido: su tipo es [Integer], la versión «objeto» del tipo [int], que puede ser [null]. Si el parámetro [doctorId] está ausente de la URL, un médico conectado ve su propia agenda: es su página de inicio. Si está vacío ([doctorId=], la opción «choose a doctor» de la lista), no se muestra ningún calendario. Línea 31: [map(d -> d.getId())] convierte el [Optional<Doctor>] devuelto por [getDoctorByUserId] en un [Optional<Integer>], y [orElse(null)] extrae de él el valor, o [null] si está vacío;
  • líneas 35–38: las opciones de la lista desplegable de médicos, leídas de la caché de [ApplicationModel]; se selecciona la opción del médico solicitado (véase el método [option] al final del archivo). [stream()] convierte la lista en un flujo, que [map] procesa elemento por elemento y que [toList()] vuelve a convertir en una lista. [d -> option(...)] es una lambda: una función anónima, definida en el mismo lugar. Una lambda solo puede usar una variable local si esta nunca se vuelve a modificar: por eso [doctorId], modificada en la línea 31, se copia en la línea 35 en una variable [final] (que no puede modificarse). En la línea 37, los dos valores [Integer] se comparan con [equals], que compara sus valores, y no con [==], que compararía dos objetos: una trampa clásica de [Java];
  • Líneas 41–49: la agenda se calcula solo si hay un médico seleccionado y la fecha es válida. Un identificador de médico desconocido provoca un mensaje, no una página de error. El calendario calculado por la capa de negocio (un objeto [DoctorDaySchedule] de la carpeta [domain]) lo formatea el método [scheduleView], que se analiza a continuación.

11.16.2.3. La ventana de reserva y el modelo de la vista

        // el diálogo de reserva: solo si la franja solicitada es
        // reservable por este usuario
        BookingView booking = null;
        Integer slotId = Utils.positiveInteger(request.getParameter("book"));
        if (schedule != null && slotId != null) {
            Optional<ScheduleRowView> row = schedule.rows().stream()
                    .filter(r -> r.slotId() == slotId && r.bookable())
                    .findFirst();
            if (row.isPresent()) {
                booking = new BookingView(
                        row.get().slotId(),
                        row.get().time(),
                        rights.manager()
                                ? application.getAllClients().stream().map(c -> option(c, false)).toList()
                                : List.of(),
                        rights.patient() != null ? Utils.label(rights.patient()) : null);
            }
        }

        model.addAttribute("model", new ScheduleModel(
                "SCHEDULE.PAGE_TITLE",
                error == null ? null : Message.of(error),
                doctors,
                doctorId,
                Utils.iso(day),
                schedule,
                booking,
                doctorId != null ? scheduleUrl(doctorId, day, null) : "/schedule",
                patientInfo(rights, schedule)));
        return "schedule";
    }
  • líneas 3–8: la franja horaria para la cual la URL solicita una reserva ([book=7]). Debe aparecer en el calendario mostrado y poder ser reservada por este usuario: una URL creada manualmente (una franja pasada, una franja ocupada o una franja que pertenece a otro médico) no abre la ventana. [filter] conserva solo las filas que cumplen la condición, y [findFirst] devuelve la primera en un [Optional] (vacío si ninguna es adecuada);
  • líneas 9–17: el modelo de la ventana. Un gestor selecciona a un paciente de una lista (todos los clientes, leídos de la caché); un paciente hace una reserva para sí mismo: la ventana simplemente muestra su nombre. [List.of()] es una lista vacía;
  • Líneas 20–29: el modelo de la página, un [ScheduleModel] (véase [models/ViewModels.java]), almacenado en el modelo con el nombre [model]. Los argumentos del constructor del [record] se enumeran en el orden de sus campos: la clave del título de la página, el error eventual (un [Message]: una clave de traducción y sus parámetros), los médicos, el médico seleccionado, el día en el formato [yyyy-MM-dd], el calendario, la ventana de reserva, etc. [condition ? value1 : value2] es igual a [value1] si la condición es verdadera y a [value2] en caso contrario;
  • línea 28: la dirección del calendario mostrado, sin la ventana de reserva; es la dirección del botón que cierra la ventana;
  • línea 29: un mensaje informativo para los pacientes que ya tienen una cita próxima: explica por qué no ven un botón «Book». Lo calcula el método [patientInfo], al final del archivo;
  • línea 30: el nombre de la vista: [templates/schedule.html].

11.16.2.4. POST /schedule/book

    // -----------------------------------------------------------------------
    // POST /schedule/book   campos: doctorId, day, slotId, clientId
    //
    // Para un paciente (USER), el campo clientId se IGNORA: siempre reserva
    // para sí mismo. Confiar en un campo enviado por el
    // navegador permitiría a un paciente astuto reservar a nombre de otro.
    //
    // Patrón "Post / Redirect / Get": sea cual sea el resultado, no
    // construimos una página aquí - colocamos un mensaje flash y redirigimos
    // a la agenda (véase el ejemplo 20).
    // -----------------------------------------------------------------------
    @PostMapping("/book")
    @PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR', 'USER')")
    public String book(
            @RequestParam(required = false) String doctorId,
            @RequestParam(required = false) String day,
            @RequestParam(required = false) String slotId,
            @RequestParam(required = false) String clientId,
            @AuthenticationPrincipal Jwt token,
            RedirectAttributes redirect) {
        ScheduleRequest req = readScheduleRequest(doctorId, day);
        Integer sltId = Utils.positiveInteger(slotId);
        if (req == null || sltId == null) {
            // -> página de "solicitud no válida" (véase ErrorController)
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
        }
        ConnectedUser user = Utils.user(token);

        Optional<Client> client;
        if (user.isPatient()) {
            client = Optional.of(Utils.connectedPatient(application, user));
        } else {
            Integer cliId = Utils.positiveInteger(clientId);
            if (cliId == null) {
                // ningún paciente elegido: reabrimos el diálogo de reserva
                redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CHOOSE_PATIENT"));
                return "redirect:" + scheduleUrl(req.doctorId(), req.day(), sltId);
            }
            client = application.getClientById(cliId);
        }

        Optional<Slot> slot = application.getSlotById(sltId);
        FlashMessage flash;
        if (client.isEmpty()) {
            flash = FlashMessage.error("ERRORS.PATIENT_NOT_FOUND");
        } else if (slot.isEmpty() || slot.get().getDoctorId() != req.doctorId()) {
            flash = FlashMessage.error("ERRORS.SLOT_NOT_FOUND");
        } else {
            try {
                // las reglas (no en el pasado, una sola cita futura por
                // paciente, franja libre) las verifica la capa de negocio
                application.addAppointment(req.day(), slot.get(), client.get());
                flash = FlashMessage.success("SCHEDULE.BOOKED");
            } catch (BusinessException e) {
                // misma regla, pero con un mensaje en segunda persona cuando es el
                // propio paciente quien reserva ("You already have..." en lugar
                // de "This patient..."). Las demás excepciones (anomalías
                // reales) no se capturan: página 500.
                flash = e.getKey().equals("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT") && user.isPatient()
                        ? FlashMessage.error("SCHEDULE.ALREADY_BOOKED_INFO")
                        : FlashMessage.error(e.getKey(), e.getParams());
            }
        }
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
        return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
    }
  • Línea 13: [@PreAuthorize] exige, además de un usuario conectado, uno de los roles indicados (véase el Ejemplo 26). La anotación contiene una expresión, evaluada por [Spring Security] antes de invocar el método: [hasAnyRole('ADMIN', 'DOCTOR', 'USER')] es verdadera si el usuario tiene uno de estos roles. Aquí no impone ninguna restricción adicional; documenta la regla y la protegería si apareciera un cuarto rol;
  • líneas 15–18: los campos del formulario de la ventana de reserva (véase el Ejemplo 11). [@RequestParam] asocia cada parámetro del método con el campo del mismo nombre; [required = false]: un campo ausente da como resultado [null] en lugar de un error 400 de Spring (MVC). Se reciben como cadenas y luego se convierten con cuidado;
  • línea 20: [RedirectAttributes] sirve para mostrar un mensaje flash antes de una redirección (véase el ejemplo 20);
  • Líneas 21–26: el «médico» y el «día» son campos ocultos del formulario; permiten al usuario regresar al calendario mostrado. Si no son válidos, la solicitud no proviene de nuestra página: fue creada manualmente. La excepción [ResponseStatusException(HttpStatus.BAD_REQUEST)] genera una respuesta 400, que el servidor convierte en una página de error (véase [ErrorController]);
  • líneas 29–31: para un paciente, el campo [clientId] se ignora: el sistema siempre hace la reserva para el propio paciente. Confiar en este campo, que envía el navegador, permitiría a un paciente malintencionado hacer una reserva a nombre de otra persona. [Utils.connectedPatient] identifica al cliente mediante el token; [Optional.of] lo coloca en un [Optional], de modo que tenga el mismo tipo que el de la línea 39;
  • Líneas 33–38: un administrador que no ha seleccionado un paciente es redirigido a la ventana de reserva (la URL con [book]), junto con un mensaje flash de error. [addFlashAttribute] almacena el mensaje en los atributos flash, que [web/CookieFlashMapManager.java] transporta en una cookie hasta la siguiente solicitud;
  • líneas 42–47: el paciente debe existir, y la franja horaria debe existir y pertenecer al médico del calendario: no se puede reservar una franja de un médico con otro;
  • línea 52: las reglas de negocio (no en el pasado, franja disponible, una sola cita próxima por paciente) las verifica la capa de lógica de negocio, que lanza una [BusinessException] en caso de rechazo;
  • Líneas 54–62: toda [BusinessException] se convierte en un mensaje flash de error, con su clave y sus parámetros. Para un paciente, el mensaje «This patient already has an upcoming appointment» se reemplaza por un mensaje en segunda persona. Las demás excepciones no se capturan: son errores verdaderos, que dan lugar a una página de error 500. ([C#] tiene un filtro de excepciones para este caso, [catch ... when], que no existe en [Java]: la condición se verifica en el bloque [catch]);
  • Líneas 64–65: el esquema PRG: sea cual sea el resultado, se muestra un mensaje flash y se redirige al usuario al calendario, que mostrará el mensaje.

11.16.2.5. POST /schedule/cancel

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   campos: appointmentId, doctorId, day
    // (un paciente cancela SU cita desde "My area", no desde aquí)
    // -----------------------------------------------------------------------
    @PostMapping("/cancel")
    @PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR')")
    public String cancel(
            @RequestParam(required = false) String appointmentId,
            @RequestParam(required = false) String doctorId,
            @RequestParam(required = false) String day,
            RedirectAttributes redirect) {
        ScheduleRequest req = readScheduleRequest(doctorId, day);
        Integer id = Utils.positiveInteger(appointmentId);
        if (req == null || id == null) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
        }
        Optional<Appointment> appointment = application.getAppointmentById(id);
        if (appointment.isEmpty()) {
            // ya cancelada (por otra persona, o por doble clic)
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
        } else {
            application.deleteAppointment(appointment.get());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
        }
        return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
    }
  • Líneas 5–6: la cancelación está reservada a los administradores; un paciente cancela su cita desde «Mi área» (véase [PatientAreaController]). Un paciente que envíe esta solicitud recibiría una página 403: [Spring Security] rechaza la llamada al método y su manejador de rechazos (véase [SecurityConfig]) responde con un error 403, que el servidor reenvía a [/error];
  • líneas 12–16: las mismas verificaciones que para la reserva;
  • líneas 17–20: una cita que ya ha sido cancelada (por doble clic o por cancelación de otro gestor) devuelve un mensaje de error, no una página de error;
  • líneas 21–25: eliminación, seguida del esquema PRG.

Con la cookie de token de un paciente conectado (la del Sr. Jean MARTIN, que el lector copiará desde su navegador; véase «Autenticación»; aquí se abrevia como [...]), la solicitud es rechazada:

curl -i -b "rdvmedecins_jwt=..." -X POST http://localhost:8081/schedule/cancel -d "appointmentId=1&doctorId=1&day=2026-09-25"
1
2
3
4
5
6
7
8
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

11.16.2.6. Permisos, el calendario formateado y funciones utilitarias

    // -----------------------------------------------------------------------
    // ¿quién está conectado y qué puede hacer en esta página?
    // -----------------------------------------------------------------------
    private Rights rights(ConnectedUser user) {
        if (!user.isPatient()) {
            return new Rights(true, null, false);
        }
        Client patient = Utils.connectedPatient(application, user);
        List<Appointment> upcoming = application.getClientUpcomingAppointments(patient.getId());
        return new Rights(false, patient, upcoming.isEmpty());
    }

    // -----------------------------------------------------------------------
    // la agenda del médico, formateada para la vista - y filtrada según los permisos
    // -----------------------------------------------------------------------
    private ScheduleView scheduleView(DoctorDaySchedule doctorSchedule, Rights rights, boolean dayBookable,
            Locale locale) {
        int doctorId = doctorSchedule.doctor().getId();
        LocalDate day = doctorSchedule.day();
        List<ScheduleRowView> rows = doctorSchedule.doctorDaySlots().stream().map(dds -> {
            Slot slot = dds.slot();
            Appointment appointment = dds.appointment();
            boolean free = appointment == null;
            // ¿la cita del paciente conectado?
            boolean mine = appointment != null && rights.patient() != null && appointment.getClientId().equals(rights.patient().getId());
            return new ScheduleRowView(
                    slot.getId(),
                    Utils.time(slot),
                    free,
                    // EL punto de confidencialidad: un paciente recibe el nombre solo
                    // de SU cita; para las demás, null (la vista muestra "Booked")
                    appointment != null && (rights.manager() || mine) ? Utils.label(appointment.getClient()) : null,
                    mine,
                    free && dayBookable && (rights.manager() || rights.patientCanBook()),
                    scheduleUrl(doctorId, day, slot.getId()),
                    appointment != null && rights.manager() ? appointment.getId() : null);
        }).toList();
        return new ScheduleView(Utils.label(doctorSchedule.doctor()), Utils.formatDay(day, locale), rows);
    }

    // ----------------------------------------------------------------- funciones utilitarias

    // los campos ocultos doctorId / day de los formularios POST; null si no son válidos
    private static ScheduleRequest readScheduleRequest(String rawDoctorId, String rawDay) {
        Integer doctorId = Utils.positiveInteger(rawDoctorId);
        Optional<LocalDate> day = Utils.validDate(rawDay);
        return doctorId == null || day.isEmpty() ? null : new ScheduleRequest(doctorId, day.get());
    }

    private static String scheduleUrl(int doctorId, LocalDate day, Integer book) {
        String url = "/schedule?doctorId=" + doctorId + "&day=" + Utils.iso(day);
        return book == null ? url : url + "&book=" + book;
    }

    private static OptionView option(Person p, boolean selected) {
        return new OptionView(p.getId(), Utils.label(p), selected);
    }

    // -----------------------------------------------------------------------
    // el mensaje informativo de un paciente que ya tiene una cita futura
    // (por qué no hay botón "Book"), o null. Inútil si SU
    // cita aparece en la agenda mostrada (en azul): es el caso justo
    // después de haberla reservado, cuando el mensaje estaría fuera de lugar.
    // -----------------------------------------------------------------------
    private static String patientInfo(Rights rights, ScheduleView schedule) {
        if (rights.patient() == null || rights.patientCanBook()) {
            return null;
        }
        boolean appointmentShown = schedule != null && schedule.rows().stream().anyMatch(ScheduleRowView::mine);
        return appointmentShown ? null : "SCHEDULE.ALREADY_BOOKED_INFO";
    }
}
  • líneas 4–11: un administrador tiene todos los permisos; un paciente puede hacer una reserva si no tiene citas próximas;
  • líneas 16–17: el calendario calculado por la capa de negocio se convierte en elementos de un arreglo, uno por franja horaria ([ScheduleRowView]);
  • línea 20: la función lambda que se pasa a [map] abarca aquí varias líneas: su cuerpo es un bloque encerrado entre llaves, que termina con un [return];
  • línea 25: [mine] determina si la cita pertenece al paciente conectado;
  • línea 28: la vista recibe solo datos ya formateados ([8:00 - 8:20]); ya no tiene nada que calcular;
  • línea 32: el control de privacidad de la aplicación. El nombre del paciente se incluye en el modelo solo para un administrador o para el paciente a quien pertenece la cita. Para todos los demás, el modelo contiene [null], y la vista muestra «Booked». El nombre no está simplemente oculto por la vista: nunca se envía al navegador, y «Ver código fuente de la página» no lo revelaría;
  • líneas 34–36: lo que la vista debe mostrar, según lo determina el controlador: el botón «Book» (franja disponible, fecha no pasada y usuario autorizado a reservar), su enlace (la URL de la página, junto con [book]) y el botón «Cancel» ([appointmentId] solo tiene valor para un administrador). La vista no toma ninguna decisión: sigue estas instrucciones;
  • línea 38: la agenda completa: el médico, el día, formateado en el idioma de la solicitud («Friday 25 September 2026»), las filas;
  • líneas 44–48: los valores de los dos campos ocultos comunes a los formularios POST: un [ScheduleRequest], o [null] si no son válidos;
  • líneas 50–53: la URL de la agenda de un médico en un día determinado, posiblemente con la ventana de reserva abierta. Todas las redirecciones del controlador la generan mediante este método: las URL de la página se escriben en un solo lugar;
  • líneas 55–57: una opción de lista desplegable (ID, etiqueta, selección), tanto para médicos como para clientes: el parámetro es de tipo [Person], la clase padre de ambas entidades;
  • Líneas 59–71: el mensaje informativo para el paciente que ya tiene una cita próxima. No se envía si esa cita aparece en el calendario mostrado: el nombre del paciente en azul es suficiente, y esta es precisamente la página que el paciente ve inmediatamente después de reservar, donde el mensaje «You already have an upcoming appointment» estaría fuera de lugar. Línea 69: [anyMatch] indica si al menos una línea del flujo cumple la condición; [ScheduleRowView::mine] es una referencia a método: el equivalente de la lambda [r -> r.mine()].

Esto es lo que recibe el navegador del Sr. Jean (rol USER) para el calendario de la Sra. PELISSIER, que tiene dos franjas horarias reservadas (extracto):

curl -b "rdvmedecins_jwt=..." "http://localhost:8081/schedule?doctorId=1&day=2026-09-26"
  <div class="card p-3">
    <h5>Schedule for Saturday 26 September 2026 - Mme Marie PELISSIER</h5>
...
        <tr>
          <td>8:20 - 8:40</td>
          <td>
            <span class="badge text-bg-secondary">Booked</span>
          </td>
          <td>
          </td>
        </tr>
...
        <tr>
          <td>9:00 - 9:20</td>
          <td>
            <span class="badge text-bg-primary">Mr Jean MARTIN</span>
          </td>
          <td>
          </td>
        </tr>

La franja de las 8:20 a.m. está reservada por otro paciente: su nombre no aparece en ninguna parte de la página. La franja de las 9:00 a.m. es la cita del Sr. MARTIN: su nombre aparece en azul. Como ya tiene una cita próxima, no se muestra ningún botón «Book». El mensaje informativo («You already have an upcoming appointment...») no aparece aquí, ya que esta cita está justo frente a él; aparece en el calendario de otro día o de otro médico para explicar la ausencia de botones.

11.16.3. controllers/PersonsControllerBase.java

// =========================================================================
// controllers/PersonsControllerBase.java
// -------------------------------------------------------------------------
// La gestión de los médicos y la de los clientes (reservada al ADMIN) son
// IDÉNTICAS: misma lista, mismo formulario, mismas reglas. En lugar de
// escribir dos veces las mismas acciones, las escribimos una sola vez en esta
// clase ABSTRACTA y GENÉRICA, de la que heredan DoctorsController
// (@RequestMapping("/doctors")) y ClientsController
// (@RequestMapping("/clients")). A cada subclase solo le queda proporcionar su
// "configuración": qué métodos llamar, qué etiquetas mostrar.
//
// Las rutas definidas AQUÍ (@GetMapping("/add")...) se heredan y
// completan la ruta de la subclase. Obtenemos así, para cada una:
//
//   GET  /doctors                    lista
//   GET  /doctors/add                formulario vacío
//   POST /doctors/add                creación
//   GET  /doctors/{id}/edit          formulario prellenado
//   POST /doctors/{id}/edit          edición
//   POST /doctors/{id}/delete        eliminación
//
// (y las mismas URL bajo /clients). Las vistas también son comunes:
// templates/persons/list.html y templates/persons/form.html.
//
// Una clase abstracta nunca es un bean: solo sus subclases concretas,
// anotadas con @Controller, son controladores.
//
// SEGURIDAD: @PreAuthorize("hasRole('ADMIN')") se coloca en ESTA clase,
// y no en las subclases. Para decidir qué regla se aplica a una
// acción, Spring Security mira la anotación del método y luego la de
// la clase que DECLARA el método - aquí, PersonsControllerBase. Si se pusiera
// solo en DoctorsController, la anotación se ignoraría para las acciones
// heredadas: ¡un USER podría abrir /doctors!
// =========================================================================
package rdvmedecins.controllers;

import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.Supplier;

import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.validation.Valid;
import rdvmedecins.entities.Person;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.PersonForm;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.PersonFormModel;
import rdvmedecins.models.ViewModels.PersonListModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;

@PreAuthorize("hasRole('ADMIN')")
public abstract class PersonsControllerBase<T extends Person> {

    // -----------------------------------------------------------------------
    // lo que cada subclase debe proporcionar. Los últimos cinco campos son
    // FUNCIONES (interfaces funcionales de java.util.function): la
    // subclase almacena en ellos referencias a métodos, application::getAllDoctors...
    // -----------------------------------------------------------------------
    protected record PersonsConfig<T>(
            String url, // "/doctors" o "/clients"
            PersonKeys keys,
            Supplier<List<T>> list, // () -> lista
            Function<Integer, Optional<T>> find, // id -> persona
            Function<PersonData, T> add, // data -> persona creada
            BiFunction<Integer, PersonData, T> edit, // (id, data) -> persona editada
            IntConsumer delete) { // id -> nada
    }

    protected abstract PersonsConfig<T> config();

    // las vistas comunes
    private static final String LIST_VIEW = "persons/list";
    private static final String FORM_VIEW = "persons/form";

    // -----------------------------------------------------------------------
    // GET /doctors (o /clients)
    // -----------------------------------------------------------------------
    @GetMapping
    public String list(Model model) {
        PersonsConfig<T> config = config();
        List<PersonView> persons = config.list().get().stream()
                .map(p -> new PersonView(p.getTitle(), p.getFirstName(), p.getLastName(), login(p),
                        config.url() + "/" + p.getId() + "/edit",
                        config.url() + "/" + p.getId() + "/delete"))
                .toList();
        model.addAttribute("model", new PersonListModel(config.keys().title(), null, config.keys(),
                config.url() + "/add", persons));
        return LIST_VIEW;
    }

    // -----------------------------------------------------------------------
    // GET /doctors/add
    // -----------------------------------------------------------------------
    @GetMapping("/add")
    public String addForm(Model model) {
        return showForm(model, null, PersonValues.empty(), Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /doctors/add
    // Spring MVC (@Valid) ha llenado Y validado [form]: el
    // BindingResult que lo sigue indica si la entrada es correcta.
    // -----------------------------------------------------------------------
    @PostMapping("/add")
    public String add(@Valid PersonForm form, BindingResult result, Model model,
            RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return showForm(model, null, enteredValues(form), Validation.errorsOf(result),
                    null, null);
        }
        try {
            T person = config().add().apply(data(form));
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.success(config().keys().added(), messageParams(person)));
            return "redirect:" + config().url();
        } catch (BusinessException e) {
            return showBusinessError(model, redirect, null, enteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id:\d+}: el id debe estar formado por dígitos - /doctors/abc/edit
    // no coincide con ninguna ruta (página 404)
    // -----------------------------------------------------------------------
    @GetMapping("/{id:\\d+}/edit")
    public String editForm(@PathVariable int id, Model model) {
        T person = config().find().apply(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
        PersonValues values = new PersonValues(person.getTitle(), person.getFirstName(), person.getLastName(),
                login(person), person.getVersion());
        return showForm(model, id, values, Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -----------------------------------------------------------------------
    @PostMapping("/{id:\\d+}/edit")
    public String edit(@PathVariable int id, @Valid PersonForm form, BindingResult result,
            Model model, RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return showForm(model, id, enteredValues(form), Validation.errorsOf(result),
                    null, null);
        }
        try {
            T person = config().edit().apply(id, data(form));
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.success(config().keys().edited(), messageParams(person)));
            return "redirect:" + config().url();
        } catch (BusinessException e) {
            return showBusinessError(model, redirect, id, enteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (la confirmación "Are you sure?" se solicita antes de enviar el formulario,
    // véase static/js/app.js)
    // -----------------------------------------------------------------------
    @PostMapping("/{id:\\d+}/delete")
    public String delete(@PathVariable int id, RedirectAttributes redirect) {
        Optional<T> person = config().find().apply(id);
        FlashMessage flash;
        try {
            config().delete().accept(id);
            flash = FlashMessage.success(config().keys().deleted(), messageParams(person.orElse(null)));
        } catch (BusinessException e) {
            flash = FlashMessage.error(e.getKey(), e.getParams());
        }
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
        return "redirect:" + config().url();
    }

    // ----------------------------------------------------------------- métodos privados

    // id null: formulario de creación; si no: formulario de edición.
    // errors: campo -> clave del mensaje; error: el mensaje en la parte inferior de la página;
    // otherFields: campos adicionales que se resaltan en rojo
    private String showForm(Model model, Integer id, PersonValues values,
            Map<String, String> errors, String error, List<String> otherFields) {
        PersonsConfig<T> config = config();
        boolean creating = id == null;
        FormState state = Validation.state(errors, otherFields);
        model.addAttribute("model", new PersonFormModel(
                creating ? config.keys().add() : config.keys().edit(),
                Validation.pageMessage(errors, error == null ? null : Message.of(error)),
                values,
                state,
                creating,
                creating ? config.url() + "/add" : config.url() + "/" + id + "/edit",
                config.url()));
        return FORM_VIEW;
    }

    // una regla de negocio rechazó la escritura: mostramos de nuevo el formulario,
    // con lo digitado por el usuario y el mensaje de la capa de negocio
    private String showBusinessError(Model model, RedirectAttributes redirect, Integer id,
            PersonValues values, BusinessException e) {
        if (e.getKey().equals("ERRORS.DOCTOR_NOT_FOUND") || e.getKey().equals("ERRORS.PATIENT_NOT_FOUND")) {
            // eliminado entre tanto por otro ADMIN: de vuelta a la lista
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error(e.getKey()));
            return "redirect:" + config().url();
        }
        // el mensaje va en la parte inferior de la página; los campos afectados, si los hay,
        // se resaltan en rojo para que el usuario vea de inmediato qué corregir
        return showForm(model, id, values, Map.of(), e.getKey(),
                Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
    }

    // lo que digitó el usuario (contraseña excluida: nunca la enviamos
    // de vuelta al navegador)
    private static PersonValues enteredValues(PersonForm f) {
        return new PersonValues(
                f.getTitle() == null ? "" : f.getTitle(),
                f.getFirstName() == null ? "" : f.getFirstName(),
                f.getLastName() == null ? "" : f.getLastName(),
                f.getLogin() == null ? "" : f.getLogin(),
                f.getVersion());
    }

    // el formulario validado -> los datos esperados por la capa de negocio
    private static PersonData data(PersonForm f) {
        return new PersonData(f.getTitle(), f.getLastName(), f.getFirstName(), f.getLogin(), f.getPassword(),
                f.getVersion());
    }

    // {name} y {login} de los mensajes "added / edited / deleted"
    private static Map<String, String> messageParams(Person person) {
        return person == null
                ? Map.of("name", "", "login", "")
                : Map.of("name", person.getFirstName() + " " + person.getLastName(), "login", login(person));
    }

    private static String login(Person p) {
        return p.getUser() == null ? "" : p.getUser().getLogin();
    }
}

La gestión de médicos y de clientes es idéntica. En lugar de escribir dos controladores similares, escribimos sus acciones una sola vez, en una clase padre abstracta y genérica. Comentemos este código:

  • líneas 15–20: las rutas generadas para los médicos; las mismas existen en [/clients];
  • líneas 22–23: las vistas también se comparten (carpeta [templates/persons]);
  • líneas 25–26: la clase no está anotada con [@Controller] y, al ser abstracta, de todos modos no podría instanciarse: solo sus subclases [DoctorsController] y [ClientsController] son beans y reciben solicitudes;
  • Líneas 28–33 y línea 70: la restricción a los roles ADMIN y [@PreAuthorize("hasRole('ADMIN')")] se aplica a esta clase. Cuando se aplica a una clase, la anotación se aplica a todos sus métodos. Sin embargo, para determinar qué regla se aplica a una acción, [Spring Security] comprueba la anotación del método y luego la de la clase que declara el método. Ahora bien, las acciones [list], [add]... se declaran aquí, en [PersonsControllerBase], y solo las hereda [DoctorsController]. Si se aplicara a [DoctorsController], la anotación se ignoraría para ellas: un paciente (USER) podría abrir [/doctors]. Esto difiere de [ASP.NET Core MVC], donde el atributo [[Authorize(Roles = "ADMIN")]] de una subclase también se aplica a las acciones heredadas;
  • línea 71: la clase es abstracta ([abstract]: no se puede crear un objeto de ella; existe únicamente para derivar de ella) y genérica: [T] es un parámetro de tipo, que cada subclase reemplaza por [Doctor] o [Client]. [T extends Person] es una restricción: [T] debe ser [Person] o una de sus clases derivadas; por lo tanto, el código puede usar [p.getFirstName()] o [p.getUser()], que son comunes a todas las personas;
  • Líneas 78–86: la configuración que proporciona cada subclase, en forma de [record]: la URL base, los textos (claves de traducción, agrupadas en el [record], [PersonKeys], y [models/ViewModels.java]) y cinco funciones que se deben invocar para listar, buscar, agregar, modificar y eliminar. Una función almacenada en una variable tiene un tipo que es una interfaz funcional del paquete [java.util.function] (véase «La capa de negocio»): [Supplier<R>] (sin parámetros, devuelve un [R], método [get]), [Function<P, R>] (un parámetro: [P]; devuelve un [R]; método: [apply]), [BiFunction<P1, P2, R>] (dos parámetros), [IntConsumer] (un [int]; no devuelve nada; método [accept]). [protected]: [record] solo es visible para la clase y sus subclases (y el paquete);
  • línea 88: un método abstracto: cada subclase debe implementarlo para especificar su configuración;
  • líneas 91–92: las dos vistas, designadas por su ruta en la carpeta [templates];
  • líneas 97–108: la lista. Las anotaciones de enrutamiento aplicadas a los métodos de una clase padre se heredan: combinadas con el [@RequestMapping("/doctors")] de la subclase, dan como resultado [GET /doctors]. [config.list().get()] invoca la función especificada en la configuración. Para cada persona, el modelo contiene los valores de URL de sus botones Edit y Delete;
  • líneas 113–116: el formulario vacío. [Map.of()] es un diccionario vacío: ningún error;
  • Líneas 123–138: el alta, en tres pasos, como en el Ejemplo 28. Spring MVC pobló el parámetro [form] con los campos enviados, y luego lo validó según sus anotaciones ([@NotBlank], [@Size]..., véase [models/Forms.java]) porque está anotado como [@Valid] (véase el Ejemplo 19). El resultado de la validación se encuentra en el parámetro [BindingResult], que le sigue inmediatamente: una entrada no válida vuelve a mostrar el formulario, con los valores introducidos y un mensaje debajo de cada campo incorrecto; una entrada válida se pasa a la capa de negocio y luego se redirige el navegador a la lista, con un mensaje flash (PRG); un rechazo de la capa de negocio (un nombre duplicado, un identificador ya en uso) vuelve a mostrar el formulario;
  • Líneas 145–152: el formulario de edición, rellenado previamente. [{id:\\d+}] es una variable de ruta asociada a una expresión regular: el identificador debe estar formado por dígitos ([\d+], con [\] duplicada en la cadena [Java]). [/doctors/abc/edit] no corresponde, por lo tanto, a ninguna ruta, lo que da como resultado una página 404. Un usuario inexistente también da como resultado un 404: [orElseThrow] obtiene el valor del [Optional] o, si está vacío, lanza la excepción generada por la lambda. El número de versión, un campo oculto del formulario, se utilizará para el bloqueo optimista (véase el Ejemplo 28);
  • líneas 157–172: la actualización, que sigue el mismo patrón que la inserción;
  • líneas 179–191: eliminación. La persona se obtiene de antemano para mostrar su nombre en el mensaje de éxito ([orElse(null)]: la persona, o [null] si no existía). Un rechazo de la capa de negocio (un médico que tiene citas) da lugar a un mensaje flash de error en la página de la lista;
  • Líneas 198–212: el formulario, tanto para la creación ([id] equivale a [null]) como para la modificación: solo cambian el título y la dirección postal. [Validation.state] y [Validation.pageMessage] (carpeta [web]) preparan los errores por campo, los campos que se resaltarán en rojo y el mensaje de la parte inferior de la página;
  • líneas 216–227: una persona que ha sido eliminada entretanto (por otro administrador) se muestra en la lista; los demás errores de negocio vuelven a mostrar el formulario, con el mensaje del pie de página y los campos correspondientes resaltados en rojo ([Validation.BUSINESS_ERROR_FIELDS] asocia cada código de error con sus campos correspondientes: [firstName] y [lastName] para un homónimo);
  • líneas 231–238: los valores que se deben volver a mostrar, nunca la contraseña;
  • líneas 241–244: los datos transmitidos a la capa de negocio;
  • líneas 247–251: los parámetros [{name}] y [{login}] de los mensajes de éxito: el nombre y el apellido de la persona, y su identificador;
  • líneas 253–255: el identificador de la cuenta asociada (una cadena vacía si faltaba la cuenta, como precaución: todos tienen una cuenta).

11.16.4. controllers/DoctorsController.java

// =========================================================================
// controllers/DoctorsController.java
// -------------------------------------------------------------------------
// Gestión de los médicos (solo rol ADMIN). Todas las acciones se
// heredan de PersonsControllerBase: aquí solo queda indicar QUÉ
// llamar y QUÉ etiquetas mostrar.
//
// La restricción al rol ADMIN se coloca en la clase padre (véase el
// comentario "SECURITY" de PersonsControllerBase).
// =========================================================================
package rdvmedecins.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import rdvmedecins.entities.Doctor;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;

@Controller
@RequestMapping("/doctors")
public class DoctorsController extends PersonsControllerBase<Doctor> {

    private final PersonsConfig<Doctor> config;

    public DoctorsController(ApplicationModel application) {
        // application::getAllDoctors: una "referencia a método", el
        // método getAllDoctors del objeto application, almacenado en una variable
        this.config = new PersonsConfig<>(
                "/doctors",
                new PersonKeys(
                        "DOCTORS.TITLE",
                        "DOCTORS.ADD",
                        "DOCTORS.EDIT",
                        "DOCTORS.EMPTY",
                        "DOCTORS.DELETE_CONFIRM",
                        "DOCTORS.ADDED",
                        "DOCTORS.UPDATED",
                        "DOCTORS.DELETED"),
                application::getAllDoctors,
                application::getDoctorById,
                application::addDoctor,
                application::editDoctor,
                application::deleteDoctor);
    }

    @Override
    protected PersonsConfig<Doctor> config() {
        return config;
    }
}
  • líneas 8–9: la restricción al rol ADMIN la lleva la clase padre, por la razón explicada antes;
  • líneas 20–22: un controlador ([@Controller]) cuyas rutas comienzan todas con [/doctors]. Hereda ([extends]) de [PersonsControllerBase<Doctor>]: el tipo [T] de la clase padre pasa a ser [Doctor];
  • líneas 26–45: el constructor recibe [ApplicationModel] mediante inyección y crea la configuración de una vez por todas: la URL base y las claves de traducción específicas de los médicos;
  • líneas 40–44: las funciones que se deben invocar, que son métodos de ***[ApplicationModel]***. ***[application::getAllDoctors] es una *referencia a método: no invoca el método; hace referencia a él. El compilador la convierte en un valor de la interfaz funcional que espera [record] ([Supplier<List<Doctor>>] para la primera), cuyo método [get] invocará [application.getAllDoctors()]. Es una notación abreviada de la lambda [() -> application.getAllDoctors()];
  • línea 29: [new PersonsConfig<>(...)]: el operador [<>], conocido como operador «diamante», permite al compilador inferir el tipo genérico ([Doctor]);
  • Líneas 47–50: el método abstracto de la clase padre, escrito aquí con [@Override], indica al compilador que verifique que efectivamente redefine un método de la clase padre.

Como vimos con la autenticación, un paciente que solicita [/doctors] recibe una página 403: la protección establecida en la clase padre funciona, por lo tanto. Observamos también que la barra de navegación de esta página de error muestra al usuario (véase el método [currentUser] de [auth/AuthService.java]). Con la cookie de token del Sr. Jean MARTIN (rol USER):

curl -i -b "rdvmedecins_jwt=..." http://localhost:8081/doctors
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <span class="badge text-bg-light text-primary">USER</span>
      <span class="text-white">Jean MARTIN</span>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

11.16.5. controllers/ClientsController.java

// =========================================================================
// controllers/ClientsController.java
// -------------------------------------------------------------------------
// Gestión de los clientes (los PACIENTES del consultorio), solo rol ADMIN.
// Mismo principio que DoctorsController (véanse sus comentarios).
// =========================================================================
package rdvmedecins.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import rdvmedecins.entities.Client;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;

@Controller
@RequestMapping("/clients")
public class ClientsController extends PersonsControllerBase<Client> {

    private final PersonsConfig<Client> config;

    public ClientsController(ApplicationModel application) {
        this.config = new PersonsConfig<>(
                "/clients",
                new PersonKeys(
                        "CLIENTS.TITLE",
                        "CLIENTS.ADD",
                        "CLIENTS.EDIT",
                        "CLIENTS.EMPTY",
                        "CLIENTS.DELETE_CONFIRM",
                        "CLIENTS.ADDED",
                        "CLIENTS.UPDATED",
                        "CLIENTS.DELETED"),
                application::getAllClients,
                application::getClientById,
                application::addClient,
                application::editClient,
                application::deleteClient);
    }

    @Override
    protected PersonsConfig<Client> config() {
        return config;
    }
}

El mismo controlador, para los clientes: otra ruta (líneas 16–18), otras claves de traducción, otros métodos de [ApplicationModel] (líneas 34–38).

11.16.6. controllers/RegistrationController.java

// =========================================================================
// controllers/RegistrationController.java
// -------------------------------------------------------------------------
// "Create a client account": un paciente que todavía no tiene cuenta
// la crea él mismo. Rutas NO protegidas (todavía no se tiene cuenta, por
// definición):
//
//   POST /register/access     botón "Create a client account" de la
//                             página de autenticación: verifica el captcha de
//                             ESTA página y luego abre el formulario
//   GET  /register            el formulario
//   POST /register            la creación y luego de vuelta a la página de inicio de sesión
//
// El flujo está protegido contra robots por UN solo captcha, el de la
// página de autenticación:
//   1. el botón "Create a client account" envía el formulario de inicio de sesión
//      a /register/access; si el captcha se copió correctamente, el servidor
//      emite un pase (véase auth/RegistrationPassService.java);
//   2. sin un pase válido, /register devuelve a la página de
//      autenticación - digitar la URL directamente no sirve de nada;
//   3. el pase se consume al crear la cuenta: un captcha resuelto
//      permite crear UNA cuenta;
//   4. además, el número de cuentas creadas por hora y por dirección IP está
//      limitado (véase auth/AttemptLimiterService.java).
//
// La cuenta creada es exactamente la que crearía el ADMIN desde la
// página "Clients" (mismo método de la capa de negocio: addClient), salvo
// que el paciente ELIGE su login y su contraseña (obligatorios,
// con confirmación).
// =========================================================================
package rdvmedecins.controllers;

import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.CookieValue;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import org.springframework.web.util.UriUtils;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.RegistrationPassService;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.RegistrationForm;
import rdvmedecins.models.ViewModels.RegistrationModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;

@Controller
@RequestMapping("/register")
public class RegistrationController {

    private final ApplicationModel application;
    private final CaptchaService captchaService;
    private final AttemptLimiterService limiter;
    private final RegistrationPassService passes;

    public RegistrationController(ApplicationModel application, CaptchaService captchaService,
            AttemptLimiterService limiter, RegistrationPassService passes) {
        this.application = application;
        this.captchaService = captchaService;
        this.limiter = limiter;
        this.passes = passes;
    }

    // -----------------------------------------------------------------------
    // POST /register/access   campos: captchaId, captcha (los de la
    // página de autenticación; login y password, enviados también, se ignoran)
    // -----------------------------------------------------------------------
    @PostMapping("/access")
    public String access(@RequestParam(required = false) String captchaId,
            @RequestParam(required = false) String captcha,
            HttpServletRequest request, HttpServletResponse response, RedirectAttributes redirect) {
        String ip = AuthController.ipAddress(request);

        // demasiadas cuentas creadas recientemente desde esta dirección: no vale la pena continuar
        long minutes = limiter.registrationBlockMinutes(ip);
        if (minutes > 0) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.error("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))));
            return "redirect:/login";
        }

        // captcha ausente o incorrecto: de vuelta a la página de autenticación, con
        // una nueva imagen (un fallo cuenta como fallo de inicio de sesión)
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, "");
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
            return "redirect:/login";
        }

        // captcha correcto: emitimos el pase y abrimos el formulario
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.cookie(passes.issue()).toString());
        return "redirect:/register";
    }

    // -----------------------------------------------------------------------
    // GET /register
    // @CookieValue: el valor de la cookie con ese nombre (null si está ausente)
    // -----------------------------------------------------------------------
    @GetMapping
    public String form(@CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
            Model model, RedirectAttributes redirect) {
        if (!passes.isValid(pass)) {
            return backToLogin(redirect);
        }
        return show(model, PersonValues.empty(), Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /register
    // El parámetro [form] lo llena y lo VALIDA Spring MVC antes de
    // la llamada: el resultado de la validación está en [result].
    // -----------------------------------------------------------------------
    @PostMapping
    public String create(@Valid RegistrationForm form, BindingResult result,
            @CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
            HttpServletRequest request, HttpServletResponse response, Model model,
            RedirectAttributes redirect) {
        if (!passes.isValid(pass)) {
            return backToLogin(redirect);
        }
        String ip = AuthController.ipAddress(request);
        PersonValues values = new PersonValues(
                form.getTitle() == null ? "Mr" : form.getTitle(),
                form.getFirstName() == null ? "" : form.getFirstName(),
                form.getLastName() == null ? "" : form.getLastName(),
                form.getLogin() == null ? "" : form.getLogin(),
                null);

        // 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
        long minutes = limiter.registrationBlockMinutes(ip);
        if (minutes > 0) {
            return show(model, values, Map.of(),
                    new Message("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))), null);
        }

        // 2. todos los errores de entrada a la vez (campos + confirmación):
        //    el usuario los corrige todos de una sola vez
        Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
        if (!errors.containsKey("password") && !errors.containsKey("confirmation")
                && !form.getPassword().equals(form.getConfirmation())) {
            errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
        }
        if (!errors.isEmpty()) {
            return show(model, values, errors, null, null);
        }

        // 3. la creación (cliente + cuenta USER, en una transacción)
        try {
            application.addClient(new PersonData(form.getTitle(), form.getLastName(),
                    form.getFirstName(), form.getLogin(), form.getPassword(), null));
        } catch (BusinessException e) {
            // login o nombre + apellido ya ocupados: el pase sigue siendo válido
            return show(model, values, Map.of(), Message.of(e.getKey()),
                    Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
        }

        // 4. el pase se ha usado: no permitirá crear una 2.ª cuenta
        passes.consume(pass);
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.clearedCookie().toString());
        limiter.registrationSuccess(ip);

        // 5. de vuelta a la página de inicio de sesión, con el login prellenado
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                FlashMessage.success("REGISTRATION.DONE", Map.of("login", form.getLogin())));
        return "redirect:/login?login=" + UriUtils.encodeQueryParam(form.getLogin(), StandardCharsets.UTF_8);
    }

    // ----------------------------------------------------------------- métodos privados

    // ningún pase válido: de vuelta a la página de autenticación
    private static String backToLogin(RedirectAttributes redirect) {
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
        return "redirect:/login";
    }

    // el formulario; nunca se devuelve una contraseña al navegador
    private static String show(Model model, PersonValues values, Map<String, String> errors,
            Message error, List<String> otherFields) {
        model.addAttribute("model", new RegistrationModel("REGISTRATION.TITLE",
                Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
        return "registration";
    }
}

Comentemos este código:

  • líneas 14–24: protección contra bots, en cuatro pasos. El CAPTCHA y el limitador de intentos se trataron en el Ejemplo 27 junto con la autenticación;
  • líneas 66–81: las rutas [/register...] se declaran públicas en [SecurityConfig] ([permitAll()]), y el controlador no tiene anotaciones ([@PreAuthorize]): sus páginas están abiertas a todos. Recibe cuatro servicios mediante inyección;
  • líneas 87–90: el botón «Crear una cuenta de paciente» de la página de inicio de sesión envía el formulario de inicio de sesión a esta dirección (atributo [formaction]; véase el ejemplo 21). Solo se leen los campos del CAPTCHA;
  • línea 91: la dirección IP del navegador, mediante un método estático de [AuthController];
  • líneas 94–99: demasiadas cuentas creadas desde esta dirección durante la última hora: redirige a la página de inicio de sesión, con una ventana emergente que indica el número de minutos que hay que esperar. [Map.of("minutes", ...)] genera el diccionario de parámetros del mensaje;
  • líneas 103–107: un CAPTCHA ausente o incorrecto cuenta como un intento fallido de inicio de sesión (con un nombre de usuario vacío): un bot no puede seguir intentándolo indefinidamente. Al volver a la página de inicio de sesión se muestra una imagen nueva;
  • líneas 110–111: el CAPTCHA es correcto: un token (véase [auth/RegistrationPassService.java]) se almacena en una cookie mediante un encabezado [Set-Cookie] agregado a la respuesta, y el navegador es redirigido al formulario;
  • líneas 118–125: el formulario, pero solo con un token válido. Escribir directamente la dirección [/register] no produce ningún efecto. [@CookieValue] enlaza el parámetro [pass] con el valor de la cookie que tiene ese nombre ([null] si está ausente, gracias a [required = false]);
  • líneas 132–136: creación. Spring MVC enlazó y validó el formulario [RegistrationForm] (carpeta [models]) ([@Valid]), y el resultado se almacena en [result];
  • líneas 137–139: el token se verifica de nuevo: la solicitud POST pudo haberse enviado sin pasar por el formulario;
  • líneas 141–146: los valores que se volverán a mostrar en caso de error, sin la contraseña. El título predeterminado es [Mr];
  • líneas 149–153: el límite de tiempo, verificado de nuevo en el momento de la creación;
  • líneas 157–164: errores de entrada, campo por campo (véase el ejemplo 19). [Validation.errorsOf] los compila en un diccionario (campo, clave de mensaje), copiado en un [HashMap] para poder completarlo. La coincidencia entre la contraseña y su confirmación, que involucra dos campos, se verifica aquí manualmente; solo se prueba si esos dos campos son correctos por separado. Todos los errores se informan juntos: el usuario los corrige todos a la vez;
  • líneas 167–174: creación del cliente y de su cuenta USER, mediante el método de la capa de negocio utilizado por ADMIN. Si un nombre de usuario o una combinación de nombre y apellido ya está en uso, el formulario se vuelve a mostrar con los campos correspondientes resaltados en rojo; el token sigue siendo válido;
  • líneas 177–179: el token ha sido utilizado: se consume en el lado del servidor y se elimina su cookie. La creación se cuenta finalmente para el límite por hora;
  • líneas 182–184: regreso a la página de inicio de sesión, con el nombre de usuario ya completado, junto con un mensaje de éxito. [UriUtils.encodeQueryParam] codifica el nombre de usuario para poder incluirlo en una URL;
  • líneas 190–193: sin un pase, regreso a la página de inicio de sesión con un mensaje;
  • líneas 196–201: el formulario, preparado por [Validation], similar a los de los médicos y los clientes. Un método declarado [static] no utiliza ningún campo del objeto; puede llamarse sin él.

11.16.7. controllers/PatientAreaController.java

// =========================================================================
// controllers/PatientAreaController.java
// -------------------------------------------------------------------------
// Las páginas PERSONALES del paciente (rol USER), las que ve justo
// después de iniciar sesión:
//
//   GET  /my-area                  página de inicio: [Manage my account],
//                                  [View a schedule], y su próxima cita
//   POST /my-area/cancel           cancela SU cita
//   GET  /my-account               formulario de edición de su cuenta
//   POST /my-account               edición
//   POST /my-account/delete        eliminación de la cuenta (y de sus citas)
//
// Regla de oro de este controlador: el paciente afectado es SIEMPRE el del
// token (Utils.connectedPatient), nunca un identificador enviado por el
// navegador. Por tanto, un paciente no puede ver, ni editar, ni cancelar lo que
// pertenece a otro paciente, ni siquiera construyendo él mismo sus solicitudes.
//
// Cualquier edición o eliminación de la cuenta exige la contraseña
// ACTUAL: alguien que encontrara una sesión abierta no podría
// cambiar la contraseña ni eliminar la cuenta. Los errores de la contraseña
// actual se cuentan como fallos de inicio de sesión (mismo límite).
// =========================================================================
package rdvmedecins.controllers;

import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.MyAccountForm;
import rdvmedecins.models.ViewModels.AreaModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.MyAccountModel;
import rdvmedecins.models.ViewModels.AppointmentView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;
import rdvmedecins.web.Validation;

@Controller
@PreAuthorize("hasRole('USER')")
public class PatientAreaController {

    private final ApplicationModel application;
    private final AuthService authService;
    private final AttemptLimiterService limiter;

    public PatientAreaController(ApplicationModel application, AuthService authService,
            AttemptLimiterService limiter) {
        this.application = application;
        this.authService = authService;
        this.limiter = limiter;
    }

    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    @GetMapping("/my-area")
    public String area(@AuthenticationPrincipal Jwt token, Locale locale, Model model) {
        Client patient = patient(token);
        List<AppointmentView> appointments = application.getClientUpcomingAppointments(patient.getId()).stream()
                .map(a -> new AppointmentView(
                        a.getId(),
                        Utils.formatDay(a.getDay(), locale),
                        Utils.time(a.getSlot()),
                        Utils.label(a.getSlot().getDoctor()),
                        // enlace a la agenda del médico en ese día: el paciente ve allí su nombre
                        "/schedule?doctorId=" + a.getSlot().getDoctorId() + "&day=" + Utils.iso(a.getDay())))
                .toList();
        model.addAttribute("model", new AreaModel("AREA.TITLE", null, Utils.label(patient), appointments));
        return "area";
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   campo: appointmentId
    // -----------------------------------------------------------------------
    @PostMapping("/my-area/cancel")
    public String cancelAppointment(@RequestParam(required = false) String appointmentId, @AuthenticationPrincipal Jwt token,
            RedirectAttributes redirect) {
        Client patient = patient(token);
        Integer id = Utils.positiveInteger(appointmentId);
        Optional<Appointment> appointment = id == null ? Optional.empty() : application.getAppointmentById(id);
        // una cita que no existe y la de OTRO paciente reciben
        // la misma respuesta: no revelamos nada sobre las citas de los demás
        if (appointment.isEmpty() || !appointment.get().getClientId().equals(patient.getId())) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
        } else {
            application.deleteAppointment(appointment.get());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
        }
        return "redirect:/my-area";
    }

    // -----------------------------------------------------------------------
    // GET /my-account
    // -----------------------------------------------------------------------
    @GetMapping("/my-account")
    public String accountForm(@AuthenticationPrincipal Jwt token, Model model) {
        Client patient = patient(token);
        PersonValues values = new PersonValues(patient.getTitle(), patient.getFirstName(), patient.getLastName(),
                patient.getUser().getLogin(), patient.getVersion());
        return show(model, values, Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /my-account
    // -----------------------------------------------------------------------
    @PostMapping("/my-account")
    public String editAccount(@Valid MyAccountForm form, BindingResult result,
            @AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
            Model model, RedirectAttributes redirect) {
        Client patient = patient(token);
        PersonValues values = new PersonValues(
                form.getTitle() == null ? patient.getTitle() : form.getTitle(),
                form.getFirstName() == null ? "" : form.getFirstName(),
                form.getLastName() == null ? "" : form.getLastName(),
                form.getLogin() == null ? "" : form.getLogin(),
                form.getVersion());

        Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
        if (!errors.containsKey("password") && form.getPassword() != null
                && !form.getPassword().equals(form.getConfirmation())) {
            errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
        }
        if (!errors.isEmpty()) {
            return show(model, values, errors, null, null);
        }

        // la contraseña actual
        Message passwordError = checkCurrentPassword(request, patient, form.getCurrentPassword());
        if (passwordError != null) {
            // contraseña incorrecta: el mensaje también va BAJO el campo
            Map<String, String> fieldErrors = passwordError.key().equals("ERRORS.WRONG_CURRENT_PASSWORD")
                    ? Map.of("currentPassword", passwordError.key())
                    : Map.of();
            return show(model, values, fieldErrors, passwordError, null);
        }

        try {
            Client client = application.editClient(patient.getId(), new PersonData(form.getTitle(),
                    form.getLastName(), form.getFirstName(), form.getLogin(),
                    form.getPassword(), // null = sin cambios
                    form.getVersion()));
            // el login y el nombre para mostrar están EN el token: emitimos uno
            // nuevo, de lo contrario la barra de navegación conservaría el nombre anterior
            authService.setToken(response, client.getUser());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.UPDATED"));
            return "redirect:/my-area";
        } catch (BusinessException e) {
            return show(model, values, Map.of(), Message.of(e.getKey()),
                    Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
        }
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   campo: deletePassword
    // La cuenta, el cliente y TODAS sus citas desaparecen juntos,
    // y luego se cierra la sesión del paciente.
    // -----------------------------------------------------------------------
    @PostMapping("/my-account/delete")
    public String deleteAccount(@RequestParam(required = false) String deletePassword,
            @AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
            RedirectAttributes redirect) {
        Client patient = patient(token);
        Message passwordError = checkCurrentPassword(request, patient, deletePassword);
        if (passwordError != null) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.error(passwordError.key(), passwordError.params()));
            return "redirect:/my-account";
        }
        application.deleteClient(patient.getId());
        AuthService.clearToken(response);
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.DELETED"));
        return "redirect:/login";
    }

    // ----------------------------------------------------------------- métodos privados

    // el paciente del token
    private Client patient(Jwt token) {
        return Utils.connectedPatient(application, Utils.user(token));
    }

    // null si la contraseña actual es correcta; si no, el mensaje de error
    private Message checkCurrentPassword(HttpServletRequest request, Client patient, String password) {
        String ip = AuthController.ipAddress(request);
        String login = patient.getUser().getLogin();
        long minutes = limiter.loginBlockMinutes(ip, login);
        if (minutes > 0) {
            return new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes)));
        }
        boolean ok = password != null && !password.isEmpty()
                && authService.validateUser(login, password).isPresent();
        if (!ok) {
            limiter.loginFailure(ip, login);
            return Message.of("ERRORS.WRONG_CURRENT_PASSWORD");
        }
        return null;
    }

    private static String show(Model model, PersonValues values, Map<String, String> errors,
            Message error, List<String> otherFields) {
        model.addAttribute("model", new MyAccountModel("MY_ACCOUNT.TITLE",
                Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
        return "account";
    }
}

Analicemos este código:

  • líneas 14–17: la regla de oro de este controlador: el paciente en cuestión es siempre el asociado con el token, nunca un identificador enviado por el navegador;
  • líneas 63–65: reservado para pacientes. Aquí, [@PreAuthorize] en la clase se aplica a todas las acciones, ya que todas están declaradas dentro de ella. El controlador no tiene la anotación [@RequestMapping]: cada acción proporciona su URL completa, ya que no comparten un prefijo ([/my-area], [/my-account]);
  • líneas 81–95: la página «Mi espacio». El método [patient] (más abajo) identifica al cliente a partir del token; si la cuenta del cliente se eliminó después del inicio de sesión, lanza una excepción [InvalidSessionException], que [web/HtmlExceptionHandler.java] maneja redirigiendo al usuario de vuelta a la página de inicio de sesión. La fecha es formateada por [Utils.formatDay] en el idioma de la solicitud (véase el ejemplo 22); cada cita incluye un enlace a la agenda del médico para ese día (línea 91);
  • líneas 100–115: cancelación de la cita del paciente. En la línea 105, un identificador no válido devuelve un [Optional] vacío ([Optional.empty()]). Una cita inexistente y una que pertenece a otro paciente (línea 108) reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes;
  • Líneas 120–126: el formulario de la cuenta, completado previamente con el número de versión (bloqueo optimista);
  • líneas 131–134: el proceso de modificación, en tres pasos: validación, verificación de la contraseña actual, capa de lógica de negocio;
  • líneas 136–141: los valores que se volverán a mostrar en caso de error; nunca las contraseñas;
  • líneas 143–150: errores de entrada. La nueva contraseña es opcional (en blanco: sin cambios); su confirmación se verifica solo si se ingresó;
  • líneas 153–160: la contraseña actual. Una contraseña incorrecta se señala debajo de su campo y al final de la página; un bloqueo (demasiados intentos) se indica solo al final de la página, junto con el número de minutos;
  • líneas 162–168: modificación por parte de la capa de negocio, que aplica las mismas reglas que para ADMIN (unicidad, bloqueo optimista);
  • línea 169: el token contiene el inicio de sesión y el nombre para mostrar: después de un cambio se emite un nuevo token; de lo contrario, la barra de navegación conservaría el nombre anterior;
  • líneas 172–175: un rechazo por parte de la capa de negocio recarga el formulario, con los campos correspondientes resaltados en rojo;
  • líneas 183–193: la eliminación de la cuenta también requiere la contraseña actual. Un error se indica mediante una ventana emergente en la página de la cuenta (PRG);
  • líneas 194–197: eliminación del registro, de la cuenta y de todas las citas (el método de la capa de negocio utilizado por ADMIN), seguida del cierre de sesión: se borra la cookie del token;
  • líneas 203–205: el paciente del token;
  • líneas 208–222: verificación de la contraseña actual. Devuelve [null] si la contraseña es correcta; de lo contrario, un mensaje de error (un [Message]: clave y parámetros). La contraseña actual está sujeta a las mismas restricciones que el inicio de sesión (véase el ejemplo 27): quien encuentre una sesión que se dejó abierta no podría cambiar la contraseña, eliminar la cuenta ni intentar adivinar contraseñas indefinidamente. La verificación en sí la realiza [AuthService]; un fallo se cuenta como un fallo de inicio de sesión;
  • líneas 224–229: el formulario de la cuenta.

11.16.8. controllers/ErrorController.java

// =========================================================================
// controllers/ErrorController.java
// -------------------------------------------------------------------------
// La página de error (400, 403, 404, 405, 500...).
//
// Nunca se llega aquí mediante un enlace. Cuando una solicitud termina en error
// - una excepción no manejada, un response.sendError(403), una
// ResponseStatusException(NOT_FOUND)... - el servidor (Tomcat) REENVÍA la
// solicitud a la dirección /error, para construir la página que se devuelve en lugar
// de una respuesta vacía o un seguimiento de la pila (véase el ejemplo 24). Almacena
// por el camino el código de error en un atributo de la solicitud.
//
// Spring Boot ya proporciona un controlador /error (BasicErrorController, la
// "Whitelabel Error Page"); se aparta en cuanto un bean implementa
// la interfaz ErrorController, como este.
//
// @RequestMapping sin método HTTP: la acción acepta todos los métodos -
// la solicitud reenviada conserva su método original (un POST rechazado sigue siendo un POST).
// =========================================================================
package rdvmedecins.controllers;

import java.util.Map;

// (la interfaz ErrorController de Spring Boot tiene el nombre de nuestra clase: escrita completa abajo)
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;

import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.models.ViewModels.ErrorModel;

@Controller
public class ErrorController implements org.springframework.boot.webmvc.error.ErrorController {

    private static final Map<Integer, String> MESSAGES = Map.of(
            HttpServletResponse.SC_BAD_REQUEST, "ERRORS.BAD_REQUEST",
            HttpServletResponse.SC_FORBIDDEN, "ERRORS.FORBIDDEN",
            HttpServletResponse.SC_NOT_FOUND, "ERRORS.NOT_FOUND");

    @RequestMapping("/error")
    public String show(HttpServletRequest request, HttpServletResponse response, Model model) {
        // el código de error original, almacenado por el servidor en la solicitud
        Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        int code = status instanceof Integer c ? c : HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
        // la página conserva este código (404 sigue siendo 404...); un código inesperado
        // (o /error llamado directamente) se convierte en un error 500
        if (code < 400 || code > 599) {
            code = HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
        }
        response.setStatus(code);
        model.addAttribute("model", new ErrorModel("ERROR_PAGE.TITLE", null, code,
                MESSAGES.getOrDefault(code, "ERRORS.SERVER_ERROR")));
        return "error";
    }
}

Este es el controlador del ejemplo 24, con mensajes traducidos:

  • líneas 6–11: nunca se llega a esta página mediante un enlace. Cuando una solicitud termina en error (una excepción no controlada, una [ResponseStatusException], un [response.sendError(403)] del manejador de rechazo de [Spring Security]...), el servidor [Tomcat] reenvía la solicitud a la dirección [/error] para generar la página que se devolverá, en lugar de una respuesta vacía o de una pila de llamadas;
  • líneas 13–15 y líneas 34–35: [Spring Boot] ya proporciona un controlador, [/error] ([BasicErrorController]), que genera la «Whitelabel Error Page». Se elimina en cuanto un bean implementa la interfaz [ErrorController] (importada en la línea 24), como este;
  • líneas 37–40: la clave de mensaje para cada código de error. [static final]: un único diccionario, creado cuando se carga la clase y nunca reemplazado; [Map.of] también lo hace de solo lectura;
  • línea 42: [@RequestMapping], que no especifica el método HTTP, acepta todos los métodos: una solicitud POST dirigida a [/error] (por ejemplo, un paciente que intenta una cancelación reservada a los administradores) sigue siendo una solicitud POST;
  • Líneas 45–46: el código de error original, que el servidor almacenó en un atributo de la solicitud llamado [RequestDispatcher.ERROR_STATUS_CODE]. El atributo es de tipo [Object]: [status instanceof Integer c] verifica si es efectivamente un [Integer] y, en ese caso, lo almacena en la variable [c]. De lo contrario (dirección [/error] ingresada manualmente), el código es 500;
  • líneas 49–51: un código HTTP que no es de error se convierte en un error 500;
  • línea 52: la página conserva el código de error original (una página desconocida sigue siendo una respuesta 404);
  • líneas 53–55: el modelo de la página y el nombre de su vista. [getOrDefault] devuelve la clave asociada con el código, o [ERRORS.SERVER_ERROR] para cualquier otro código (500 en particular).

11.17. Vistas

Las vistas se escriben con [Thymeleaf] (véanse los ejemplos 13 a 16). Repasemos el concepto: una vista es un verdadero archivo HTML, enriquecido con atributos [th:...] que [Thymeleaf] reemplaza al generar la página. Cuando se abre directamente en un navegador, sin servidor, el archivo se muestra de todos modos, con su texto de muestra («Mme Alice DURAND», «8:00 – 8:20»): esto se conoce como «plantillas naturales». Los atributos utilizados en el caso de estudio son los de los ejemplos:

Atributo o expresión
Función
[th:text="${model.day}"]
reemplaza el contenido del elemento con el valor, escapado ([<] se convierte en [&lt;])
[th:utext]
Igual que el anterior, sin escape (solo para la imagen del CAPTCHA)
[#{SCHEDULE.FREE}]
Un mensaje traducido (véase el ejemplo 22)
[#{BOOKING_DIALOG.SLOT('time', ${r.time})}]
un mensaje con un parámetro [{time}]
[#{${error.key}(${error.params})}]
un mensaje cuya clave es en sí misma un valor, con un diccionario de parámetros
[th:if], [th:unless]
el elemento se escribe solo si la condición es verdadera (falsa)
[th:each="row : ${rows}"]
el elemento se repite para cada elemento de la lista
[th:value], [th:href], [th:action]
Un atributo calculado
[th:selected], [th:autofocus]
un atributo booleano: se escribe si el valor es verdadero, se omite en caso contrario
[th:classappend]
agrega una clase CSS a las del atributo [class]
[th:attr="data-confirmation=#{...}"]
cualquier atributo, calculado
[th:with="state=${model.state}"]
una variable local al elemento
[th:replace="~{fragments/flash :: flash}"]
reemplaza el elemento con un fragmento (véase el ejemplo 15)
[<th:block>]
una etiqueta que no deja rastro en la página generada
[<!--/* ... */-->]
un comentario, eliminado de la página generada

Las vistas casi no tienen decisiones que tomar: su modelo fue preparado por los controladores en la sección [record] del archivo [models/ViewModels.java] (qué botones mostrar, qué URL, qué claves de traducción). Cada vista comienza con un comentario [<!--/* ... */-->] que describe su función; estos comentarios no aparecen en las páginas enviadas al navegador. A diferencia de [Razor], [Thymeleaf] no conoce el tipo del modelo: un error tipográfico en [${model.dayy}] no se detecta en tiempo de compilación, sino cuando se renderiza la página, lo que produce una excepción (y, por tanto, un error 500).

Todas las vistas tienen acceso a las mismas variables: [model], el modelo de la página almacenado por el controlador; [user], [language] y [path] (el usuario que inició sesión, o [null], el idioma de la solicitud, la ruta de la URL solicitada), agregadas al modelo para todas las acciones por el método [@ModelAttribute] de [web/CommonModel.java]; y [flash], los mensajes flash, si los hay: después de una redirección, Spring MVC coloca automáticamente los atributos flash en el modelo de la siguiente solicitud.

11.17.1. La plantilla y los fragmentos

11.17.1.1. templates/layout.html

<!doctype html>
<!--/* =========================================================================
   templates/layout.html
   -------------------------------------------------------------------------
   El layout COMÚN a todas las páginas (vea el ejemplo 15): un fragmento
   [page] cuyo parámetro [content] es el bloque <main> de la página solicitada
   por el controlador (schedule.html, login.html...).

   Thymeleaf ESCAPA todo lo que muestra con th:text (los caracteres
   < > & " ' se convierten en &lt; &gt;...): protección contra la inyección de HTML
   a través de un nombre escrito, por ejemplo. Para insertar HTML tal cual, hay que
   solicitarlo explícitamente (th:utext, vea fragments/captcha.html).

   Mensajes: un éxito se muestra en la parte SUPERIOR de la página (fragmento flash), un
   error en la parte INFERIOR, sobre un fondo rosa claro (fragmento errors).

   El layout comparte las variables de la página: [model] (el modelo de vista
   pasado por el controlador, vea models/ViewModels.java), de donde lee el
   título de la página; [language], [user], [path], agregadas a todas
   las vistas por web/CommonModel.java; [flash], el posible mensaje flash.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${language}" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <!--/* #{${key}}: el mensaje cuya clave es el VALOR de la expresión ${key} */-->
  <title th:text="|#{${model.pageTitle}} - #{APP.TITLE}|">RdvMedecins</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <div th:replace="~{fragments/flash :: flash}"></div>
    <main th:replace="${content}"></main>
    <div th:replace="~{fragments/errors :: errors}"></div>
  </div>
  <!--/* el diálogo "Are you sure?", oculto mientras no se necesita */-->
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <script src="/js/app.js"></script>
</body>
</html>

Esta es la plantilla del ejemplo 15. Cada página de la aplicación comienza con [<html th:replace="~{layout :: page(~{::main})}">]: es reemplazada por el fragmento [page] de esta plantilla, al cual se le pasa su propio elemento [<main>].

  • Líneas 2–21: un comentario de [Thymeleaf]: [<!--/*] y [*/-->] delimitan el texto que [Thymeleaf] elimina de la página generada. Un navegador que abre el archivo sin servidor lo ve como un comentario HTML normal;
  • línea 22: [th:fragment="page(content)"] convierte todo el elemento [<html>] en un fragmento llamado [page], que recibe un parámetro, [content]. [th:lang] escribe el atributo [lang] de la página: el idioma de la solicitud ([fr] o [en]);
  • línea 27: el título, traducido, por ejemplo, «Agenda - RdvMedecins». Las barras verticales [|...|] delimitan una sustitución literal: texto en el que las expresiones se reemplazan por sus valores. [#{${model.pageTitle}}] es el mensaje cuya clave es el valor de [${model.pageTitle}]: este título lo proporciona el controlador en el modelo de cada página (en el ejemplo 15, la página lo pasaba como parámetro de un fragmento);
  • líneas 28–29: las hojas de estilo, servidas por [Spring Boot] desde la carpeta [src/main/resources/static]: [Bootstrap] ([static/lib/bootstrap]) y la hoja de estilo propia de la aplicación;
  • líneas 33–36: la barra de navegación, el mensaje de éxito (en la parte superior), el elemento [<main>] de la página solicitada ([th:replace="${content}"]: el elemento se reemplaza por el fragmento recibido como parámetro) y el área de errores (en la parte inferior);
  • líneas 39–40: la ventana de confirmación (oculta) y su script (véase el ejemplo 21), cargado en la parte inferior de la página.

El comienzo de la página de inicio de sesión, tal como lo recibe el navegador:

curl -i http://localhost:8081/login
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>

<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>Login - RdvMedecins</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
...

Los comentarios [<!--/* ... */-->] han desaparecido, y solo quedan líneas vacías; los atributos [th:...] también han desaparecido.

11.17.1.2. templates/fragments/navbar.html

<!--/* =========================================================================
   templates/fragments/navbar.html - la barra de navegación.

   Título, FR/EN, rol, nombre, cierre de sesión - y un menú cuyas entradas
   dependen del rol: "Doctors" y "Patients" aparecen solo para
   el ADMIN. Es solo una comodidad de visualización: la protección real es
   el @PreAuthorize de los controladores (un USER que escribe /doctors a mano
   obtiene una página 403). Un paciente (USER) también tiene su menú "My area".

   El menú de la página actual se resalta (clase "active"):
   [path] es la URL solicitada (véase web/CommonModel.java).
   ========================================================================= */-->
<nav xmlns:th="http://www.thymeleaf.org" th:fragment="navbar"
     class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0" th:text="#{APP.TITLE}">RdvMedecins</span>

  <ul class="navbar-nav me-auto" th:if="${user != null}">
    <li class="nav-item" th:if="${user.isPatient()}">
      <a class="nav-link" th:classappend="${#strings.startsWith(path, '/my-')} ? 'active'"
         href="/my-area" th:text="#{APP.MENU_MY_AREA}">My area</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" th:classappend="${#strings.startsWith(path, '/schedule')} ? 'active'"
         href="/schedule" th:text="#{APP.MENU_SCHEDULE}">Schedule</a>
    </li>
    <!--/* th:block: una etiqueta de Thymeleaf que no deja rastro en el HTML */-->
    <th:block th:if="${user.isAdmin()}">
      <li class="nav-item">
        <a class="nav-link" th:classappend="${#strings.startsWith(path, '/doctors')} ? 'active'"
           href="/doctors" th:text="#{APP.MENU_DOCTORS}">Doctors</a>
      </li>
      <li class="nav-item">
        <a class="nav-link" th:classappend="${#strings.startsWith(path, '/clients')} ? 'active'"
           href="/clients" th:text="#{APP.MENU_PATIENTS}">Patients</a>
      </li>
    </th:block>
  </ul>
  <div class="me-auto" th:if="${user == null}"></div>

  <div class="d-flex align-items-center gap-2">
    <!--/* FR / EN: simples enlaces (GET /language/fr), el idioma activo resaltado */-->
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn" th:classappend="${language == 'fr'} ? 'btn-light' : 'btn-outline-light'" href="/language/fr">FR</a>
      <a class="btn" th:classappend="${language == 'en'} ? 'btn-light' : 'btn-outline-light'" href="/language/en">EN</a>
    </div>

    <th:block th:if="${user != null}">
      <span class="badge text-bg-light text-primary" th:text="${user.role}">ADMIN</span>
      <span class="text-white" th:text="${user.name}">name</span>
      <!--/* el cierre de sesión es un POST: un formulario reducido a su botón */-->
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light" th:text="#{APP.LOGOUT}">Log out</button>
      </form>
    </th:block>
  </div>
</nav>
  • líneas 13–14: el fragmento [navbar], insertado por la plantilla;
  • línea 17: el menú se muestra solo a un usuario que inició sesión. En la página de inicio de sesión, [user] tiene el valor [null];
  • líneas 18–21: «Mi espacio», solo para pacientes. [user.isPatient()] llama a un método de [record] [ConnectedUser]: las expresiones de [Thymeleaf] pueden llamar a métodos;
  • Línea 19: el menú de la página actual aparece resaltado (clase [active]). [#strings.startsWith] es una función del objeto de utilidad [#strings] de [Thymeleaf] (véase el ejemplo 14). [condition ? 'active'], sin cláusula «else», se evalúa como [null] si la condición es falsa, y [th:classappend] entonces no agrega nada;
  • Líneas 27–36: «Médicos» y «Pacientes», solo para ADMIN. [th:block] agrupa los dos elementos bajo una sola condición, sin dejar ninguna etiqueta en la página. Esto es solo una comodidad de visualización: la protección real proviene de [@PreAuthorize] en los controladores (un USER que ingresa manualmente [/doctors] recibe una página 403, como hemos visto);
  • línea 38: si ningún usuario ha iniciado sesión, un elemento vacío empuja los botones FR / EN hacia la derecha de la barra, igual que lo hace el menú;
  • líneas 43–44: los botones FR / EN son simplemente enlaces a [/language/fr] y [/language/en]; el del idioma activo aparece resaltado ([btn-light]). Aquí, la expresión condicional tiene ambas ramas;
  • líneas 48–49: el rol y el nombre del usuario, leídos del token;
  • líneas 51–53: el cierre de sesión es una solicitud POST (véase el ejemplo 25), procesada por [Spring Security] (véase [SecurityConfig]): un formulario reducido a un solo botón. Un simple enlace (GET), colocado en otro sitio, no podría cerrar la sesión del usuario sin que este lo sepa.

11.17.1.3. templates/fragments/flash.html

<!--/* =========================================================================
   templates/fragments/flash.html - el mensaje de ÉXITO puesto por la
   acción anterior (cita guardada, médico agregado...), mostrado solo
   una vez, en la parte superior de la página (véase web/CookieFlashMapManager.java).
   Un mensaje flash de ERROR se muestra al pie de la página, por
   fragments/errors.html.

   #{${flash.key}(${flash.params})}: el mensaje cuya clave es
   flash.key, con como parámetro el diccionario de los valores de {name},
   {login}... (véase web/Translator.java).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="flash"
     th:if="${flash != null and flash.successful()}" class="alert alert-success" role="status"
     th:text="#{${flash.key}(${flash.params})}">message</div>
  • líneas 12–14: el mensaje de éxito mostrado por la acción anterior, antes de una redirección. [flash] es un [FlashMessage] (véase [web/FlashMessage.java]): un tipo (éxito o error), una clave de traducción y parámetros. Este fragmento muestra solo los mensajes de éxito; los errores se muestran en la parte inferior de la página mediante el fragmento siguiente. [role="status"] hace que los lectores de pantalla anuncien el mensaje;
  • línea 14: [#{${flash.key}(${flash.params})}]: el mensaje con la clave [flash.key], con el diccionario [flash.params] como parámetros (los valores de [{name}], [{login}]...). El servicio [Translator] (véase «La capa web: servicios comunes») es el que reemplaza estos parámetros en el texto.

11.17.1.4. templates/fragments/errors.html

<!--/* =========================================================================
   templates/fragments/errors.html - la zona de errores, al PIE de cada
   página, sobre un fondo rosa claro (clase .error-zone, véase static/css/styles.css).

   Reúne las dos posibles fuentes de error:
     - model.error: el error de la página mostrada (formulario rechazado, login
       o nombre + apellido ya usados, fecha inválida, contraseña incorrecta...);
     - un mensaje flash de error, puesto por la acción anterior antes de una
       redirección (franja ya reservada, eliminación rechazada...).

   th:with define variables locales al elemento. Se coloca en un th:block
   ENVOLVENTE: en el mismo elemento, Thymeleaf evalúa th:if ANTES que
   th:with, y las variables aún no existirían. role="alert": un
   lector de pantalla anuncia el mensaje en cuanto se muestra la página, aunque
   esté al pie.
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="errors"
          th:with="error=${model.error}, flashError=${flash != null and !flash.successful()} ? ${flash}">
  <div th:if="${error != null or flashError != null}" class="error-zone" role="alert">
    <div th:if="${error != null}" th:text="#{${error.key}(${error.params})}">page error</div>
    <div th:if="${flashError != null}" th:text="#{${flashError.key}(${flashError.params})}">flash error</div>
  </div>
</th:block>
  • líneas 5–9: la sección de errores agrupa las dos posibles fuentes de error: el error de la página ([model.error]) y un mensaje de error flash;
  • Líneas 17–18: [th:with] define dos variables locales. [error] es el error de la página; [flashError] es el mensaje flash si es un error, [null] en caso contrario (una expresión condicional sin cláusula «else», como en la barra de navegación). Estas variables se definen en un ***[th:block] que *engloba el elemento que las utiliza. No se puede escribir [th:with] y ***[th:if] en el mismo elemento: [Thymeleaf]* procesa los atributos de un elemento en un orden fijo, que no depende del orden en que se escriben, y [th:if] se evalúa antes que [th:with]**. La condición usaría variables que aún no existen;
  • línea 19: el campo se escribe solo si hay al menos un mensaje. [role="alert"]: un lector de pantalla anuncia el mensaje en cuanto se muestra la página, aunque esté en la parte inferior;
  • Líneas 20–21: ambos mensajes, traducidos junto con sus parámetros.

Por ejemplo, para una agenda solicitada con una fecha no válida ([day=2026-02-30]), la parte inferior de la página contiene:

1
2
3
4
  <div class="error-zone" role="alert">
    <div>The requested date is not valid.</div>

  </div>

11.17.1.5. templates/fragments/confirmation.html

<!--/* =========================================================================
   templates/fragments/confirmation.html - el diálogo modal "Are you sure?".

   Reemplaza el cuadro window.confirm() del navegador, que no se puede
   personalizar ni traducir (sus botones permanecen en el idioma del
   navegador, no en el de la página).

   UN SOLO diálogo para toda la página, oculto (d-none) al principio. Sus
   etiquetas se traducen aquí, por el servidor, como el resto de la página;
   el pequeño script static/js/app.js se limita a mostrarlo, a poner en él
   el mensaje específico del formulario (atributo data-confirmation), y a enviar
   el formulario si el usuario confirma.

   Mismas clases Bootstrap que el diálogo de reserva (fragments/booking.html).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="confirmation" id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title" th:text="#{CONFIRMATION.TITLE}">Confirmation</h5>
          <button type="button" class="btn-close" data-action="no" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <!--/* "No, go back" en lugar de "Cancel": la pregunta a veces
                 "Cancel this appointment?", y un botón "Cancel" sería ambiguo */-->
          <button type="button" class="btn btn-secondary" data-action="no" th:text="#{CONFIRMATION.NO}">No</button>
          <button type="button" class="btn btn-danger" data-action="yes" th:text="#{CONFIRMATION.YES}">Yes</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • Líneas 4–6: ¿por qué hay una ventana en la página en lugar del cuadro [window.confirm()] del navegador (véase el ejemplo 21)?
  • Línea 16: una sola ventana para toda la página, inicialmente oculta por la clase [d-none] de [Bootstrap] ([display: none]). El script [static/js/app.js] la localiza por su identificador;
  • Líneas 17–21: las clases de [Bootstrap] de una ventana modal: el fondo atenuado ([modal-backdrop]), y luego la ventana, que pasa a ser visible ([show d-block]) en cuanto se quita la clase [d-none]. [role="alertdialog"], [aria-modal], [aria-labelledby] y [aria-describedby] describen la ventana a los lectores de pantalla;
  • línea 24: el botón de cierre. Su etiqueta para lectores de pantalla ([aria-label]) está traducida; [th:attr] calcula un atributo cualquiera;
  • línea 27: el lugar del mensaje específico de cada formulario, colocado allí por el script;
  • líneas 30–33: «No, volver» en lugar de «Cancelar»: la pregunta a veces es «¿Cancelar esta cita?». El atributo [data-action] le indica al script qué botón se presionó.

11.17.1.6. templates/fragments/captcha.html

<!--/* =========================================================================
   templates/fragments/captcha.html - el captcha de la página de autenticación
   (véase auth/CaptchaService.java). Protege tanto el login como
   el acceso a la creación de cuentas (botón "Create a client account").
   Parámetro: captcha, un objeto Captcha (id, svg).

   th:utext: la imagen SVG se inserta TAL CUAL en la página, sin
   escape. Aquí es inofensivo porque este SVG lo construye el propio
   servidor y no contiene nada que provenga del usuario - NUNCA se haría esto
   con una entrada.

   El campo oculto captchaId le dice al servidor QUÉ captcha verificar; la respuesta
   correcta nunca se envía al navegador.
   "Another image" simplemente recarga la página ([path] = la URL actual).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="captcha(captcha)" class="mb-3">
  <label class="form-label" for="captcha" th:text="#{CAPTCHA.LABEL}">Copy the characters</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" th:attr="aria-label=#{CAPTCHA.IMAGE_ALT}" th:utext="${captcha.svg}">image</div>
    <a class="small" th:href="${path}" th:text="#{CAPTCHA.NEW_IMAGE}">Another image</a>
  </div>
  <input type="hidden" name="captchaId" th:value="${captcha.id}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text" th:text="#{CAPTCHA.HELP}">help</div>
</div>
  • línea 16: un fragmento parametrizado: la página que lo inserta le pasa el objeto [Captcha] (ID e imagen);
  • línea 19: la imagen SVG del CAPTCHA (véase el ejemplo 27) se inserta tal cual en la página ([th:utext]), sin escape. Esto es seguro aquí porque este SVG lo genera el propio servidor y no contiene nada proporcionado por el usuario; nunca haríamos esto con datos ingresados por el usuario. [role="img"] y [aria-label] describen la imagen a los lectores de pantalla;
  • línea 20: «Otra imagen» simplemente recarga la página ([path] es la ruta de la URL actual): cada vista genera un nuevo CAPTCHA;
  • línea 22: el campo oculto [captchaId] le indica al servidor qué CAPTCHA debe verificar; la respuesta correcta, sin embargo, nunca se envía al navegador;
  • Líneas 23–24: los campos de entrada. [autocomplete="off"], [autocapitalize="off"], y [spellcheck="false"] impiden que el navegador sugiera, escriba en mayúsculas o corrija lo ingresado.

11.17.1.7. templates/fragments/person-fields.html

<!--/* =========================================================================
   templates/fragments/person-fields.html - los campos de identidad (título,
   nombre, apellido), comunes a tres formularios: médico/cliente del ADMIN,
   "Create a client account" y "Manage my account".
   El fragmento lee la variable [model] de la página que lo inserta (un
   FormView, véase models/ViewModels.java): valores, mensaje bajo
   cada campo, campos resaltados en rojo.

   th:selected: un atributo booleano. Thymeleaf escribe selected="selected"
   si el valor es true, y OMITE el atributo si es false.
   th:classappend: agrega una clase a las ya presentes - aquí
   "is-invalid" (contorno rojo de Bootstrap) para un campo rechazado, o nada.
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="fields" th:with="state=${model.state}">
<div class="mb-3">
  <label class="form-label" for="title" th:text="#{PERSONS.TITLE_LABEL}">Title</label>
  <select id="title" name="title" class="form-select" th:classappend="${state.invalidClass('title')}">
    <option th:each="title : ${model.titles()}" th:value="${title.value}"
            th:selected="${title.selected}" th:text="${title.value}">Mr</option>
  </select>
  <div class="invalid-feedback" th:if="${state.errorOf('title') != null}"
       th:text="#{${state.errorOf('title')}}">error</div>
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <label class="form-label" for="firstName" th:text="#{PERSONS.FIRSTNAME_LABEL}">First name</label>
    <input id="firstName" name="firstName" type="text" maxlength="20" required
           class="form-control" th:classappend="${state.invalidClass('firstName')}" th:value="${model.values.firstName}">
    <div class="invalid-feedback" th:if="${state.errorOf('firstName') != null}"
         th:text="#{${state.errorOf('firstName')}}">error</div>
  </div>
  <div class="col-sm-6">
    <label class="form-label" for="lastName" th:text="#{PERSONS.LASTNAME_LABEL}">Last name</label>
    <input id="lastName" name="lastName" type="text" maxlength="20" required
           class="form-control" th:classappend="${state.invalidClass('lastName')}" th:value="${model.values.lastName}">
    <div class="invalid-feedback" th:if="${state.errorOf('lastName') != null}"
         th:text="#{${state.errorOf('lastName')}}">error</div>
  </div>
</div>
</th:block>

Los campos de título, nombre y apellido son comunes a tres formularios: el formulario de ADMIN (para médicos y clientes), el formulario de creación de cuenta y el formulario «Administrar mi cuenta». Se escriben una sola vez, en este fragmento.

  • Línea 14: el fragmento [fields] es un [th:block]: no agrega ninguna etiqueta alrededor de los campos. Lee la variable [model] de la página que lo inserta: un modelo que implementa la interfaz [FormView] (véase [models/ViewModels.java]), y que por lo tanto tiene valores ([values]) y un estado ([state]). [th:with] almacena el estado en una variable más corta; no hay ningún [th:if] en este mismo elemento;
  • línea 17: [th:classappend] agrega la clase devuelta por [state.invalidClass('title')]: [is-invalid] (el borde rojo de [Bootstrap]) para un campo rechazado, una cadena vacía en caso contrario;
  • líneas 18–19: los títulos ([Mr], [Mme], [Melle]), devueltos por el método [titles()] del modelo, un método predeterminado de la interfaz [FormView]. Cada opción indica si está seleccionada: [th:selected] escribe [selected="selected"] si el valor es verdadero, y omite el atributo si es falso;
  • Líneas 21–22: el mensaje de error del campo, si lo hay. [#{${state.errorOf('title')}}]: el mensaje cuya clave devuelve [errorOf]. La clase [invalid-feedback] de [Bootstrap] muestra este mensaje solo debajo de un campo [is-invalid];
  • Líneas 25–40: el nombre y el apellido, con el mismo formato, uno al lado del otro en una pantalla bastante ancha ([col-sm-6]). [th:value] vuelve a mostrar lo ingresado; [maxlength] y [required] son comodidades para el usuario, ya que la validación real la realiza el servidor.

11.17.1.8. templates/fragments/booking.html

<!--/* =========================================================================
   templates/fragments/booking.html - el diálogo de reserva de la
   agenda.

   Las clases Bootstrap REALES de un diálogo modal (.modal,
   .modal-backdrop...), hechas visibles "a la fuerza" (show d-block) en lugar
   de mediante el JavaScript de Bootstrap. Es el SERVIDOR quien decide mostrarlo
   (parámetro &book=... de la URL), y cerrarlo equivale a seguir un enlace
   a la misma página sin este parámetro.

   El fragmento lee directamente la variable [model] de la página que lo inserta
   (un ScheduleModel).
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="booking" th:with="booking=${model.booking}">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title" th:text="#{BOOKING_DIALOG.TITLE}">Book this slot</h5>
        <a class="btn-close" th:href="${model.backUrl}" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></a>
      </div>

      <div class="modal-body">
        <p th:text="#{BOOKING_DIALOG.SLOT('time', ${booking.time})}">Slot 8:00 - 8:20</p>

        <!--/* lo que el servidor debe saber además del paciente elegido */-->
        <input type="hidden" name="doctorId" th:value="${model.doctorId}">
        <input type="hidden" name="day" th:value="${model.day}">
        <input type="hidden" name="slotId" th:value="${booking.slotId}">

        <!--/* un paciente reserva para sí mismo: sin lista donde elegir
               (y el servidor ignora de todos modos un posible clientId) */-->
        <p class="mb-0" th:if="${booking.patient != null}">
          <span th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</span>:
          <strong th:text="${booking.patient}">Mme Alice DURAND</strong>
        </p>
        <th:block th:if="${booking.patient == null}">
          <label class="form-label" for="clientId" th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</label>
          <select id="clientId" name="clientId" class="form-select" required autofocus>
            <option value="" th:text="#{BOOKING_DIALOG.CHOOSE_PATIENT}">-- choose a patient --</option>
            <option th:each="client : ${booking.clients}" th:value="${client.id}"
                    th:text="${client.label}">Mme Alice DURAND</option>
          </select>
        </th:block>
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" th:href="${model.backUrl}" th:text="#{BOOKING_DIALOG.CANCEL}">Cancel</a>
        <button type="submit" class="btn btn-primary" th:text="#{BOOKING_DIALOG.CONFIRM}">Confirm</button>
      </div>
    </form>
  </div>
</div>
</th:block>
  • Líneas 5–9: la ventana de reserva utiliza las clases reales de una ventana modal de [Bootstrap], hecha visible «de forma fija» ([show d-block]) en lugar de mediante el [JavaScript] de [Bootstrap]. El servidor decide si se muestra;
  • línea 14: el fragmento lee el modelo de la página (un [ScheduleModel]); [th:with] almacena la ventana ([model.booking]) en la variable [booking];
  • línea 18: el formulario envía la reserva mediante POST a [/schedule/book];
  • línea 21: el botón de cierre es un enlace a la agenda, sin el parámetro [book]: cerrar la ventana simplemente muestra la página sin ella;
  • línea 25: «Horario 8:00 - 8:20»: un mensaje con un parámetro. En [#{BOOKING_DIALOG.SLOT('time', ${booking.time})}], los parámetros se dan como pares (nombre, valor): [{time}] se reemplaza por el valor de [booking.time];
  • líneas 28–30: campos ocultos: el médico, el día (para volver a la misma agenda) y el horario;
  • líneas 34–37: un paciente hace una reserva para sí mismo: sin lista, solo su nombre (el servidor de todos modos ignora cualquier [clientId]);
  • líneas 38–45: un administrador selecciona un paciente de una lista, obligatoria ([required]), que recibe el foco al abrirse la página ([autofocus]);
  • línea 49: «Cancelar» también es un enlace a la página sin la ventana emergente.

11.17.2. Las páginas

11.17.2.1. templates/login.html

<!doctype html>
<!--/* =========================================================================
   templates/login.html - el formulario de login (véase AuthController).
   Un <form> HTML ordinario: el propio navegador envía login,
   contraseña y respuesta al captcha en POST /login, sin JavaScript. En caso
   de fallo, el servidor devuelve ESTA página, con el login ya escrito, un
   captcha NUEVO y el error, mostrado al pie de la página por el layout.

   Toda la página se REEMPLAZA por el fragmento [page] del layout, al que
   pasamos el bloque <main> de esta página (~{::main}).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="loginTyped=${model.login != ''}">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3" th:text="#{LOGIN.TITLE}">Login</h5>

      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{LOGIN.LOGIN_LABEL}">Login</label>
          <!--/* th:autofocus: un atributo booleano, escrito si el valor es true, omitido en caso contrario */-->
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 th:value="${model.login}" required th:autofocus="${!loginTyped}">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password" th:text="#{LOGIN.PASSWORD_LABEL}">Password</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required th:autofocus="${loginTyped}">
        </div>

        <div th:replace="~{fragments/captcha :: captcha(${model.captcha})}"></div>

        <button type="submit" class="btn btn-primary w-100" th:text="#{LOGIN.SUBMIT}">Log in</button>

        <!--/* todavía sin cuenta: un paciente puede crear una él mismo.
               NO es un simple enlace: es un segundo botón de envío de
               ESTE formulario, que va a otra dirección (formaction). El
               servidor verifica allí el captcha anterior antes de abrir la página de
               creación de cuenta (véase RegistrationController).
               formnovalidate: el navegador no exige login ni contraseña
               (inútiles para crear una cuenta); es el servidor quien verifica el
               captcha. Enter en un campo siempre activa el PRIMER
               botón del formulario, "Log in". */-->
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="/register/access" formnovalidate th:text="#{LOGIN.CREATE_ACCOUNT}">Create an account</button>
        <div class="form-text text-center" th:text="#{LOGIN.CREATE_ACCOUNT_HELP}">help</div>
      </form>

      <div class="text-muted small mt-3">
        <span th:text="#{LOGIN.DEMO_ACCOUNTS}">Demo accounts</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span th:text="#{LOGIN.DEMO_ADMIN}">ADMIN</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span th:text="#{LOGIN.DEMO_DOCTOR}">DOCTOR</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span th:text="#{LOGIN.DEMO_USER}">USER</span></li>
        </ul>
      </div>
    </div>
  </div>
</main>
</body>
</html>
  • línea 12: la página es reemplazada por el fragmento [page] de la plantilla, al cual se le pasa su elemento [<main>]. [~{::main}] se refiere al elemento [<main>] del archivo actual. Por lo tanto, solo se usa este elemento: las etiquetas [<html>] y [<body>] de este archivo solo sirven para convertirlo en un archivo HTML completo que se puede abrir en un navegador;
  • línea 14: después de un intento fallido, el controlador devuelve esta página con el inicio de sesión ya ingresado ([model.login]); la variable [loginTyped] indica si se conoce;
  • línea 19: un formulario HTML estándar: el propio navegador envía el nombre de usuario, la contraseña y la respuesta del CAPTCHA;
  • líneas 23–29: [th:autofocus] establece el atributo booleano [autofocus] si el valor es verdadero, y lo omite en caso contrario: solo uno de los dos campos lo recibe. El cursor se coloca en el campo del nombre de usuario, o en el de la contraseña si el nombre de usuario ya se conoce. Los valores de [autocomplete] ([username], [current-password]) ayudan a los administradores de contraseñas de los navegadores;
  • línea 32: el CAPTCHA, un fragmento parametrizado, que recibe el objeto [model.captcha];
  • líneas 45–46: el segundo botón envía el mismo formulario a [/register/access] (atributo [formaction], véase el ejemplo 21): el servidor verifica allí el CAPTCHA antes de abrir la página de creación de cuenta. [formnovalidate]: el navegador no exige un nombre de usuario ni una contraseña, ya que no son necesarios para crear una cuenta. Presionar la tecla Enter en un campo siempre activa el primer botón del formulario: «Iniciar sesión»;
  • Líneas 50–57: cuentas de demostración (contraseña = nombre de usuario).

Este es el formulario generado para la dirección [/login?login=martin] (la imagen del CAPTCHA se ha recortado):

curl http://localhost:8081/login?login=martin
    <main class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">Login</h5>
      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login">Login</label>
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="martin" required>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">Password</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required autofocus="autofocus">
        </div>
        <div class="mb-3">
  <label class="form-label" for="captcha">Type the characters shown in the image</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="Anti-robot verification image"><svg xmlns="http://www.w3.org/2000/svg" width="150" height="50" ...</svg></div>
    <a class="small" href="/login">Another image</a>
  </div>
  <input type="hidden" name="captchaId" value="7cb0085e-e571-4756-878f-04ca6f429140">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text">Upper or lower case, it does not matter.</div>
</div>
        <button type="submit" class="btn btn-primary w-100">Log in</button>

Como el nombre de usuario ya se conoce, solo al campo de la contraseña se le asignó el atributo [autofocus]. El enlace «Otra imagen» apunta a [/login]: la variable [path] contiene solo la ruta de la URL, sin sus parámetros.

11.17.2.2. templates/schedule.html

<!doctype html>
<!--/* =========================================================================
   templates/schedule.html - la página principal (véase ScheduleController).
   Tres bloques:
     1. la elección del médico y del día;
     2. la agenda;
     3. el diálogo de reserva (fragments/booking.html).
   Un posible error (fecha inválida, médico desconocido) se muestra al
   pie de la página por el layout (véase fragments/errors.html).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>

  <!--/* 1. elección del médico y del día: un formulario GET, que simplemente
         recarga esta página con ?doctorId=...&day=... en la URL */-->
  <form method="get" action="/schedule" class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId" th:text="#{DOCTOR_DAY_PICKER.DOCTOR_LABEL}">Doctor</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="" th:text="#{DOCTOR_DAY_PICKER.CHOOSE_DOCTOR}">-- choose --</option>
          <option th:each="doctor : ${model.doctors}" th:value="${doctor.id}"
                  th:selected="${doctor.selected}" th:text="${doctor.label}">Mme Marie PELISSIER</option>
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day" th:text="#{DOCTOR_DAY_PICKER.DAY_LABEL}">Day</label>
        <input id="day" name="day" type="date" class="form-control" th:value="${model.day}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100" th:text="#{DOCTOR_DAY_PICKER.VIEW_SCHEDULE}">View the schedule</button>
      </div>
    </div>
  </form>

  <!--/* paciente que ya tiene una cita futura: por qué no hay botón "Book" */-->
  <div class="alert alert-info" th:if="${model.info != null}">
    <span th:text="#{${model.info}}">info</span>
    <a href="/my-area" class="alert-link" th:text="#{APP.MENU_MY_AREA}">My area</a>
  </div>

  <!--/* 2. la agenda; th:object: ${schedule} permite entonces escribir *{...} */-->
  <div class="card p-3" th:if="${model.schedule != null}" th:object="${model.schedule}">
    <h5 th:text="|#{SCHEDULE.TITLE_PREFIX} *{day} - *{doctor}|">Schedule of ...</h5>

    <table class="table table-hover align-middle" th:unless="*{rows.isEmpty()}">
      <thead>
        <tr>
          <th th:text="#{SCHEDULE.COLUMN_SLOT}">Slot</th>
          <th th:text="#{SCHEDULE.COLUMN_STATUS}">Status</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr th:each="row : *{rows}" th:classappend="${row.bookable} ? 'free-slot'">
          <td th:text="${row.time}">8:00 - 8:20</td>
          <td>
            <!--/* [patient] se llena solo si el usuario tiene permiso para ello
                   ver este nombre (ADMIN, DOCTOR, o el paciente para SU
                   cita) - de lo contrario, simplemente "Booked" */-->
            <span th:if="${row.free}" class="badge text-bg-success" th:text="#{SCHEDULE.FREE}">Free</span>
            <span th:if="${!row.free and row.patient != null}" class="badge"
                  th:classappend="${row.mine} ? 'text-bg-primary' : 'text-bg-secondary'"
                  th:text="${row.patient}">Mme Alice DURAND</span>
            <span th:if="${!row.free and row.patient == null}" class="badge text-bg-secondary"
                  th:text="#{SCHEDULE.BOOKED_BY_OTHER}">Booked</span>
          </td>
          <td>
            <!--/* los botones mostrados los ha decidido el controlador
                   (bookable, appointmentId) según el rol del usuario */-->
            <!--/* "Book" es un simple enlace: reabre esta página
                   con el diálogo de reserva de esta franja */-->
            <a th:if="${row.bookable}" class="btn btn-sm btn-outline-success"
               th:href="${row.bookUrl}" th:text="#{SCHEDULE.BOOK}">Book</a>
            <!--/* "Cancel" MODIFICA datos: por eso es un POST */-->
            <form th:if="${row.appointmentId != null}" method="post" action="/schedule/cancel" class="m-0"
                  th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
              <input type="hidden" name="appointmentId" th:value="${row.appointmentId}">
              <input type="hidden" name="doctorId" th:value="${model.doctorId}">
              <input type="hidden" name="day" th:value="${model.day}">
              <button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{SCHEDULE.CANCEL_APPOINTMENT}">Cancel</button>
            </form>
          </td>
        </tr>
      </tbody>
    </table>
    <p class="text-muted mb-0" th:if="*{rows.isEmpty()}" th:text="#{SCHEDULE.NO_SLOTS}">No slots.</p>
  </div>
  <p class="text-muted" th:if="${model.schedule == null}" th:text="#{SCHEDULE.EMPTY_STATE}">Choose a doctor...</p>

  <!--/* 3. el diálogo de reserva, solo si la URL contiene &book=... */-->
  <th:block th:if="${model.booking != null}">
    <div th:replace="~{fragments/booking :: booking}"></div>
  </th:block>

</main>
</body>
</html>

Analicemos este código:

  • Líneas 17–35: selección del médico y del día: un formulario GET (véase el ejemplo 17), que recarga la página con [?doctorId=...&day=...] en la URL. Cada médico es un [OptionView] que indica si está seleccionado ([th:selected]). Un campo [type="date"] envía la fecha en formato [yyyy-MM-dd] (véase el ejemplo 18);
  • Líneas 38–41: el mensaje para un paciente que ya tiene una cita próxima: explica por qué faltan los botones «Reservar» y proporciona un enlace a «Mi espacio». El controlador no envía este mensaje cuando la cita del paciente aparece en la agenda mostrada (véase [patientInfo]). [#{${model.info}}]: la clave del mensaje la proporciona el controlador;
  • línea 44: la agenda, si se solicitó. [th:object] hace referencia a un objeto de selección: dentro del elemento, [*{day}] equivale a [${model.schedule.day}];
  • línea 45: el título: «Agenda del viernes 25 de septiembre de 2026 - Mme Marie PELISSIER», mediante una sustitución literal;
  • línea 47: la tabla se escribe solo si la agenda tiene filas ([th:unless]: a menos que...);
  • línea 56: una línea por horario. Un horario reservable cambia de color al pasar el mouse (clase [free-slot], véase [styles.css]);
  • Líneas 62–67: tres casos: disponible; reservado, con el nombre del paciente (en azul si es la cita del paciente que inició sesión, [mine]; en gris en caso contrario); reservado sin nombre visible, «Reservado». El controlador solo completa [patient] si el usuario tiene permiso para ver ese nombre;
  • líneas 74–75: «Reservar» es un enlace: vuelve a abrir esta página, mostrando la ventana de reserva para ese horario ([bookUrl], preparada por el controlador);
  • líneas 77–83: «Cancelar» modifica datos: es un formulario (POST) con confirmación. [th:attr] establece el atributo [data-confirmation], que contiene la pregunta traducida; el script [app.js] intercepta el envío de los formularios que tienen este atributo (véase el ejemplo 21). Los campos ocultos [doctorId] y [day] permiten al controlador redirigir a la misma agenda. Dentro del bucle, [model] siempre se refiere al modelo de la página;
  • líneas 88 y 90: un médico sin horarios disponibles, o aún sin agenda solicitada;
  • líneas 93–95: la ventana de reserva, si el controlador la preparó. La condición se establece en un [th:block] que incluye: el fragmento, que lee [model.booking], se inserta solo si esta ventana existe.

11.17.2.3. templates/persons/list.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/list.html - la lista de los médicos O de los clientes (ADMIN).
   Una sola vista para ambos: las etiquetas específicas de cada uno llegan en
   model.keys (véase DoctorsController / ClientsController).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0" th:text="#{${model.keys.title}}">Doctors</h4>
    <a class="btn btn-primary" th:href="${model.addUrl}" th:text="#{${model.keys.add}}">Add</a>
  </div>

  <div class="card p-3">
    <table class="table table-hover align-middle mb-0" th:unless="${model.persons.isEmpty()}">
      <thead>
        <tr>
          <th th:text="#{PERSONS.COLUMN_TITLE}">Title</th>
          <th th:text="#{PERSONS.COLUMN_FIRSTNAME}">First name</th>
          <th th:text="#{PERSONS.COLUMN_LASTNAME}">Last name</th>
          <th th:text="#{PERSONS.COLUMN_LOGIN}">Login</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr th:each="person : ${model.persons}">
          <td th:text="${person.title}">Mme</td>
          <td th:text="${person.firstName}">Marie</td>
          <td th:text="${person.lastName}">PELISSIER</td>
          <td><code th:text="${person.login}">pelissier</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              <a class="btn btn-sm btn-outline-primary" th:href="${person.editUrl}"
                 th:text="#{PERSONS.EDIT}">Edit</a>
              <!--/* data-confirmation: se abrirá un diálogo de confirmación
                     antes de enviar el formulario (véase static/js/app.js) */-->
              <form method="post" th:action="${person.deleteUrl}" class="m-0"
                    th:attr="data-confirmation=#{${model.keys.confirmDelete}}">
                <button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{PERSONS.DELETE}">Delete</button>
              </form>
            </div>
          </td>
        </tr>
      </tbody>
    </table>
    <p class="text-muted mb-0" th:if="${model.persons.isEmpty()}" th:text="#{${model.keys.empty}}">None.</p>
  </div>
</main>
</body>
</html>
  • líneas 11–12: el título y la etiqueta del botón de agregar: claves de traducción proporcionadas por el controlador ([model.keys]), que difieren para los médicos y para los clientes;
  • Líneas 16 y 47: la tabla, o el mensaje «No hay médicos». («No hay pacientes».) si la lista está vacía;
  • línea 27: una línea por persona;
  • línea 31: el inicio de sesión, en una fuente monoespaciada ([<code>]);
  • líneas 34–35: «Editar» es un enlace al formulario de edición;
  • líneas 38–41: «Eliminar» modifica datos: es un formulario POST, con confirmación. La pregunta de confirmación es una clave proporcionada por el controlador: [#{${model.keys.confirmDelete}}]; su dirección ([th:action]) también.

11.17.2.4. templates/persons/form.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/form.html - creación O edición de un
   médico o un cliente (ADMIN). model.creating distingue los dos casos.

   Cuando se rechaza la entrada (campo vacío, login ya tomado...), el
   controlador devuelve ESTA vista con:
     - los valores ya escritos (model.values);
     - los campos defectuosos resaltados en rojo (clase Bootstrap "is-invalid");
     - bajo un campo rechazado por la validación, su mensaje;
     - el mensaje de error de la página, mostrado AL PIE de la página por el
       layout (véase fragments/errors.html).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3" th:text="#{${model.pageTitle}}">Add a doctor</h5>

      <!--/* novalidate: dejamos que el SERVIDOR valide (es quien tiene la autoridad);
             las verificaciones del navegador (required...) son solo una comodidad,
             que un usuario siempre puede eludir */-->
      <form method="post" th:action="${model.action}" novalidate>
        <input type="hidden" name="version" th:unless="${model.creating}" th:value="${model.values.version}">

        <!--/* título, nombre, apellido: fragmento común a tres formularios */-->
        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="off"
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('login') == null}"
               th:text="${model.creating} ? #{PERSONS.LOGIN_HELP_CREATE} : #{PERSONS.LOGIN_HELP_EDIT}">help</div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
          <!--/* nunca prellenado: la contraseña nunca vuelve al navegador */-->
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control" th:classappend="${state.invalidClass('password')}">
          <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
               th:text="#{${state.errorOf('password')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('password') == null}"
               th:text="${model.creating} ? #{PERSONS.PASSWORD_HELP_CREATE} : #{PERSONS.PASSWORD_HELP_EDIT}">help</div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
          <a class="btn btn-secondary" th:href="${model.listUrl}" th:text="#{PERSONS.BACK}">Back</a>
        </div>
      </form>
    </div>
  </div>
</main>
</body>
</html>
  • línea 16: [state]: el estado del formulario, para la parte no incluida en el fragmento común;
  • línea 19: el título: «Agregar un médico», «Editar un paciente», etc.;
  • Línea 24: la dirección de envío, proporcionada por el controlador. [novalidate]: el navegador no verifica por sí mismo estos campos ([required], [maxlength]); el servidor los valida y es la fuente autorizada (véase el ejemplo 19);
  • línea 25: la versión del registro (bloqueo optimista), solo para una modificación;
  • línea 28: los campos de título, nombre y apellido, mediante el fragmento común. [th:replace] en un [th:block]: el fragmento reemplaza al bloque;
  • líneas 34–39: el inicio de sesión, con su mensaje de error o, en su defecto, su texto de ayuda, que depende del modo: [${model.creating} ? #{...} : #{...}] elige entre dos mensajes;
  • líneas 45–50: la contraseña, que nunca se completa previamente; nunca se vuelve a enviar al navegador;
  • línea 55: regreso a la lista.

11.17.2.5. templates/registration.html

<!doctype html>
<!--/* =========================================================================
   templates/registration.html - "Create a client account" (página pública,
   véase RegistrationController). Mismos campos de identidad que el formulario
   del ADMIN (fragmento person-fields), pero el login y la contraseña
   son obligatorios, con confirmación.
   Aquí NO hay captcha: solo se llega a esta página después de haber copiado
   el de la página de autenticación (botón "Create a client account").

   #{${key}('min', ${model.passwordMin()})}: el mensaje cuya clave es
   el valor de [key], con el parámetro {min} (véase web/Translator.java).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1" th:text="#{REGISTRATION.TITLE}">Create a client account</h5>
      <p class="text-muted small mb-3" th:text="#{REGISTRATION.INTRO}">intro</p>

      <form method="post" action="/register" novalidate>
        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('login') == null}" th:text="#{REGISTRATION.LOGIN_HELP}">help</div>
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control" th:classappend="${state.invalidClass('password')}">
            <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
                 th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
            <div class="form-text" th:if="${state.errorOf('password') == null}"
                 th:text="#{REGISTRATION.PASSWORD_HELP('min', ${model.passwordMin()})}">help</div>
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control" th:classappend="${state.invalidClass('confirmation')}">
            <div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
                 th:text="#{${state.errorOf('confirmation')}}">error</div>
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{REGISTRATION.SUBMIT}">Create my account</button>
          <a class="btn btn-secondary" href="/login" th:text="#{REGISTRATION.BACK_TO_LOGIN}">Back</a>
        </div>
      </form>
    </div>
  </div>
</main>
</body>
</html>
  • línea 21: el formulario, enviado mediante POST a [/register], validado por el servidor ([novalidate]);
  • línea 22: los campos de identidad, que son los mismos que los del formulario de ADMIN;
  • líneas 26–33: el inicio de sesión, que aquí es obligatorio;
  • líneas 37–43: la contraseña. El mensaje de error «La contraseña debe tener al menos {min} caracteres» tiene un parámetro: [#{${key}('min', ${model.passwordMin()})}] pasa tanto una clave calculada como un parámetro (la longitud mínima establecida en [models/InputRules.java]), que lee un método del modelo;
  • líneas 46–50: confirmación de la contraseña, comparada por el validador;
  • línea 56: el usuario es redirigido de vuelta a la página de inicio de sesión.

11.17.2.6. templates/area.html

<!doctype html>
<!--/* =========================================================================
   templates/area.html - "My area": la página de inicio del paciente
   (rol USER), que se muestra justo después de su login.
     - dos opciones: [Manage my account] y [View a schedule];
     - su cita próxima, si la tiene, con los medios para cancelarla.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h4 class="mb-3" th:text="#{AREA.HELLO('name', ${model.patient})}">Hello Mme Alice DURAND</h4>

  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
        <h5 class="mb-1" th:text="#{AREA.MANAGE_ACCOUNT}">Manage my account</h5>
        <span class="text-muted" th:text="#{AREA.MANAGE_ACCOUNT_HELP}">help</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
        <h5 class="mb-1" th:text="#{AREA.VIEW_SCHEDULE}">View a schedule</h5>
        <span class="text-muted" th:text="#{AREA.VIEW_SCHEDULE_HELP}">help</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5 th:text="#{AREA.MY_APPOINTMENT}">My appointment</h5>
    <!--/* normalmente solo una (regla "una cita futura a la vez"),
           pero la página puede mostrar varias. [status]: una variable
           de iteración proporcionada por th:each (status.last: ¿último elemento?) */-->
    <div th:each="appointment, status : ${model.appointments}"
         class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2"
         th:classappend="${status.last} ? '' : 'border-bottom'">
      <div>
        <div class="fw-semibold" th:text="|${appointment.day}, ${appointment.time}|">Wednesday 23 September 2026, 8:00 - 8:20</div>
        <div class="text-muted">
          <span th:text="${appointment.doctor}">Mme Marie PELISSIER</span> -
          <a th:href="${appointment.scheduleUrl}" th:text="#{AREA.SEE_IN_SCHEDULE}">see in the schedule</a>
        </div>
      </div>
      <form method="post" action="/my-area/cancel" class="m-0"
            th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
        <input type="hidden" name="appointmentId" th:value="${appointment.id}">
        <button type="submit" class="btn btn-outline-danger" th:text="#{AREA.CANCEL_APPOINTMENT}">Cancel</button>
      </form>
    </div>
    <p class="text-muted mb-0" th:if="${model.appointments.isEmpty()}" th:text="#{AREA.NO_APPOINTMENT}">No appointment.</p>
  </div>
</main>
</body>
</html>
  • línea 11: «Hola Mr Jean MARTIN»: un mensaje con un parámetro [{name}];
  • líneas 13–26: las dos opciones de la página, tarjetas grandes en las que se puede hacer clic (enlaces) que responden al pasar el mouse (clase [option-card], véase [styles.css]);
  • líneas 33–35: la cita próxima. Normalmente solo hay una (una cita próxima por paciente), pero la página puede mostrar varias. [th:each="appointment, status : ..."] declara, después de la variable del bucle, una variable de estado proporcionada por [Thymeleaf]: [status.last] indica si el elemento es el último de la lista; todos los demás se separan mediante un separador ([border-bottom]);
  • línea 37: la fecha y la hora, ya formateadas por el controlador;
  • línea 40: el enlace a la agenda del médico para ese día, donde el paciente ve su nombre;
  • líneas 43–47: la cancelación, un formulario POST con confirmación;
  • línea 49: no hay citas próximas.

11.17.2.7. templates/account.html

<!doctype html>
<!--/* =========================================================================
   templates/account.html - "Manage my account" (rol USER).
   Dos formularios independientes en la misma página:
     1. la edición (identidad, login, nueva contraseña opcional);
     2. la eliminación de la cuenta - que también cancela sus citas.
   Ambos requieren la contraseña ACTUAL.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">

    <!--/* 1. edición */-->
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3" th:text="#{MY_ACCOUNT.TITLE}">Manage my account</h5>

      <form method="post" action="/my-account" novalidate>
        <input type="hidden" name="version" th:value="${model.values.version}">

        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password" th:text="#{MY_ACCOUNT.NEW_PASSWORD_LABEL}">New password</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control" th:classappend="${state.invalidClass('password')}">
            <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
                 th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
            <div class="form-text" th:if="${state.errorOf('password') == null}"
                 th:text="#{PERSONS.PASSWORD_HELP_EDIT}">help</div>
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control" th:classappend="${state.invalidClass('confirmation')}">
            <div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
                 th:text="#{${state.errorOf('confirmation')}}">error</div>
          </div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="currentPassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
          <input id="currentPassword" name="currentPassword" type="password" maxlength="72"
                 autocomplete="current-password" required
                 class="form-control" th:classappend="${state.invalidClass('currentPassword')}">
          <div class="invalid-feedback" th:if="${state.errorOf('currentPassword') != null}"
               th:text="#{${state.errorOf('currentPassword')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('currentPassword') == null}"
               th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_HELP}">help</div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
          <a class="btn btn-secondary" href="/my-area" th:text="#{MY_ACCOUNT.BACK}">Back</a>
        </div>
      </form>
    </div>

    <!--/* 2. eliminación */-->
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1" th:text="#{MY_ACCOUNT.DELETE_TITLE}">Delete my account</h5>
      <p class="text-muted small" th:text="#{MY_ACCOUNT.DELETE_HELP}">help</p>
      <form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
            th:attr="data-confirmation=#{MY_ACCOUNT.DELETE_CONFIRM}">
        <div class="flex-grow-1">
          <label class="form-label" for="deletePassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
          <input id="deletePassword" name="deletePassword" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger" th:text="#{MY_ACCOUNT.DELETE_SUBMIT}">Delete my account</button>
      </form>
    </div>

  </div>
</main>
</body>
</html>
  • líneas 15–68: modificación de la cuenta: identidad, inicio de sesión, nueva contraseña (opcional) y su confirmación;
  • línea 19: la versión del registro del cliente (bloqueo optimista);
  • líneas 52–61: contraseña actual, obligatoria para cualquier cambio;
  • líneas 71–83: eliminación, con confirmación. Dos formularios independientes en la misma página: cada uno envía solo sus propios campos. Por eso el campo de la contraseña tiene aquí un nombre distinto ([deletePassword]) y un identificador distinto. Este formulario no tiene el atributo [novalidate]: el navegador exige la contraseña ([required]) incluso antes de activar el evento [submit], es decir, antes de pedir confirmación.

11.17.2.8. templates/error.html

<!doctype html>
<!--/* =========================================================================
   templates/error.html - la página de error (400, 403, 404, 500...),
   construida por ErrorController.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger" th:text="${model.code}">404</h1>
      <p class="lead" th:text="#{${model.message}}">This page does not exist.</p>
      <div><a class="btn btn-primary" href="/" th:text="#{ERROR_PAGE.BACK}">Back to home</a></div>
    </div>
  </div>
</main>
</body>
</html>
  • Líneas 11–12: la página de error generada por [ErrorController] (400, 403, 404, 500): el código HTTP y el mensaje traducido. Usa la misma plantilla que las demás páginas: el usuario conserva su barra de navegación.

11.18. Los diccionarios

Los diccionarios son los de la versión [ASP.NET Core MVC], sin cambios: se almacenan en [src/main/resources/i18n] y el servicio [Translator] los lee al iniciar (véase «La capa web: servicios comunes»). Este servicio «aplana» su estructura: el texto ["TITLE"] de la sección ["LOGIN"] se convierte en la clave de mensaje [LOGIN.TITLE], que utilizan las vistas ([#{LOGIN.TITLE}]) y los controladores.

11.18.1. i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
  • Las secciones agrupan los textos por página ([LOGIN], [SCHEDULE], [AREA]...) o por tema ([ERRORS], [CONFIRMATION]). Algunos nombres ([DOCTOR_DAY_PICKER], [BOOKING_DIALOG]) provienen de las primeras versiones de la aplicación, cuyo cliente se escribió con [Angular];
  • línea 80: texto con dos parámetros, [{name}] y [{login}], que se reemplazan durante la traducción;
  • Líneas 98–137: mensajes de error. Son las claves utilizadas por la [BusinessException] de la capa de negocio, las anotaciones de validación de los formularios ([@NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")]), los controladores y la página de error. Tres de ellos tienen un parámetro: [{minutes}] (líneas 124 y 126) y [{min}] (línea 129).

11.18.2. i18n/en.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

El diccionario en inglés tiene exactamente las mismas claves en las mismas líneas.

11.19. Los archivos estáticos

[Spring Boot] sirve tal cual los archivos de la carpeta [src/main/resources/static] (véase el ejemplo 15): [static/css/styles.css] se sirve en la dirección [/css/styles.css]. Estas direcciones se declaran públicas en [SecurityConfig], para que la página de inicio de sesión tenga sus estilos. La carpeta [static/lib/bootstrap] contiene [Bootstrap] (su hoja de estilo [css/bootstrap.min.css] y su licencia), que no se muestra.

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - algunos ajustes sobre Bootstrap
   (los mismos que en la versión ASP.NET Core MVC de esta aplicación).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: los mensajes de error, al pie de la página, sobre un fondo rosa claro
   (véase templates/fragments/errors.html).
   position: sticky + bottom: si la página es más alta que la ventana (una
   agenda de 12 franjas, por ejemplo), la zona se queda pegada al pie de la
   ventana en lugar de desaparecer bajo el borde inferior - sin tapar nunca el
   contenido cuando la página es corta.
   z-index: por encima del fondo gris del diálogo de reserva (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* las dos grandes opciones de la página "My area" del paciente */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* la imagen del captcha (SVG de 150 x 50 píxeles) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • líneas 10–12: un horario reservable cambia de color al pasar el mouse;
  • líneas 23–33: el área de errores, sobre un fondo rosa claro. [position: sticky] y [bottom: 1rem]: si la página es más alta que la ventana, el área permanece en la parte inferior de la ventana en lugar de desaparecer de la pantalla; [z-index] la coloca por encima del fondo atenuado de la ventana de reserva;
  • líneas 36–43: las dos opciones de «Mi espacio» responden al pasar el mouse;
  • líneas 46–50: el marco de la imagen del CAPTCHA.

11.19.2. static/js/app.js

// =========================================================================
// static/js/app.js - el ÚNICO JavaScript de la aplicación.
// -------------------------------------------------------------------------
// Toda la aplicación funciona sin JavaScript. Este script añade una
// comodidad: antes de enviar un formulario que lleva el atributo
// data-confirmation="...", un diálogo modal pregunta "Are you sure?"
// (el diálogo mismo está en la página: templates/fragments/confirmation.html).
// Si JavaScript está desactivado, el formulario simplemente se envía sin
// confirmación - nada se rompe (principio de "mejora progresiva").
//
// ¿Por qué no window.confirm()? Su cuadro no se puede personalizar y sus
// botones permanecen en el idioma del navegador, no en el de la página.
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // el formulario que se enviará si el usuario confirma
  let previousFocus = null; // el elemento al que devolver el foco al cerrar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (y no innerHTML): el mensaje se muestra como TEXTO,
    // nunca interpretado como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // el foco va a "No": una pulsación distraída de Enter no elimina nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. interceptamos el envío de los formularios que requieren confirmación
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. los botones del diálogo (Yes / No / cruz de cierre)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envía el formulario SIN volver a disparar el evento
      // 'submit': no hay nueva solicitud de confirmación
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clic en el fondo gris, fuera del diálogo
    }
  });

  // 3. teclado: Escape cierra el diálogo; Tab permanece DENTRO del diálogo
  //    (de lo contrario el foco iría a la página atenuada, detrás)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

El script de la ventana de confirmación del ejemplo 21, mejorado con el manejo del teclado. Sigue el mismo principio de mejora progresiva: sin [JavaScript], los formularios se envían sin confirmación y la aplicación sigue funcionando.

  • Línea 15: todo el script está encerrado en una función, que se llama de inmediato ([(() => { ... })()]): sus variables no son visibles para otros scripts de la página;
  • Líneas 16–19: una página sin ventana de confirmación no tiene nada que hacer;
  • Línea 24: el elemento que tenía el foco del teclado (el que recibe las pulsaciones de teclas) antes de que se abriera la ventana: el foco vuelve a él cuando la ventana se cierra;
  • líneas 26–35: la ventana se abre con el mensaje específico del formulario ([form.dataset.confirmation] es el valor de su atributo [data-confirmation]); el foco se coloca en «No, volver»: presionar Enter por accidente no elimina nada;
  • líneas 37–43: la ventana se oculta y se restaura el foco;
  • líneas 46–51: se interceptan los envíos de formularios con el atributo [data-confirmation], como en el ejemplo 21;
  • líneas 54–67: «Sí», «No», el botón de cierre y el clic fuera de la ventana. [closest('[data-action]')] encuentra el elemento con el atributo, incluso si se hizo clic en un elemento contenido en él. El operador [?.] devuelve [undefined] en lugar de fallar cuando no se encuentra ningún elemento;
  • líneas 71–86: la tecla Esc cierra la ventana; la tecla Tab (y Shift+Tab) recorre cíclicamente el foco entre los botones de la ventana, en lugar de dejar que pase a la página atenuada que está detrás.