8. 2Pack — empaquetar cambios del Diccionario

Si el Diccionario de Aplicación vive en la base de datos, ¿cómo se lleva un cambio de diccionario hecho en un servidor de desarrollo hasta el servidor de un cliente, sin ejecutar SQL a mano ni copiar la base entera? La respuesta de iDempiere es 2Pack: un paquete XML exportable e importable de objetos del Diccionario, y FINORA LVE lo entrega incrustado dentro del propio jar del plugin, aplicado automáticamente al arrancar.

Pack Out / Pack In

• Pack Out es el proceso de iDempiere que exporta un conjunto de objetos del Diccionario (una tabla, una ventana, un proceso, y todo lo que dependa de ellos) a un archivo XML, PackOut.xml.
• Pack In es el proceso inverso: lee ese XML y crea o actualiza los objetos correspondientes en el servidor destino — incluyendo, si hace falta, la tabla física y sus columnas.

FINORA versiona ese XML descomprimido, para poder revisarlo en un diff de git antes de aplicarlo en ningún lado:

packout/com.finora.lve.base/1.1.0/dict/PackOut.xml

tools/build.sh lo comprime dentro del jar del bundle como META-INF/2Pack_1.1.0.zip (finora-lve/packout/README.md).

Incremental2PackActivator: aplicar solo lo que falta, en orden

El core aporta la clase que hace el trabajo pesado, Incremental2PackActivator (org.adempiere.plugin.utils). Cuando el bundle arranca:

1. Busca dentro de sí mismo todos los archivos META-INF/2Pack_*.zip.
2. Compara cada versión contra la tabla AD_Package_Imp (que registra, por bundle, qué versiones ya se aplicaron con éxito).
3. Aplica solo las que faltan, en orden ascendente — así un servidor que ya tiene la 1.3.0 no vuelve a aplicar la 1.0.0 al reiniciar, y uno nuevo aplica todas desde la 1.0.0.
4. Si una versión falla, detiene las siguientes de ese bundle; el próximo arranque las reintenta.

flowchart LR
    A["Arranca el bundle"] --> B{"¿Hay 2Pack_x.y.z.zip\nsin aplicar?"}
    B -- no --> Z["Bundle ACTIVE, nada que hacer"]
    B -- sí --> C["Aplica la versión más baja pendiente"]
    C --> D{"¿Se aplicó\ncon éxito?"}
    D -- sí --> E["Registra 'Completed successfully'\nen AD_Package_Imp"] --> B
    D -- no --> F["Detiene el pack-in de este bundle;\nreintenta en el próximo arranque"]

FINORA LVE hereda este mecanismo tal cual: cada bundle extiende com.finora.lve.base.LvePackActivator, que a su vez extiende Incremental2PackActivator (ver el Activator.java real en el Tutorial 6). El precedente de referencia es el propio plugin REST de iDempiere, que trae veinte versiones de 2Pack con este mismo activador (finora-lve/docs/ARCHITECTURE.md, §3.3).

El orden entre bundles no está garantizado

Require-Bundle ordena la resolución de dependencias, no el pack-in: cada Incremental2PackActivator corre en su propio hilo al arrancar, y nada garantiza que base termine de aplicar su 2Pack antes que fiscal. FINORA LVE lo descubrió en una instalación limpia: fiscal intentó aplicar una vista que dependía de una columna de base que todavía no existía (finora-lve/decisions/ADR.md, ADR-LVE-014). La solución fue un helper, LvePackActivator, que espera (con reintento, hasta 10 minutos) a que cada bundle en requiredBundles() tenga su versión más alta de 2Pack completada antes de aplicar la propia.

Por qué los UUID, y no los ID numéricos

Un mismo AD_Table_ID puede ser un número distinto en el servidor de desarrollo, en el de DC GEEKS y en el de un cliente — cada base de datos asigna sus propios IDs desde AD_Sequence. Por eso Pack In resuelve cada objeto por su UUID (*_UU), nunca por el ID numérico, y el propio código de FINORA LVE tiene prohibido usar un AD_*_ID literal: siempre busca por UUID, por Value (el código de negocio) o por nombre de tabla/columna (finora-lve/packout/README.md, regla 3).

Un detalle sutil: el orden de activación entre bundles

Como el orden de activación entre bundles no está garantizado, el primer 2Pack de cada bundle crea también el EntityType FVE compartido, con el mismo UUID en los cinco bundles — si ya existe, Pack In simplemente lo actualiza sin efecto (finora-lve/docs/ARCHITECTURE.md, §3.1).

La regla de los tres pasos de FINORA (nunca editar un 2Pack publicado)

Un 2Pack que ya llegó a un servidor de desarrollo o producción se considera quemado, aunque su aplicación haya fallado y se haya revertido — la corrección siempre es una versión nueva, nunca el mismo número con otro contenido. finora-lve/packout/README.md, regla 1, define un orden obligatorio en tres pasos, con un commit de git por paso:

1. Commit del XML (git commit -- packout/<bundle>/<x.y.z>/dict/PackOut.xml). Nunca se despliega en desarrollo un 2Pack que no esté commiteado primero.
2. Despliegue en desarrollo y confirmación de Completed successfully para esa versión en AD_Package_Imp.
3. Solo entonces, en un commit aparte, se fija el hash sha256 de ese archivo en packout/<bundle>/PUBLISHED.sha256 — el candado que certifica “esta versión ya corrió en desarrollo con este contenido exacto”. Fijar el candado antes de aplicar sería mentir sobre lo que se probó.

Fuentes

• finora-lve/packout/README.md (reglas 1 a 9: inmutabilidad, autoría, UUID, niveles System/tenant, trampas de PostgreSQL)
• finora-lve/docs/ARCHITECTURE.md, §3.1, §3.3 y §3.4 (EntityType FVE, formato del zip, UUID)
• finora-lve/decisions/ADR.md, ADR-LVE-003 y ADR-LVE-014 (2Pack incremental, orden de pack-in entre bundles)
• Evidencia de código citada en FINORA: org.adempiere.plugin.utils.Incremental2PackActivator (iDempiere release-13)