La forma más fácil de migrar tu proyecto a la última versión de OpenXava es pedírselo a tu asistente IA:
Migra mi proyecto a OpenXava 8.0.1 siguiendo estas instrucciones:
https://openxava.org/OpenXavaDoc/docs/migration_es.html
Aplica solo las secciones posteriores a la versión de OpenXava de mi pom.xml.
Si tu asistente IA no puede acceder a la web, copia y pega el contenido de esta página en lugar de la URL. Después, revisa los cambios y prueba tu aplicación.
Edita el archivo pom.xml de tu proyecto y cambia el valor de la propiedad openxava.version para que apunte a la última versión de OpenXava, así:
<properties>
<openxava.version>8.0.1</openxava.version>
...
</properties>
Si tu versión actual es anterior a la 8.0 deberías seguir las instrucciones de la sección Para migrar de OpenXava 7.7.3 a OpenXava 8.0 primero.
Para finalizar, revisa las instrucciones de abajo para adaptar tu código.
No hay consideraciones.
Ahora Java 17 es la versión mínima soportada. Si tu proyecto todavía usa Java 8 u 11 deberías actualizarlo para que compile con Java 17, 21 o 25. Para ello modifica el pom.xml:
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
...
</properties>
Asegúrate de tener instalado un JDK 17 (o superior) en tu sistema y configurado en tu IDE.
Puedes consultar la documentación oficial de Java de migración a Java 17 y si usas Java 8 la documentación de migración desde Java 8.
Si estabas usando la funcionalidad de chat con IA en la versión 7.7, tenías que añadir la dependencia openxava-7.7-chat-jdk17 a tu pom.xml. En la versión 8.0 esta dependencia ya no es necesaria porque la funcionalidad de chat ahora está incluida en el núcleo de OpenXava.
Elimina la siguiente dependencia de tu pom.xml:
<!-- Elimina esta dependencia -->
<dependency>
<groupId>org.openxava</groupId>
<artifactId>openxava-7.7-chat-jdk17</artifactId>
<version>${openxava.version}</version>
</dependency>
Si no la eliminas, tu build fallará porque este artefacto no existe en la versión 8.0.
Los proyectos creados a partir de los arquetipos de OpenXava 7.7 incluyen un archivo AGENTS.md con instrucciones para los asistentes de codificación con IA, y una carpeta .xava con ejemplos de código para ellos. En OpenXava 8.0 el artefacto openxava-agents-examples ya no existe, por lo que tienes que eliminar la ejecución unpack-agents-examples del maven-dependency-plugin de tu pom.xml:
<!-- Elimina esta ejecución -->
<execution>
<id>unpack-agents-examples</id>
<phase>initialize</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.openxava</groupId>
<artifactId>openxava-agents-examples</artifactId>
<version>${openxava.version}</version>
<outputDirectory>.xava</outputDirectory>
<includes>agents/**</includes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
Si no la eliminas, tu build fallará porque este artefacto no existe en la versión 8.0. Mantén la otra ejecución que desempaqueta los DTDs (xava/dtds/*).
Después borra la carpeta .xava de tu proyecto y elimina la entrada /.xava/ de tu .gitignore.
Por último, actualiza tu AGENTS.md. La nueva versión indica al asistente de IA que use siempre imports jakarta.* (nunca javax.*) y apunta a los ejemplos de código directamente en GitHub en lugar de la carpeta local .xava. La forma más sencilla es reemplazar tu AGENTS.md por el incluido en el arquetipo de OpenXava 8.0. Si prefieres mantener tu archivo actual, al menos elimina las referencias a ./.xava/agents/test y añade una nota para usar imports jakarta.*.
En OpenXava 7.7 la aplicación se arrancaba con una clase lanzadora personalizada ubicada en el paquete run, que llamaba a AppServer.run() para iniciar un Tomcat embebido, y se ejecutaba con mvn exec:java (configurado mediante el exec-maven-plugin). En OpenXava 8.0 la aplicación es una aplicación Spring Boot estándar que se arranca con mvn spring-boot:run.
Elimina tu antigua clase lanzadora (la del paquete run) y crea una clase de aplicación Spring Boot que extienda org.openxava.spring.OpenXavaApplication. Colócala en el paquete raíz de tu aplicación:
// ANTES: src/main/java/com/yourcompany/yourapp/run/yourapp.java
package com.yourcompany.yourapp.run;
import org.openxava.util.*;
public class yourapp {
public static void main(String[] args) throws Exception {
DBServer.start("yourapp-db");
AppServer.run("yourapp");
}
}
// DESPUÉS: src/main/java/com/yourcompany/yourapp/YourappApplication.java
package com.yourcompany.yourapp;
import org.openxava.util.DBServer;
import org.openxava.spring.OpenXavaApplication;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class YourappApplication extends OpenXavaApplication {
public static void main(String[] args) throws Exception {
DBServer.start("yourapp-db"); // Solo para el HSQLDB incluido, elimínalo si usas tu propia base de datos
SpringApplication.run(YourappApplication.class, args);
}
}
Extender OpenXavaApplication (que a su vez extiende SpringBootServletInitializer) hace que la aplicación funcione tanto al lanzarla con Spring Boot como al desplegarla como WAR en un contenedor de servlets externo.
En tu pom.xml, elimina el exec-maven-plugin y añade el spring-boot-maven-plugin apuntando a tu nueva clase de aplicación:
<!-- ELIMINA este plugin -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<mainClass>${project.groupId}.${project.artifactId}.run.${project.artifactId}</mainClass>
</configuration>
</plugin>
<!-- AÑADE este plugin -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.0</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
<configuration>
<mainClass>com.yourcompany.yourapp.YourappApplication</mainClass>
</configuration>
</plugin>
Además, como ahora el servidor embebido lo proporciona Spring Boot, no debes excluir los jars de Tomcat de tu WAR. Elimina la línea WEB-INF/lib/tomcat-*.jar de los packagingExcludes del maven-war-plugin si está presente.
En OpenXava 7.7 el datasource se declaraba mediante JNDI en src/main/webapp/META-INF/context.xml. Con Spring Boot eliminas de ese fichero las declaraciones del datasource (las entradas <Resource>) y defines el datasource en src/main/resources/application.properties en su lugar. OpenXava enlaza este datasource de Spring con el nombre JNDI usado en persistence.xml, así que no necesitas cambiar persistence.xml.
server.servlet.context-path=/yourapp
server.tomcat.additional-tld-skip-patterns=htmlunit-*.jar,jetty-*.jar
spring.datasource.username=sa
spring.datasource.password=
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=10000
# HSQLDB
spring.datasource.url=jdbc:hsqldb:hsql://localhost:1666
spring.datasource.driver-class-name=org.hsqldb.jdbcDriver
Si tu aplicación usa más de un datasource (por ejemplo porque tiene persistence-unit secundarias en persistence.xml), declara los adicionales en el mismo application.properties usando el prefijo openxava.datasources.<nombre>.*. El datasource por defecto sigue usando spring.datasource.*. OpenXava crea cada datasource adicional y lo enlaza al nombre JNDI declarado en su propiedad jndi, que debe coincidir con el usado en persistence.xml. No hace falta ninguna clase de configuración Java:
openxava.datasources.companya.jndi=jdbc/companyaDS
openxava.datasources.companya.url=jdbc:hsqldb:file:data/company-a-db
openxava.datasources.companya.username=sa
openxava.datasources.companya.password=
openxava.datasources.companya.driver-class-name=org.hsqldb.jdbcDriver
openxava.datasources.companya.maximum-pool-size=20
openxava.datasources.companya.minimum-idle=5
openxava.datasources.companya.connection-timeout=10000
openxava.datasources.companyb.jndi=jdbc/companybDS
openxava.datasources.companyb.url=jdbc:hsqldb:file:data/company-b-db
openxava.datasources.companyb.username=sa
openxava.datasources.companyb.password=
openxava.datasources.companyb.driver-class-name=org.hsqldb.jdbcDriver
Así toda la configuración de base de datos de tu aplicación queda en un único fichero declarativo, equivalente al antiguo context.xml pero al estilo estándar de Spring Boot.
Para arrancar la aplicación usa:
mvn spring-boot:run
El antiguo comando mvn exec:java ya no se aplica.
Cuando la aplicación se ejecuta con el Tomcat embebido de Spring Boot, el archivo src/main/webapp/WEB-INF/web.xml no se procesa. Esto significa que cualquier servlet, filtro o listener declarado en web.xml no se registrará. Debes declarar tus servlets personalizados usando la anotación @WebServlet (y @WebFilter, @WebListener para filtros y listeners) en la propia clase Java:
<!-- ANTES: src/main/webapp/WEB-INF/web.xml -->
<servlet>
<servlet-name>testServlet</servlet-name>
<servlet-class>com.yourcompany.yourapp.servlets.TestServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>testServlet</servlet-name>
<url-pattern>/test</url-pattern>
</servlet-mapping>
// DESPUÉS: src/main/java/com/yourcompany/yourapp/servlets/TestServlet.java
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
@WebServlet("/test")
public class TestServlet extends HttpServlet {
// ...
}
La auto-configuración de OpenXava ya escanea los paquetes org.openxava y com.openxava en busca de anotaciones @WebServlet, @WebFilter y @WebListener, por lo que si tus servlets están en esos paquetes se detectarán automáticamente. Si tus servlets están en un paquete diferente, añade @ServletComponentScan a tu clase de aplicación con los paquetes base correspondientes.
Dado que web.xml ya no es necesario, deberías eliminar el archivo src/main/webapp/WEB-INF/web.xml. Cuando la aplicación se despliega como WAR en un contenedor de servlets externo, las anotaciones son procesadas por el contenedor automáticamente, por lo que web.xml no es necesario en ningún escenario.
Con Spring Boot el sistema de logging ha cambiado, por lo que las propiedades javaLoggingLevel y hibernateJavaLoggingLevel de xava.properties ya no tienen efecto. Ahora configuras el nivel de logging en application.properties.
Antes en xava.properties:
javaLoggingLevel=FINE
hibernateJavaLoggingLevel=FINE
Después en application.properties:
logging.level.org.openxava=DEBUG
logging.level.org.hibernate=DEBUG
Los niveles equivalentes son: SEVERE = ERROR, WARNING = WARN, INFO = INFO, FINE = DEBUG, FINER/FINEST = TRACE.
OpenXava 8.0 usa Jakarta Persistence 3.2 y Hibernate 7.4. Esto implica cambios significativos respecto a las versiones anteriores. A continuación detallamos los problemas más comunes que puedes encontrar al migrar tu aplicación.
Puedes consultar la guía de migración oficial de Hibernate para más información.
El cambio principal es el reemplazo del namespace javax por jakarta en todas las anotaciones de JPA. Esto afecta a tus entidades, clases clave, y cualquier código que use anotaciones de persistencia.
// ANTES
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.ManyToOne;
// DESPUÉS
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;
Además, si usas import org.hibernate.annotations.*; en tus archivos, esto puede causar ambigüedad entre org.openxava.annotations.View y org.hibernate.annotations.View. La solución es usar imports específicos:
// ANTES
import org.hibernate.annotations.*;
// DESPUÉS
import org.hibernate.annotations.GenericGenerator;
import org.hibernate.annotations.Parameter;
import org.hibernate.annotations.Type;
El archivo persistence.xml requiere actualizar el namespace a la versión 3.2 de Jakarta Persistence:
<persistence version="3.2"
xmlns="https://jakarta.ee/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence
https://jakarta.ee/xml/ns/persistence/persistence_3_2.xsd">
El formato del nombre JNDI de la fuente de datos en persistence.xml ha cambiado. En OpenXava 7.x el nombre usaba java:// como prefijo, pero en OpenXava 8.0 debes usar java: (sin la doble barra). El formato anterior con // no funciona en 8.0:
<!-- ANTES (7.x) -->
<non-jta-data-source>java://comp/env/jdbc/yourappDS</non-jta-data-source>
<!-- DESPUÉS (8.0) -->
<non-jta-data-source>java:comp/env/jdbc/yourappDS</non-jta-data-source>
Si usas propiedades para generación de esquema en tu persistence.xml, debes actualizarlas de javax.persistence.* a jakarta.persistence.*:
<!-- ANTIGUO (javax) -->
<property name="javax.persistence.schema-generation.database.action" value="update"/>
<property name="javax.persistence.create-database-schemas" value="true"/>
<!-- NUEVO (jakarta) -->
<property name="jakarta.persistence.schema-generation.database.action" value="update"/>
<property name="jakarta.persistence.create-database-schemas" value="true"/>
La propiedad hibernate.jdbc.factory_class con valor org.hibernate.jdbc.NonBatchingBatcherFactory ya no es válida en Hibernate 7. Elimina esta propiedad de tu persistence.xml.
En Hibernate 7 la clase org.hibernate.dialect.MySQL5Dialect ha sido eliminada. Si tu persistence.xml la usa, sustitúyela por org.hibernate.dialect.MySQLDialect. Si se usa la clase antigua, Hibernate recurre a otro dialecto y falla durante la generación del esquema (por ejemplo con Unknown table 'sequences' in information_schema):
<!-- ANTES (7.x) -->
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQL5Dialect"/>
<!-- DESPUÉS (8.0) -->
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>
Hibernate 7 requiere MySQL 8.0 o superior. Genera datetime(6) para campos Timestamp y utiliza sentencias DELETE con un alias que versiones anteriores de MySQL no soportan correctamente.
La URL JDBC también debe incluir el nombre de la base de datos de forma explícita. Una URL sin base de datos, como jdbc:mysql://localhost:3306, provocará errores No database selected. Debes usar una URL del tipo jdbc:mysql://localhost:3306/miaplicaciondb:
# ANTES
spring.datasource.url=jdbc:mysql://localhost:3306
# DESPUÉS
spring.datasource.url=jdbc:mysql://localhost:3306/miaplicaciondb
Hibernate 7 ya no permite usar @Column(scale=..., precision=...) ni @Digits(integer=..., fraction=...) en tipos float o double:
// ERROR en Hibernate 7
@Column(scale=7, precision=7)
private double axisY;
Solución: Usa @DecimalMax de Jakarta Validator en su lugar:
// Solución válida
@DecimalMax("0.9999999")
private double axisY;
En Hibernate 6+ las uniones anidadas deben usar la ruta completa desde la entidad raíz. No puedes usar el alias de un join previo como prefijo para un join anidado.
// INCORRECTO (Falla en Hibernate 6+)
SELECT e FROM Product2 e
LEFT JOIN e.subfamily e_subfamily
LEFT JOIN e_subfamily.family e_subfamily_family -- ¡Error!
// CORRECTO (Ruta completa desde la entidad raíz)
SELECT e FROM Product2 e
LEFT JOIN e.subfamily e_subfamily
LEFT JOIN e.subfamily.family e_subfamily_family -- ¡Correcto!
Si ordenas o filtras por un campo común (como name, id, description, code, etc.) y la consulta tiene JOINs, Hibernate lanzará la excepción Ambiguous unqualified attribute reference. Debes calificar siempre las referencias a propiedades con el alias de su entidad:
// INCORRECTO (Falla en Hibernate 6+)
SELECT e FROM Traveler e
LEFT JOIN e.lastJourney e_lastJourney
ORDER BY name -- ¡Error! 'name' existe en Traveler y en Journey
// CORRECTO
SELECT e FROM Traveler e
LEFT JOIN e.lastJourney e_lastJourney
ORDER BY e.name -- ¡Correcto!
Hibernate 7 no permite usar el alias de una función de agregado (como sum()) en la cláusula GROUP BY. Además, todas las propiedades no agregadas del SELECT han de incluirse en el GROUP BY:
// INCORRECTO (Falla en Hibernate 7)
select new org.openxava.invoicedemo.dashboards.InvoicedPerCustomer(i.customer.name, sum(i.total) as amount)
from Invoice i
group by i.customer.number, amount -- ¡Error! 'amount' es un agregado
order by amount desc
// CORRECTO
select new org.openxava.invoicedemo.dashboards.InvoicedPerCustomer(i.customer.name, sum(i.total) as amount)
from Invoice i
group by i.customer.number, i.customer.name -- ¡Correcto!
order by amount desc
Con Hibernate 6/7, las clases @IdClass que contienen campos que son relaciones @ManyToOne deben adaptarse:
// ANTES (No compatible con Hibernate 6/7)
public class CityKey implements Serializable {
@ManyToOne(fetch=FetchType.LAZY)
@JoinColumn(name="STATE", referencedColumnName="ID")
private State state;
private int code;
}
// DESPUÉS (Compatible)
public class CityKey implements Serializable {
private String state; // Tipo de la clave primaria de State
private int code;
}
La entidad principal no requiere cambios en sus anotaciones @Id o @ManyToOne.
En Hibernate 6+ los literales booleanos se compilan directamente a literales booleanos del dialecto SQL, lo que puede romper la compatibilidad con bases de datos que usan tipos CHAR para booleanos (como OpenXava con SiNoType).
// INCORRECTO (Genera error en Hibernate 6+)
Query query = XPersistence.getManager()
.createQuery("from Invoice as o where o.paid = true");
// CORRECTO (Usa parámetros)
Query query = XPersistence.getManager()
.createQuery("from Invoice as o where o.paid = :paid");
query.setParameter("paid", true);
Los tipos personalizados requieren varios cambios en Hibernate 7:
Los tipos personalizados (UserType y CompositeUserType) prácticamente requieren reescribirse para la nueva API de Hibernate 7. Los cambios son profundos e incluyen la eliminación de métodos, cambios en las firmas, y nuevo uso de @Embeddable. Consulta la documentación de Hibernate para los detalles completos.
Para CompositeUserType con múltiples columnas, cambia @Columns por @AttributeOverrides:
// ANTES
@CompositeType(org.openxava.types.Date3Type.class)
@Columns(columns = {
@Column(name="YEARDELIVERY"),
@Column(name="MONTHDELIVERY"),
@Column(name="DAYDELIVERY")
})
// DESPUÉS
@CompositeType(org.openxava.types.Date3Type.class)
@AttributeOverrides({
@AttributeOverride(name="year", column=@Column(name="YEARDELIVERY")),
@AttributeOverride(name="month", column=@Column(name="MONTHDELIVERY")),
@AttributeOverride(name="day", column=@Column(name="DAYDELIVERY"))
})
Las consultas nativas a columnas CHAR ahora devuelven Character en lugar de String. Usa toString() para convertir:
// Antes (Hibernate 5.6)
String value = (String) query.getSingleResult();
// Después (Hibernate 7.4)
String value = query.getSingleResult().toString();
En Hibernate 5 el UUID por defecto era de 32 caracteres (sin guiones), pero en Hibernate 7 es de 36 caracteres (con guiones). Si tienes tablas existentes con columnas dimensionadas para 32 caracteres, necesitas usar la anotación @UUID32 de OpenXava para mantener el formato de 32 caracteres:
// ANTES (Hibernate 5)
@Id @GeneratedValue(generator="system-uuid") @Hidden
@GenericGenerator(name="system-uuid", strategy = "uuid")
@Column(length=32)
private String id;
// DESPUÉS (Hibernate 7 con @UUID32)
@Id @Hidden
@UUID32
@Column(length=32)
private String id;
Import: import org.openxava.annotations.UUID32;
Hibernate 7.4 es mucho más estricto al cumplir la especificación JPA para la anotación @OrderBy. Usar una ruta anidada (como asociacion.propiedad) en @OrderBy lanzará un NullPointerException al arrancar la aplicación durante la creación de la SessionFactory.
De acuerdo con la especificación JPA, @OrderBy debe referirse directamente a atributos básicos de la entidad destino. Si necesitas ordenar una colección basándote en un atributo de una entidad asociada, debes exponer esa columna en la entidad destino como un campo de solo lectura y ordenar por él.
// INCORRECTO (Falla con NullPointerException en Hibernate 7.4)
@OneToMany(mappedBy="role")
@OrderBy("module.name asc")
private Collection<ModuleRights> modulesRights;
// CORRECTO
// 1. Mapea la columna de unión como propiedad básica de solo lectura en la entidad destino (ModuleRights):
@Column(name="modules_name", insertable=false, updatable=false)
private String moduleName;
// 2. Ordena por la propiedad básica en la entidad padre:
@OneToMany(mappedBy="role")
@OrderBy("moduleName asc")
private Collection<ModuleRights> modulesRights;
Hibernate 7.4 genera DDL inválido cuando se usa @Column(columnDefinition=...) con una definición de columna completa que incluye una cláusula DEFAULT y el modo de migración de esquema (jakarta.persistence.schema-generation.database.action=update) está activado. Esto ocurre porque Hibernate concatena todo el columnDefinition como el tipo de columna en la sentencia ALTER COLUMN ... SET DATA TYPE, produciendo SQL que bases de datos como HSQLDB rechazan con unexpected token: DEFAULT.
// INCORRECTO (Genera DDL ALTER inválido en Hibernate 7.4)
@Column(columnDefinition="varchar(1) default 'Y' not null")
private boolean active;
// CORRECTO (Usar atributos JPA estándar + @ColumnDefault)
@Column(length=1, nullable=false)
@org.hibernate.annotations.ColumnDefault("'Y'")
private boolean active;
Este problema se manifiesta típicamente al arrancar, cuando Hibernate intenta migrar el esquema de tablas existentes. La solución es reemplazar el columnDefinition crudo con atributos JPA estándar (length, nullable) para los metadatos de la columna y @org.hibernate.annotations.ColumnDefault para el valor por defecto, que Hibernate trata como metadatos separados en lugar de concatenarlo en la cláusula de tipo.
En Hibernate 7.4, las propiedades byte[] sin @Lob se mapean a una columna varbinary(255) por defecto. Esto es demasiado pequeño para la mayoría de datos binarios (ficheros, imágenes, documentos, etc.) y provoca un error string data, right truncation al arrancar, cuando Hibernate intenta migrar el esquema de tablas existentes que contienen datos mayores de 255 bytes:
// ERROR en Hibernate 7.4 (varbinary(255) es demasiado pequeño)
private byte[] data;
Añade @Lob para que Hibernate mapee la columna a un tipo binario grande (BLOB) en lugar de varbinary(255):
// CORRECTO
@Lob
private byte[] data;
Si usas MySQL y necesitas soportar ficheros de más de 16 MB, añade también @Column(length = Integer.MAX_VALUE) para que MySQL use LONGBLOB en lugar de TINYBLOB o MEDIUMBLOB:
// Para MySQL con ficheros de más de 16 MB
@Lob
@Column(length = Integer.MAX_VALUE)
private byte[] data;
OpenXava 8.0 usa Jakarta Validator 3.1 y Hibernate Validator 9.1. Esto implica cambios en las anotaciones de validación.
Puedes consultar la guía de migración oficial de Hibernate Validator para más información.
Cambia los imports de validación:
// ANTES
import javax.validation.constraints.*;
import javax.validation.Payload;
// DESPUÉS
import jakarta.validation.constraints.*;
import jakarta.validation.Payload;
OpenXava 8.0 ha migrado toda su capa web a la moderna especificación Jakarta Servlet 6.1 sobre Tomcat 11. Esto requiere ajustar cualquier componente servlet personalizado, vistas JSP y configuraciones web en tu aplicación.
Las clases estándar de Java Servlet han cambiado su espacio de nombres de paquetes. Si tu aplicación define filtros, servlets, listeners u otras clases personalizadas relacionadas con servlets, debes renombrar los imports:
// ANTES
import javax.servlet.*;
import javax.servlet.http.*;
import javax.servlet.jsp.*;
// DESPUÉS
import jakarta.servlet.*;
import jakarta.servlet.http.*;
import jakarta.servlet.jsp.*;
Dado que OpenXava 8.0 usa Spring Boot, el archivo web.xml ya no se procesa cuando se ejecuta con el Tomcat embebido. Como se explica en la sección de migración a Spring Boot, deberías eliminar src/main/webapp/WEB-INF/web.xml y declarar tus servlets, filtros y listeners usando anotaciones (@WebServlet, @WebFilter, @WebListener) en su lugar.
Si por alguna razón necesitas mantener web.xml (por ejemplo para un despliegue solo como WAR en un contenedor de servlets externo), debe actualizarse para hacer referencia al espacio de nombres de Servlet 6.1:
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
https://jakarta.ee/xml/ns/jakartaee/web-app_6_1.xsd"
version="6.1">
Las URIs de la biblioteca de etiquetas estándar de JavaServer Pages (JSTL) han cambiado de sus ubicaciones legadas en sun.com al nuevo espacio de nombres jakarta.tags. Si tienes archivos JSP personalizados, debes actualizar las directivas taglib:
<%-- ANTES --%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
<%-- DESPUÉS --%>
<%@ taglib uri="jakarta.tags.core" prefix="c" %>
<%@ taglib uri="jakarta.tags.fmt" prefix="fmt" %>
<%@ taglib uri="jakarta.tags.functions" prefix="fn" %>
OpenXava 8.0 ha actualizado la biblioteca de subida de archivos a Apache Commons FileUpload 2. Esta versión incluye cambios importantes en los nombres de paquetes y el diseño de la API, particularmente alrededor de la interfaz FileItem, que se expone en varias APIs públicas de OpenXava (como WithFileItem, IProcessLoadedFileAction y la anotación @FileItemUpload).
Todas las clases del paquete org.apache.commons.fileupload se han movido. Si tus acciones personalizadas procesan archivos subidos, debes actualizar los imports:
// ANTES
import org.apache.commons.fileupload.FileItem;
// DESPUÉS
import org.apache.commons.fileupload2.core.FileItem;
Si tu aplicación instancia fábricas o controladores de subida manualmente, ten en cuenta que DiskFileItemFactory ahora utiliza un patrón builder, y ServletFileUpload ha sido reemplazado por la implementación específica para Jakarta:
// ANTES
DiskFileItemFactory factory = new DiskFileItemFactory();
ServletFileUpload upload = new ServletFileUpload(factory);
// DESPUÉS
DiskFileItemFactory factory = DiskFileItemFactory.builder().get();
JakartaServletFileUpload upload = new JakartaServletFileUpload(factory);
OpenXava 8.0 ha migrado el cliente REST (JAX-RS, implementado por Jersey) y la API de JSON Binding al espacio de nombres Jakarta. JAX-RS se ha actualizado a 4.0 (Jersey 4.0) y Jakarta JSON Binding a 3.0. Si tu aplicación usa el cliente JAX-RS o las anotaciones de JSON-B (por ejemplo en un servicio que consume un servicio web REST), actualiza los imports del espacio de nombres javax a jakarta:
// ANTES
import javax.ws.rs.client.*;
import javax.json.bind.annotation.*;
// DESPUÉS
import jakarta.ws.rs.client.*;
import jakarta.json.bind.annotation.*;
La API de estas clases (como ClientBuilder, @JsonbProperty, etc.) no cambia, por lo que no es necesario realizar ningún otro cambio en tu código.
Además, OpenXava 8.0 ya no incluye Jersey ni Jakarta JSON Binding como dependencias transitivas del artefacto openxava, porque el propio framework no los usa. Si tu aplicación usa estas librerías, añade las siguientes dependencias a tu pom.xml:
<dependency>
<groupId>jakarta.json.bind</groupId>
<artifactId>jakarta.json.bind-api</artifactId>
<version>3.0.2</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.core</groupId>
<artifactId>jersey-client</artifactId>
<version>4.0.2</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.inject</groupId>
<artifactId>jersey-hk2</artifactId>
<version>4.0.2</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-binding</artifactId>
<version>4.0.2</version>
</dependency>
Si no usas JAX-RS ni JSON-B en tu aplicación, puedes ignorar esta sección.
OpenXava 8.0 ya no incluye Groovy como dependencia transitiva del artefacto openxava, porque el propio framework no lo usa. Groovy se incluía anteriormente para que los desarrolladores de aplicaciones pudieran escribir entidades y otro código en Groovy sin añadir una dependencia adicional.
Si tu aplicación usa Groovy, añade la siguiente dependencia a tu pom.xml:
<dependency>
<groupId>org.apache.groovy</groupId>
<artifactId>groovy</artifactId>
<version>4.0.32</version>
</dependency>
Si no usas Groovy en tu aplicación, puedes ignorar esta sección. Para más detalles sobre el uso de Groovy con OpenXava, consulta la documentación de Groovy.
OpenXava 8.0 ha migrado de javax.inject:1 (JSR 330) a Jakarta Dependency Injection 2.0.1 (jakarta.inject:jakarta.inject-api:2.0.1). Esta es la versión equivalente de la misma especificación JSR 330 bajo Jakarta EE, siendo el único cambio el espacio de nombres de javax.inject a jakarta.inject. Las anotaciones @Inject y @Named funcionan exactamente igual, por lo que si tus acciones o controladores usan inyección de dependencias, solo necesitas actualizar los imports:
// ANTES
import javax.inject.*;
// DESPUÉS
import jakarta.inject.*;
La semántica de @Inject y @Named no cambia. Por ejemplo, el siguiente código de una acción no requiere ninguna modificación más allá del import:
public class AddColumnsAction extends ViewBaseAction {
@Inject @Named("xava_customizingTab")
private Tab tab;
// ...
}
OpenXava 8.0 ha eliminado la última dependencia de javax.ejb. Las antiguas clases de excepciones EJB ya no están disponibles en el classpath, por lo que cualquier código que las usara debe actualizarse a las equivalentes de OpenXava.
Las siguientes excepciones ahora residen en el paquete org.openxava.model y mantienen la misma semántica y jerarquía:
Actualiza los imports de tu código y cualquier cláusula catch o throws que haga referencia a los antiguos nombres de javax.ejb:
// ANTES
import javax.ejb.CreateException;
import javax.ejb.FinderException;
import javax.ejb.ObjectNotFoundException;
import javax.ejb.RemoveException;
import javax.ejb.DuplicateKeyException;
// DESPUÉS
import org.openxava.model.CreateException;
import org.openxava.model.FinderException;
import org.openxava.model.ObjectNotFoundException;
import org.openxava.model.RemoveException;
import org.openxava.model.DuplicateKeyException;
Las API públicas como MapFacade, los proveedores de persistencia y las clases base de acciones ahora lanzan las nuevas excepciones de org.openxava.model. Si capturabas javax.ejb.FinderException, ObjectNotFoundException, etc., captura las versiones de OpenXava en su lugar.
OpenXava ya no usa java.rmi.RemoteException como error de sistema. Se ha sustituido por la excepción org.openxava.util.SystemException, que es una RuntimeException. Esto solo te afecta si tu código hacía referencia explícita a RemoteException; la mayoría de aplicaciones no necesitarán cambios.
Tus propias interfaces o clases que declaraban throws RemoteException imitando el antiguo estilo de OpenXava no están obligadas a cambiar, pero puedes limpiarlas para mantener la coherencia.
Direct Web Remoting (DWR) se ha eliminado por completo de OpenXava. DWR era una librería sin mantenimiento desde 2016, lo que representaba un problema de seguridad importante. Además, DWR no soporta el espacio de nombres de Jakarta, por lo que no podría funcionar en contenedores de servlets modernos como Tomcat 11. Esto significa que DWR no está incluido, pero tampoco se puede añadir a proyectos de OpenXava 8 porque no funcionará.
DWR se utilizaba principalmente de forma interna en OpenXava, por lo que los proyectos estándar no deberían verse afectados. Sin embargo, si has desarrollado tu propio editor personalizado copiando un editor de OpenXava que dependía de DWR, deberás migrarlo. Una opción sencilla y robusta es migrar de DWR a fetch de JavaScript con un Servlet Java simple y llano.
Puedes consultar el siguiente ejemplo de esta migración en OpenXava:
Pedir a un asistente de IA que migre tu lógica de DWR a fetch + servlet es altamente recomendable y suele dar muy buen resultado.
El generador de la interfaz de usuario de OpenXava (la carpeta xava, que incluye core.jsp, detail.jsp, list.jsp, buttonBar.jsp, bottomButtons.jsp, sections.jsp, etc.) ha sido completamente reescrito en Java plano (en el paquete org.openxava.web.render) y todos esos archivos JSP han sido eliminados de OpenXava.
Si tu proyecto (especialmente si viene de OpenXava 6 o anterior, donde los JSPs estaban copiados en el proyecto) contiene copias personalizadas de estos archivos JSP del núcleo en la carpeta src/main/webapp/xava (o web/xava), estas personalizaciones dejarán de tener efecto porque OpenXava ya no invoca dichos JSPs. Puedes eliminar esos archivos JSP obsoletos de tu proyecto.
Ten en cuenta que esto solo afecta a los JSPs del núcleo de xava. Los siguientes elementos siguen funcionando mediante JSP como hasta ahora:
OpenXava 8.0 introduce una interfaz de usuario rediseñada con un sistema de tokens de diseño (espaciado, radios de esquina, elevaciones, escala tipográfica y transiciones definidas como variables CSS en base.css). Como parte de este rediseño los temas disponibles han cambiado:
themes=auto.css, light.css, dark.cssEl color de acento de la aplicación (botones principales, anillos de foco, estados hover) ahora se puede personalizar redefiniendo una única variable en el custom.css de tu proyecto (src/main/webapp/xava/style/custom.css):
:root {
--accent-color: #0d9488; /* El color de tu marca */
--accent-color-hover: #0f766e; /* Una variante más oscura para hover */
--accent-soft: #f0fdfa; /* Un tinte muy claro para fondos hover */
}
Si quieres mantener el aspecto del eliminado tema terra, puedes recrearlo en custom.css redefiniendo las variables del tema:
:root {
--terra: #CDB380;
--light-terra: #E8DDCB;
--dark-terra: #806632;
--acqua: #036564;
--acqua-profonda: #033649;
--accent-color: var(--acqua-profonda);
--accent-color-hover: var(--acqua);
/* Menú de módulos izquierdo */
--modules-list-color: var(--light-terra);
--modules-list-background: var(--acqua-profonda);
--modules-list-selected-color: white;
/* Cabecera de módulo */
--module-header-color: white;
--module-header-background: var(--acqua-profonda);
/* Barra de botones */
--button-bar-background: var(--terra);
/* Fondos y etiquetas */
--background: var(--light-terra);
--color: var(--dark-terra);
/* Acciones */
--action-color: var(--acqua);
--action-hover-color: var(--acqua-profonda);
--action-hover-background: white;
}
Las aplicaciones con temas CSS propios que extienden base.css siguen funcionando; las variables heredadas --my-* aún son reconocidas por light.css. Sin embargo, ten en cuenta que base.css ahora usa la tipografía Inter (en lugar de Roboto), un tamaño base de 14px (en lugar de 13px) y radios de esquina y sombras estandarizados, por lo que tu tema personalizado puede necesitar pequeños ajustes visuales.
El formato de etiqueta por defecto ha cambiado de NORMAL (etiqueta a la izquierda del campo) a SMALL (etiqueta encima del campo). Esto afecta a todos los formularios de tu aplicación. Si prefieres el comportamiento anterior, define la propiedad defaultLabelFormat en xava.properties:
defaultLabelFormat=NORMAL
OpenXava 8.0 actualiza JasperReports de la versión 6 a la versión 7. JasperReports 7 introdujo un cambio incompatible en el formato JRXML: el viejo parser basado en Apache Commons Digester fue reemplazado por un parser basado en Jackson XML, que usa una gramática XML diferente. Esto significa que los ficheros JRXML creados con JasperReports 6 o anterior (incluyendo los generados por iReport o versiones antiguas de Jaspersoft Studio) no son directamente compatibles con JasperReports 7.
OpenXava 8.0 incluye un mecanismo automático de conversión al vuelo: cuando se detecta un fichero JRXML antiguo en tiempo de ejecución, se convierte transparentemente al formato de JasperReports 7 usando una transformación XSLT. Esto significa que en la mayoría de los casos tus informes existentes seguirán funcionando sin que tengas que hacer nada.
Si un informe usa construcciones que no se pueden convertir automáticamente, recibirás un mensaje de error claro indicando qué construcción no está soportada. En ese caso, abre el informe con Jaspersoft Studio 7 y guárdalo para convertirlo manualmente.
Si prefieres convertir todos tus ficheros JRXML a la vez en lugar de depender de la conversión al vuelo, puedes usar la utilidad JRXMLMigrator incluida en OpenXava. Ejútala desde la línea de comandos:
java -cp "target/tuapp/WEB-INF/lib/*" org.openxava.reports.JRXMLMigrator src/main/resources/reports
Donde tuapp en target/tuapp/ es el finalName de tu proyecto (normalmente el artifactId del pom.xml). Ejecútalo desde dentro del directorio de tu proyecto después de mvn package. El WAR desempaquetado en target/tuapp/WEB-INF/lib/ contiene todos los jars de dependencias que necesita el migrador, incluyendo el jar de OpenXava donde reside JRXMLMigrator.
Esto escaneará el directorio indicado en busca de ficheros .jrxml, convertirá los que estén en el formato antiguo y dejará intactos los ya convertidos. Los ficheros que no se puedan convertir se reportarán con el motivo.
Desde JDK 25, el procesamiento de anotaciones ya no está activado por defecto, así que Lombok no funciona a menos que configures el maven-compiler-plugin. Los proyectos creados a partir de OpenXava 7.6 suelen declarar Lombok bajo annotationProcessorPaths con una versión fija. Eso funciona, pero te obliga a mantener esa versión sincronizada cada vez que OpenXava actualice Lombok.
En OpenXava 8.0 el enfoque recomendado es activar el procesamiento completo de anotaciones desde el classpath. Así Lombok llega de forma transitiva desde la dependencia openxava, y siempre usas la misma versión que OpenXava sin declararla en tu pom.xml.
En la sección build/plugins de tu pom.xml, sustituye la configuración del maven-compiler-plugin, y añade un profile activado para JDK 23 o superior:
<!-- ANTES -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.0</version>
<configuration>
<source>${maven.compiler.source}</source>
<target>${maven.compiler.target}</target>
<encoding>${project.build.sourceEncoding}</encoding>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.40</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
<!-- DESPUÉS -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.0</version>
<configuration>
<source>${maven.compiler.source}</source>
<target>${maven.compiler.target}</target>
<encoding>${project.build.sourceEncoding}</encoding>
</configuration>
</plugin>
Y después de la sección build, como hijo directo de project:
<!-- Activa el procesamiento de anotaciones desde el classpath (Lombok vía openxava); necesario desde JDK 25.
-proc:full solo existe desde JDK 23, por eso va en este profile para que compile también con JDK 17. -->
<profiles>
<profile>
<id>jdk23-annotation-processing</id>
<activation>
<jdk>[23,)</jdk>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<proc>full</proc>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
Si tu pom.xml aún no incluye el maven-compiler-plugin, añade el plugin del DESPUÉS junto con el profile. Esto es necesario cuando compilas con JDK 25, aunque tu maven.compiler.source/target sea 17 o 21. Con esta configuración, las futuras actualizaciones de OpenXava que cambien la versión de Lombok ya no requieren editar un número de versión oculto en el pom.xml de tu aplicación.
La opción <proc>full</proc> va en el profile, y no directamente en build, porque el flag -proc:full no existe antes de JDK 23. Si lo pones en build, al compilar con JDK 17 o 21 fallará con error: invalid flag: -proc:full. Con el profile, el mismo pom.xml funciona con JDK 17, 21 y 25.
Para migrar a OpenXava 7.7.3 desde cualquier versión anterior de OpenXava:
Sigue las instrucciones de migración para versiones anteriores