Compatibilidad y alcance de protección

P4JX cifra las implementaciones de los métodos de las clases protegidas y solo permite que el VLX JRE incluido en el paquete las lea en tiempo de ejecución. Para equilibrar la efectividad de la protección con la compatibilidad del framework, se recomienda proteger únicamente las implementaciones de los servicios clave; la entrada del framework, los DTO/entidades, las clases que deben generarse o modificarse dinámicamente por el framework, así como las dependencias de terceros, no deben incluirse en la protección.

1. Ejecutar primero un análisis de compatibilidad

Solo escanear, sin generar salida:

p4j javaapp app.jar --compat-scan
p4j springboot app.jar --compat-scan
p4j tomcat app.war --compat-scan

Escanear e aplicar recomendaciones conservadoras:

p4j springboot app.jar dist --compat-apply

Las opciones explícitas del usuario tienen prioridad sobre las recomendaciones automáticas. El escaneo es un análisis heurístico estático; un informe de “Es necesario realizar una revisión.” no implica necesariamente un fallo en la aplicación; además, la ausencia de problemas en el informe no sustituye a las pruebas de regresión en la plataforma objetivo.

Cuando los resultados del escaneo requieren modificar el código

Si el informe de la GUI muestra Se requiere realizar una operación. (en la interfaz en inglés, ACTION REQUIRED), esto indica: El usuario debe modificar el código fuente de la aplicación.; este tipo de problemas no se pueden resolver ajustando los parámetros de empaquetado. El informe enumerará las clases y métodos específicos que deben modificarse y ofrecerá sugerencias de tratamiento para cada uno de ellos:

  • Leer ZIP/JAR desde la memoria: Cambie ByteArrayInputStream por métodos de lectura basados en archivos como Files.newInputStream(Path), FileInputStream, ZipFile o JarFile.
  • Definir la clase a partir de los bytes originales: No llame directamente a ClassLoader#defineClass sobre las clases protegidas; en su lugar, utilice Class.forName() o ClassLoader.loadClass() para que P4JX realice la carga de las clases en tiempo de ejecución.

Después de modificar el código fuente, reconstruya JAR/WAR y ejecute nuevamente el análisis de compatibilidad; una vez que el informe ya no muestre ese problema, genere el paquete de protección.

2. Modelo de protección recomendado

Entrada de borde/frame público → facade estándar o interfaz → Implementación central protegida

Ejemplo:

--protect 'com.example.service.impl.**' \
--exclude 'com.example.dto.**,com.example.config.**'

3. Clases que generalmente no deben protegerse

  • Controller, Servlet, Filter, Listener, Advice;
  • Configuración de Spring, objetos mejorados con AOT/CGLIB;
  • DTO de Jackson, record, Entity de JPA, modelos de serialización;
  • Clases de puente JNI/SWT/native;
  • Clases reescritas o redefinidas por Agent, ORM, Mock, sobrecarga en tiempo de ejecución o ClassLoader personalizado;
  • Frameworks de terceros y dependencias de código abierto;
  • Clases que necesitan leer su propio bytecode de clase real.

4. Funcionalidades de JVM no soportadas o restringidas

Entorno de ejecución

  • Las aplicaciones protegidas deben utilizar el VLX JRE incluido en el paquete;
  • No se admite el inicio mediante el método JPMS -m ni el inicio con código fuente en un solo archivo;
  • Los JAR comunes en elclasspath deben ser registrados por el empaquetador y no se pueden agregar arbitrariamente durante el despliegue;
  • No se debe utilizar VLX JRE para ejecutar aplicaciones comunes sin protección.

Depuración y Agentes

  • No se admiten los depuradores JVMTI y JDWP, los analizadores de rendimiento, los medidores de cobertura ni la mayoría de los agentes APM;
  • No se admiten -javaagent, -agentlib, la recarga en caliente ni la redefinición de clases;
  • El procesamiento que requiere inserción de bytecode debe completarse antes de la codificación.

Optimización al iniciar

  • No se admiten CDS, AppCDS ni AOT;
  • ZGC y ShenandoahGC no están dentro del alcance de soporte del runtime P4JX.

5. Recursos de clases y escáneres

Al leer los recursos .class de clases protegidas, lo que se obtiene son marcadores de metadatos: se conservan el nombre de la clase, la firma y los anotaciones, pero no el cuerpo real de los métodos.

  • El reflexión normal puede leer metadatos, pero no es posible recuperar el bytecode original.
  • Las herramientas que analizan ZIPs físicos por sí solas no pueden ver el contenido de P4JX por defecto; se puede probar con --zip-overlay scanner.
  • Escáneres de classpath como ClassGraph y Reflections pueden requerir --layout fat en Spring Boot.
  • ZipInputStream/JarInputStream no admiten el análisis de P4JX a partir de la memoria o flujos de red.
  • La vista de zipfs es solo de lectura; no se pueden modificar los archivos comprimidos.

6. Comportamiento de archivado

  • El sufijo .jar no indica que se trate de un JAR normal; su contenido sigue siendo P4JX;
  • Los archivos JAR de múltiples versiones se despliegan según la versión de Java objetivo al momento de la codificación;
  • La firma original del JAR y la semántica del certificado no se conservan; cuando sea necesario, se debe realizar una firma externa del producto final para su distribución;
  • No modifique, comprima nuevamente ni combine los archivos P4JX generados.