Migrar código existente a módulos de Java

No es necesario modularizar para migrar a Java 9+. Una aplicación en classpath se ejecuta sin cambios — todo se convierte en un gran módulo sin nombre. La migración es un paso opcional que se da cuando se quiere encapsulación fuerte, un runtime personalizado con jlink, o un grafo de dependencias más limpio. El arte está en hacerlo de forma incremental, porque los tres tipos de módulos — nombrados, automáticos y sin nombre — permiten que el código modular y el no modular coexistan.

Este capítulo cubre cuándo vale la pena migrar, cómo hacer que una aplicación existente funcione primero en un JDK moderno, las dos direcciones en que se puede modularizar (bottom-up vs. top-down), las herramientas que hacen el trabajo pesado, y un ejemplo ejecutable que inspecciona el grafo de módulos tal como lo hace jdeps. Si los términos aquí resultan desconocidos, comienza con la introducción a los módulos y la declaración de un módulo.

Primero: simplemente ejecutar en Java 9+ (sin módulos)

Antes de agregar cualquier module-info.java, recompila y ejecuta tu aplicación existente en el nuevo JDK con todo en el classpath. Los fallos probables no tienen nada que ver con tus módulos sino con el JDK ahora modular:

Módulos Java EE eliminados — java.xml.bind (JAXB), java.activation, CORBA, etc. fueron eliminados del JDK. Agrégalos de vuelta como dependencias ordinarias.
Internos encapsulados — sun.misc.Unsafe y similares ya no son accesibles. Las opciones --add-exports / --add-opens son una salida de emergencia mientras eliminas el uso.
Paquetes divididos — dos JARs que aportan el mismo paquete ahora entran en conflicto en el module path (pero no en el classpath).

Primero haz que la aplicación funcione en el classpath. Solo entonces comienza a modularizar.

Migración bottom-up

La estrategia preferida cuando controlas toda la base de código:

Comienza con las librerías hoja — módulos que no dependen de nada tuyo.
Añade a cada una un module-info.java y muévela al module path.
Sus dependientes ya pueden hacer requires de ellas. Trabaja hacia arriba en el árbol de dependencias hacia el punto de entrada de la aplicación.

Esto funciona porque un módulo nombrado puede requerir otros módulos nombrados y módulos automáticos — así, siempre que las dependencias propias de una hoja sean al menos automáticas, puedes modularizarla. Cada paso mantiene la compilación en verde. Si una hoja expone comportamiento conectable, este es también un punto natural para introducir un límite de servicios para que sus dependientes hagan uses de una interfaz en lugar de una clase concreta.

Migración top-down

Cuando no controlas las librerías (JARs de terceros sin descriptores), procede en el otro sentido:

Modulariza primero tu propio código de nivel superior.
Coloca los JARs de terceros aún no modulares en el module path, donde se convierten en módulos automáticos.
Haz requires de ellos por su nombre automático (a partir del nombre del archivo JAR o de Automatic-Module-Name).
A medida que cada librería incluya un module-info real, sustituye la dependencia automática por la nombrada — sin cambios en tu requires.

Los módulos automáticos son el andamiaje que hace posible el enfoque top-down; permiten que tu código nombrado dependa de JARs que aún no son modulares.

Herramientas y aspectos a tener en cuenta

jdeps analiza las dependencias reales de un JAR e incluso puede generar un primer borrador de module-info.java (jdeps --generate-module-info). Empieza por ahí en lugar de escribir directivas a mano.
Automatic-Module-Name — si publicas una librería, añade esta entrada al manifiesto antes de escribir un descriptor completo. Fija un nombre de módulo estable para que los usuarios de módulos automáticos que dependen de ella no se vean afectados cuando luego renombres el JAR.
Los paquetes divididos deben fusionarse. El module path prohíbe que dos módulos posean el mismo paquete; el classpath lo toleraba. Este es el bloqueador de migración más común.
opens para la reflexión. Los frameworks que usan reflexión sobre tus clases (Jackson, JPA, Spring) necesitan opens, o bien obtendrás InaccessibleObjectException en tiempo de ejecución aunque la compilación haya pasado.

Advertencia

Los paquetes divididos son el fallo que más sorprende a la gente. En el classpath, dos JARs con clases en com.example.util simplemente se fusionaban; en el module path el resolver los rechaza con un error "module reads package ... from both". No existe ningún flag que lo permita — debes fusionar el paquete duplicado en un único módulo (o renombrar uno). Audita en busca de paquetes divididos con jdeps antes de comenzar a escribir descriptores.

Un ejemplo práctico: inspeccionar un grafo de dependencias como jdeps

La planificación de la migración comienza con "¿qué depende de qué?" Este programa lee los descriptores de módulos de la capa de arranque en tiempo de ejecución — la misma información de requires que reporta jdeps — y también detecta si él mismo se ejecuta como módulo nombrado o en el classpath, exactamente la verificación que indica cuánto ha avanzado la migración.

java— editable, runs on the server

import java.lang.module.ModuleDescriptor;
import java.util.stream.Collectors;

public class ModulesMigrationDemo {
  public static void main(String[] args) {
    // Where am I in the migration? Classpath => unnamed; module path => named.
    Module self = ModulesMigrationDemo.class.getModule();
    System.out.println("running as: "
        + (self.isNamed() ? "NAMED module " + self.getName()
                          : "UNNAMED module (classpath)"));

// jdeps-style: list what a JDK module 'requires'
    inspect("java.sql");
    inspect("java.desktop");

// Find every boot module that (transitively named) requires java.base -
    // i.e. effectively all of them, demonstrating the implicit dependency
    long total = ModuleLayer.boot().modules().size();
    System.out.println("\ntotal modules resolved at startup: " + total);
  }

static void inspect(String moduleName) {
    ModuleLayer.boot().findModule(moduleName).ifPresent(m -> {
      ModuleDescriptor d = m.getDescriptor();
      String deps = d.requires().stream()
          .map(r -> r.name()
              + (r.modifiers().contains(ModuleDescriptor.Requires.Modifier.TRANSITIVE)
                  ? " (transitive)" : ""))
          .collect(Collectors.joining(", "));
      System.out.println("\n" + moduleName + " requires:");
      System.out.println("  " + deps);
    });
  }
}

Qué extraer de la ejecución:

El programa reportó que se estaba ejecutando como módulo UNNAMED — exactamente lo que se espera de código en classpath, y la señal en tiempo de ejecución de que esta base de código no ha sido modularizada aún. Volver a ejecutarlo después de añadir un module-info y moverse al module path cambiaría esto a NAMED, dándote una verificación concreta de "¿ya llegamos?" durante la migración.
inspect("java.sql") imprimió su lista real de requires, incluyendo una dependencia transitiva estilo java.transaction.xa o java.logging. Esta es la misma información que expone jdeps — conocer las dependencias reales de un módulo es el primer paso para escribir su module-info.java, y el descriptor ya las contiene.
Algunos requires imprimieron (transitive). Esas son las dependencias que un módulo re-exporta; cuando haces requires java.sql, automáticamente lees también sus dependencias transitivas. Identificarlas te dice qué líneas requires transitive copiar cuando modularices código que envuelve dicho módulo.
findModule devolvió un Optional, reforzando que un módulo puede simplemente no estar presente en un runtime determinado — una imagen recortada con jlink podría omitir java.desktop por completo. Los planes de migración deben tener en cuenta qué módulos realmente se incluyen en el runtime destino.
Cada módulo depende en última instancia de java.base, y este nunca aparece en una lista de requires porque es implícito. El recuento total de módulos de arranque muestra que el JDK es un grafo que se puede consultar programáticamente — la base sobre la que herramientas como jdeps y jlink construyen para analizar y reducir una aplicación.

Un orden de migración sensato, resumido

Ejecuta en el classpath en el nuevo JDK; corrige los fallos por módulos eliminados y APIs internas.
Usa jdeps para mapear dependencias y encontrar paquetes divididos.
Añade Automatic-Module-Name a las librerías que publiques.
Modulariza bottom-up si eres dueño del árbol, top-down (apoyándote en módulos automáticos) si no lo eres.
Añade opens donde los frameworks usen reflexión; verifica en tiempo de ejecución, no solo en tiempo de compilación.

Esto completa la parte del sistema de módulos de la plataforma Java: ahora conoces qué son los módulos, cómo declarar uno, los tres tipos y cómo coexisten, cómo los servicios desacoplan módulos, y cómo migrar una aplicación existente al module path sin reescribirla.

Práctica

Tu equipo es dueño del árbol de código fuente completo de una aplicación y quiere encapsulación fuerte en toda ella. La librería A no depende de nada tuyo; la librería B depende de A; el ejecutable depende de B. ¿Qué orden de migración mantiene cada compilación intermedia en verde con el menor número de módulos automáticos necesarios?

Bottom-up: modularizar A primero, luego B (que ya puede hacer 'requires A'), luego el ejecutable — cada módulo nombrado solo requiere código ya modularizadoTop-down: modularizar el ejecutable primero y dejar A y B en el classpath como módulos sin nombre que el ejecutable puede requerir con 'requires ALL-UNNAMED'Modularizar los tres simultáneamente en un solo commit, ya que las compilaciones parcialmente modularizadas no pueden compilar en absolutoEl orden no importa porque los módulos nombrados pueden requerir libremente el módulo sin nombre durante la migración