Documentation for a newer release is available. View Latest

Uso de Bulker

¿Qué es un Bulker?

Un bulker es un módulo de aplicación responsable de reunir transacciones o componentes individuales y actúa inicialmente como un área de almacenamiento temporal donde el flujo principal de IPF puede guardar elementos que acabarán en un archivo estructurado. Cuando se le indica, el Bulker enviará cada elemento, en un orden preconfigurado, a un archivo en una ubicación predefinida.

Aplicación de Bulker de ejemplo

Para explicar cómo implementar la funcionalidad de bulker en tu aplicación, utilizaremos una aplicación de ejemplo que está disponible en la carpeta solutions del proyecto ipf-tutorial bajo add-bulker.

Al revisar el pom del proyecto add-bulker, hay dos dependencias principales que añaden la capacidad de bulking:

<!--Responsible for bulking components-->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-aggregate-starter</artifactId>
</dependency>
<!--Responsible for creating output from the bulked components-->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-bulk-producer-starter</artifactId>
</dependency>

ipf-bulker-xml-component-parser: componente que facilita el procesamiento de contenido XML para detectar la posición en bytes donde se pueden inyectar componentes hijos
scheduler-core: proporciona funcionalidad de planificación que se usa para el cierre automático de bulks (si aplica). También se utiliza para retrasar el registro de bulks hijos para asegurar que el bulk padre haya sido creado previamente. Bulker utiliza un scheduler persistente, por lo que las solicitudes planificadas se recuperan en caso de fallo de un nodo. Más detalles del scheduler están disponibles

aquí * scheduler-domain: contiene objetos de dominio que soportan el módulo scheduler-core

Añadir dependencias necesarias para los módulos starter

Además de los dos módulos anteriores, también deben añadirse las siguientes dependencias al pom de tu aplicación para aportar funcionalidad de bulker a una aplicación:

<!-- ipf-component-store implementation which uses mongodb to store components. This store is read from when assembling and streaming output to a file -->
<dependency>
    <groupId>com.iconsolutions.ipf.componentstore</groupId>
    <artifactId>ipf-component-store-mongo</artifactId>
</dependency>
<!-- module provides a http rest interface which allows querying of the component store-->
<dependency>
    <groupId>com.iconsolutions.ipf.componentstore</groupId>
    <artifactId>ipf-component-store-service</artifactId>
</dependency>
<!-- Kafka receive connector implementation of BulkIngestionReceiveConnector, which is responsible for receiving various BulkIngestionMessages (commands) e.g. CreateBulkMessage, AddComponentMessage -->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-ingestion-connector-kafka</artifactId>
</dependency>
<!-- Kafka implementation of ipf-bulker-status-sender-connector which allows you to send status messages upon completion of execution of received commands to a kafka topic -->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-status-sender-connector-kafka</artifactId>
</dependency>
<!-- Local implementation of ipf-bulker-output-stream which streams the bulker output to the local file system -->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-output-stream-local</artifactId>
</dependency>
<!-- Kafka implementation of ipf-bulker-notifications-connector which is used by ProjectionHandlers in ipf-bulker-bulk-producer to send notifications on specific
events occurring e.g. BulkAutoClosed-->
<dependency>
    <groupId>com.iconsolutions.ipf.bulk</groupId>
    <artifactId>ipf-bulker-notifications-connector-kafka</artifactId>
</dependency>
<!-- The bulker module is event sourced and this enables using mongo for journal storage -->
<dependency>
    <groupId>com.iconsolutions.ipf.core.platform</groupId>
    <artifactId>ipf-write-starter-mongo</artifactId>
</dependency>
<!-- Allows for the processing of journal events to create read side projections/send notifications -->
<dependency>
    <groupId>com.iconsolutions.ipf.core.platform</groupId>
    <artifactId>ipf-journal-processor-starter-mongo</artifactId>
</dependency>
<!-- Logs messages exchanges to/from the application to mongo -->
<dependency>
    <groupId>com.iconsolutions.ipf.core.messagelogger</groupId>
    <artifactId>message-logger-mongo</artifactId>
</dependency>

Configurar Bulker en tu aplicación

Para ensamblar los componentes almacenados en un archivo agregado (bulk), tu aplicación debe proporcionar configuración como la estructura del archivo (component-hierarchy), marcadores en el documento que indiquen dónde están los componentes en el flujo y el nombre de la configuración. Esto se puede hacer mediante la propiedad ipf.bulker.configurations. Espera un array de objetos de configuración, cada uno con:

name (string): se utiliza para identificar de forma única la configuración. Las solicitudes para añadir componentes deben especificar un nombre coincidente para que el bulker sepa cómo manejar la solicitud.
file-name-prefix (string): prefijo para los archivos bulk generados
component-hierarchy (object): estructura en árbol que representa la jerarquía de los componentes que se extraerán del archivo bulk. Cada nodo puede tener nodos hijos configurados que se extraerán como componentes separados. El contenido de los componentes hijos se omitirá del componente padre.
before-elements: lista de elementos hermanos que el componente hijo debe preceder en la salida
auto-close-triggers: una lista de cadenas; cada entrada debe coincidir con el resultado del método getName() del AutoCloseTrigger que deba aplicarse a esta configuración
schedule-auto-close: pueden especificarse dos opciones aquí (una o ambas) auto-close-by-age o schedule-at-cron. Debe especificarse al menos una de estas opciones si existe la configuración schedule-auto-close
finalise-on-auto-close: si se establece en true, comenzará el envío a un archivo de salida tan pronto como el bulk se haya cerrado

Ejemplo de configuración para agrupar (bulking) un archivo XML pain.001.001.09.

ipf.bulker {
  configurations = [
    {
      name = "pain.001"
      file-name-prefix = "bulk-"
      file-path = "/tmp/bulk-output"
      component-hierarchy {
        # ... resto de configuración
      }
    }
  ]
}

Parámetros de configuración clave

A continuación se describen algunos parámetros adicionales comunes que pueden formar parte de la configuración del bulker y de los conectores/servicios relacionados. Ajusta los valores según tu entorno, rutas de archivo y políticas de rotación/cierre automático.

Mantén sin traducir nombres de propiedades, claves de JSON/YAML/HOCON, rutas de archivos, IDs de anclaje, nombres de clases/paquetes y comandos de CLI. Solo traduce la prosa, títulos, descripciones, pies de figura y texto alternativo.

Flujo de trabajo típico

Crear/abrir un bulk: el sistema crea un contenedor lógico donde se almacenarán los componentes extraídos.
Añadir componentes: conforme llegan documentos (por ejemplo, XML), los parsers detectan posiciones y extraen componentes según la jerarquía configurada.
Cierre automático/manual del bulk: según triggers de tiempo, tamaño u otras reglas.
Finalización: si está activado finalise-on-auto-close, se inicia el envío al archivo de salida; de lo contrario, puede desencadenarse manualmente.
Emisión de notificaciones y estado: los conectores de estado/envío de notificaciones publican eventos (Kafka u otro) sobre la finalización o los errores.

Consideraciones de despliegue y operación

Almacenamiento: asegúrate de que el directorio file-path exista y tenga permisos adecuados.
Recuperación ante fallos: el scheduler persistente reprogramará tareas tras reinicios.
Observabilidad: usa ipf-journal-processor y message-logger-mongo para rastrear eventos y diagnósticos.
Rendimiento: ajusta tamaños de lote, colas y parámetros de conectores Kafka según el volumen esperado.

Solución de problemas

Marcadores de componentes no detectados: revisa la configuración de component-hierarchy y el parser XML.
Bulks que no se cierran: confirma triggers de auto-close-triggers o la programación en schedule-auto-close.
Archivo de salida vacío o incompleto: verifica el orden configurado y la presencia de before-elements conflictivos.

Próximos pasos

Integra el bulker con tus flujos IPF existentes para generar archivos consolidados.
Añade validaciones y pruebas end-to-end para asegurar que la estructura final cumple los requisitos regulatorios/operativos.