Guía detallada para migrar proyectos Spring Boot a TongWeb 7.0.4.2

Migración de Spring Boot a TongWeb 7.0.4.2 (Spring Boot 2.1.3 + Dameng V8)

Esta guía describe el proceso completo para migrar una aplicación web basada en Spring Boot 2.1.3 al servidor TongWeb 7.0.4.2, integrando la base de datos Dameng V8. Se cubren la transformación del proyecto, resolución de conflictos de dependencias, problemas de despliegue múltiple, configuración de Dameng, manejo de error 404 en frontend y despliegue con prefijo de ruta.

1. Transformación del proyecto Spring Boot: de Tomcat embebido a TongWeb (empaquetado WAR)

TongWeb es un servidor de aplicacioens Java EE (similar a WebLogic o WebSphere) que no soporta la ejecución directa del Tomcat embebido de Spring Boot. Por lo tanto, es necesario convertir el proyecto Spring Boot a un formato WAR.

Paso 1: Excluir Tomcat embebido de Spring Boot

En el archivo pom.xml, excluye la dependencia spring-boot-starter-tomcat para evitar conflictos con el contenedor Servlet de TongWeb:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

No es necesario agregar spring-boot-starter-tomcat ni javax.servlet-api, ya que TongWeb proporciona su propio contenedor Servlet completo.

Paso 2: Cambiar el empaquetado a WAR

En el pom.xml, modifica la etiqueta <packaging> de jar a war:

<packaging>war</packaging>

Paso 3: Modificar la clase principal de Spring Boot para extender SpringBootServletInitializer

Para que la aplicación Spring Boot pueda iniciarse en un contenedor Servlet tradicional (como TongWeb), la clase principal debe extender SpringBootServletInitializer y sobrescribir el método configure:

@SpringBootApplication
public class MainApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(MainApplication.class);
    }

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

Esta configuración permite dos modos de ejecución:
- Ejeuctar directamente el método main (contenedor embebido, para pruebas).
- Empaquetar como WAR y desplegar en TongWeb (producción/preproducción).

2. Problemas comunes al desplegar en TongWeb 7.0.4.2 y sus soluciones

Problema 1: java.lang.NoSuchMethodError: javax.validation.spi.ConfigurationState.getValueExtractors()Ljava/util/Set;

Causa:
TongWeb 7 incluye su propia versión de javax.validation (API de validación de beans), pero la versión puede diferir de la que requiere Spring Boot 2.1.3 (que por defecto usa validation-api 2.0.1.Final). Esto provoca conflictos de versión.

Mensaje de error típico:

Caused by: java.lang.ClassNotFoundException: javax.validation.ParameterNameProvider

Solución recomendada:

Reemplaza el archivo validation-api.jar antiguo en el directorio lib de TongWeb con la versión que usa tu proyecto (por ejemplo, validation-api-2.0.1.Final).

Localiza el archivo validation-api-2.0.1.Final.jar (normalmente en el repositorio local de Maven o en WEB-INF/lib de tu proyecto).
Accede al directorio de instalación de TongWeb y navega a la carpeta lib/.
Elimina el archivo validation-api.jar original (o cualquier JAR antiguo con nombre similar).
Copia el archivo validation-api-2.0.1.Final.jar de tu proyecto en el directorio lib/ de TongWeb.

Esto asegura que TongWeb utilice una versión compatible de Bean Validation API, evitando errores como NoSuchMethodError o ClassNotFoundException.

Problema 2: Conflicto de MBeans JMX al desplegar múltiples aplicaciones

Mensaje de error:

Unable to register MBean [...] nested exception is javax.management.InstanceAlreadyExistsException: ...

Causa:
Spring Boot habilita JMX por defecto (spring.jmx.enabled=true). Cuando varias aplicaciones se despliegan en el mismo contenedor TongWeb, si sus dominios MBean son iguales (por defecto el nombre de la clase o un valor por defecto del contexto de Spring), se produce un conflicto al registrar los MBeans.

Soluciones (elige una):

Opción 1: Deshabilitar JMX globalmente (recomendado para casos simples)

Agrega en application.yml o application.properties:

spring:
  jmx:
    enabled: false

Si tu proyecto no utiliza monitoreo JMX, Spring Cloud u otras dependencias que lo requieran, puedes deshabilitarlo sin problemas.

Opción 2: Asignar un dominio JMX diferente para cada aplicación (recomendado para despliegues múltiples)

Configura un nombre de dominio único en el archivo application.yml de cada aplicación. Por ejemplo:

spring:
  jmx:
    default-domain: app-one

Para otra aplicación:

spring:
  jmx:
    default-domain: app-two

De esta forma, los MBeans de cada aplicación se registran en dominios JMX distintos, evitando conflictos.

3. Guía de configuración de la base de datos Dameng (DM V8)

Problema 1: TongWeb no es compatible con log4jdbc

Ejemplo incorrecto:

datasource:
  url: jdbc:log4jdbc:dm://127.0.0.1:5236/SYSDBA?useUnicode=true&characterEncoding=utf8&allowMultiQueries=true
  username: SYSDBA
  password: SYSDBA
  driver-class-name: net.sf.log4jdbc.DriverSpy

Problema:
En el entorno de TongWeb, usar el prefijo jdbc:log4jdbc:... en la URL de JDBC provoca fallos de conexión. TongWeb no ofrece soporte oficial para log4jdbc, y no se conoce una solución para usarlo en este contexto. Se desaconseja su uso.

Problema 2: ClassNotFoundException al colocar el driver de Dameng en el directorio lib del proyecto e incluirlo en el pom

Enfoque incorrecto:

Colocar el archivo DmJdbcDriver18.jar en la carpeta /lib del proyecto.
Añadir la dependencia en el pom.xml, pero aún así aparece el error: ``` ClassNotFoundException: dm.jdbc.driver.DmDriver

Causa:
TongWeb tiene un mecanismo estricto para la gestión de JARs que no provienen de repositorios Maven estándar. Si el driver no está correctamente instalado en el repositorio local o privado de Maven, TongWeb puede no cargar la clase del driver correctamente.

Solución correcta: Instalar el driver JDBC de Dameng en el repositorio local de Maven y agregar la dependencia adecuada

Paso 1: Usar el comando Maven para instalar el driver en el repositorio local

mvn install:install-file \
  -Dfile=/ruta/local/DmJdbcDriver18.jar \
  -DgroupId=com.dm \
  -DartifactId=DmJdbcDriver18 \
  -Dversion=1.8 \
  -Dpackaging=jar

Reemplaza /ruta/local/DmJdbcDriver18.jar con la ruta real del archivo del driver JDBC de Dameng en tu sistema.

Paso 2: Agregar la dependencia en el pom.xml

<dependency>
  <groupId>com.dm</groupId>
  <artifactId>DmJdbcDriver18</artifactId>
  <version>1.8</version>
</dependency>

Paso 3: Configurar la fuente de datos con una URL JDBC estándar

datasource:
  driver-class-name: dm.jdbc.driver.DmDriver
  url: jdbc:dm://127.0.0.1:5236/SYSDBA?useUnicode=true&characterEncoding=utf8&allowMultiQueries=true
  username: SYSDBA
  password: SYSDBA

Utiliza el prefijo jdbc:dm:// en lugar de log4jdbc para que TongWeb cargue correctamente el driver nativo de Dameng.

4. Problemas relacionados con el despliegue del frontend (junto con el WAR)

Problema 1: Error 404 al recargar páginas del frontend

Causa:
Las aplicaciones frontend basadas en frameworks SPA como React o Vue utilizan enrutamiento del lado del cliente. Al recargar una página, el navegador solicita una ruta real al servidor, pero TongWeb (o el backend) no tiene un Servlet o Controller que maneje esa ruta, resultando en un error 404.

Solución:

Configura TongWeb para redirigir los errores 404 al archivo de entrada del frontend (index.html), permitiendo que el enrutador del frontend tome el control:

Edita el archivo de configuración de TongWeb:

directorio_instalacion_TongWeb/conf/default-web.xml

Añade la siguiente configuración:

<error-page>
    <error-code>404</error-code>
    <location>/index.html</location>
</error-page>

De esta forma, cuando se acceda a una ruta no mapeada en el backend, TongWeb devolverá el archivo index.html del frontend, y el framework SPA se encargará del enrutamiento.

Problema 2: Despliegue del frontend con prefijo (ej. /app) provoca error 404 en recursos/rutas

Causa:
Si el proyecto frontend no se empaqueta con la ruta base correcta (por ejemplo, si se despliega bajo la ruta /app en TongWeb), las rutas de los recursos estáticos y el enrutamiento pueden fallar, causando que los archivos JS/CSS no se carguen o que las rutas den error 404 al recargar.