Esta guía explica brevemente cómo configurar y utilizar j8583. Para conocer más acerca del protocolo ISO8583 como tal, favor de leer la página correspondiente.
Estas son las dos clases principales que se utilizan para trabajar con mensajes ISO8583. Un mensaje puede ser codificado como un arreglo de bytes, o un ByteBuffer, para escribirse a un OutputStream, o bien se puede pedir al mensaje que se escriba directamente a un OutputStream. Se pueden leer y modificar los valores de los distintos campos en el mensaje, el cual se ajustará para utilizar un bitmap secundario si es necesario. El IsoMessage se puede configurar para codificarse en ASCII o binario, para utilizar el bitmap secundario incluso cuando no es necesario, y para tener su propio encabezado ISO.
Sin embargo, puede ser muy tedioso crear directamente objetos IsoMessage por código. La clase MessageFactory es una gran ayuda para crear mensajes con valores predefinidos, y además puede fijar la fecha actual y un nuevo número de traza en cada mensaje nuevo.
Hay cinco aspectos principales que se pueden configurar en una MessageFactory: Los encabezados ISO, las plantillas de mensajes, las plantillas de lectura, el generador de números de traza, y los codificadores para campos especiales.
Los encabezados ISO son cadenas que están asociadas con un tipo de mensajes. Cuando se solicita a la fábrica de mensajes que genere un IsoMessage nuevo, ésta le pondré al encabezado ISO correspondiente, si se ha configurado uno para el tipo de mensaje solicitado.
Una plantilla de mensaje es en sí misma un IsoMessage; la fábrica de mensajes puede tener una plantilla para cada tipo de mensaje que necesita crear. Cuando se le pide crear un mensaje de un tipo para el cual tiene una plantilla, le pondrá los valores de la plantilla al nuevo mensaje.
Una plantilla de lectura es un mapa que contiene objetos FieldParseInfo como valores, y los números de campo a los que pertenecen serán las llaves. Un objeto FieldParseInfo contiene el tipo de valor en forma de un IsoType y opcionalmente la longitud del campo; con esta información la fábrica de mensajes puede procesar tramas entrantes, analizando primero el tipo de mensaje y luego utilizando la plantilla de lectura para ese tipo de mensaje. Cuando se lee un mensaje de esta forma, la fábrica de mensajes únicamente procesa los campos que indique el bitmap del mensaje. Por ejemplo si el bitmap tiene encendido el bit 4, la fábrica obtiene el FieldParseInfo para el campo 4 e intenta leer ese campo según el tipo y longitud especificados por el objeto obtenido.
Un mensaje no necesita contener todos los campos especificados en una plantilla de lectura, pero en cambio una plantilla de lectura sí necesita tener todos los campos indicados en el bitmap de un mensaje para poder procesarlo; si un mensaje entrante indica tener un campo para el cual la plantilla no tiene información, no se puede crear el mensaje porque no se sabe cómo leer ese campo y por lo tanto no se pueden leer tampoco los campos que le siguen.
Los mensajes ISO por lo general necesitan tener un número de traza único, en el campo 11. Por lo general también necesitan tener la fecha en que fueron creados (o la fecha en que se origina la transacción), en el campo 7. La MessageFactory puede ponerle automáticamente la fecha actual a todos los mensajes que crea; para ello únicamente hay que activar la propiedad assignDate. También puede asignar un nuevo número de traza a cada mensaje creado, pero para ello necesita la ayuda de un TraceNumberGenerator.
La interfaz TraceNumberGenerator define un método nextTrace(), el cual debe devolver un nuevo número de traza entre 1 y 999999 cada vez que se invoca. El método necesita ser cíclico, es decir que devuelva 1 después de haber devuelto 999999. Y por lo general necesita ser thread-safe (que pueda ser invocado por varios hilos a la vez).
j8583 únicamente define la interfaz; en ambientes de producción es común tener una implementación propia de TraceNumberGenerator que obtenga una nueva traza de una secuencia en una base de datos o algún mecanismo similar de persistencia. Como ejemplo, la biblioteca incluye la clase SimpleTraceGenerator, que simplemente maneja un entero en memoria que va incrementando.
Algunas implementaciones de ISO8583 especifican campos que contienen varios sub-campos. Si solamente se manejan cadenas para estos campos, entonces hay que generar las cadenas apropiadas a partir de los valores necesarios para luego ponerlas en el IsoMessage, y también convertir las cadenas de mensajes entrantes en objetos que contengan los valores separados y convertidos a sus tipos apropiados.
En estos casos, se puede implementar la interfaz CustomField, la cual define dos métodos, uno para codificar un objeto y obtener una cadena, y otro para generar un objeto a partir de una cadena. Se puede pasar un CustomField a la fábrica de mensajes por cada campo en el cual se necesitan manejar valores especiales, para que los mensajes leídos de tramas ya contengan el valor convertido en el campo. Y cuando se fija un valor en un IsoMessage, se le puede pasar el CustomField para que sepa codificar dicho valor al momento de generar su trama. Más información acerca de los codificadores de campos.
La manera más fácil de configurar las plantillas de mensajes y de lectura para una fábrica de mensajes es crear un archivo de configuración XML y pasarlo a la MessageFactory.