diff --git a/src/site/apt/guide.apt b/src/site/apt/guide.apt index d48a87f..7d96482 100644 --- a/src/site/apt/guide.apt +++ b/src/site/apt/guide.apt @@ -7,7 +7,7 @@ Usage Guide This guide explains how to setup j8583. If you want to know more about the ISO8583 protocol, please read the {{{iso8583.html}corresponding page}}. -The MessageFactory and IsoMessage classes +* The MessageFactory and IsoMessage classes These are the two main classes you need to use to work with ISO8583 messages. An IsoMessage can be encoded into a byte array or a ByteBuffer to be written to an OutputStream, or it can directly write itself @@ -15,26 +15,27 @@ The MessageFactory and IsoMessage classes to use a secondary bitmap if necessary. An IsoMessage has settings to encode itself in binary or ASCII, to use a secondary bitmap even if it's not necessary, and it can have its own ISO header. - However, it can be cumbersome to programmatically create IsoMessages all the time. The MessageFactory is a big aid - in IsoMessages with predefined values; also, it can set the date and the trace number in each new message. + However, it can be cumbersome to programmatically create IsoMessages all the time. The MessageFactory is a + big aid in creating IsoMessages with predefined values; also, it can set the date and the trace number + in each new message. * Configuring the MessageFactory There are five main things you need to configure in a MessageFactory: ISO headers, message templates, parsing templates, TraceNumberGenerator, and custom field encoders. -* ISO headers +** ISO headers ISO headers are strings that are associated with a message type. Whenever you ask the message factory to create an IsoMessage, it will pass the corresponding ISO header (if present) to the new message. -* Message templates +** Message templates A message template is an IsoMessage itself; the MessageFactory can have a template for each message type it needs to create. When it creates a message and it has a template for that message type, it copies the fields from the template to the new message before returning it. -* Parsing templates +** Parsing templates A parsing template is a map containing FieldParseInfo objects as values and the field numbers as the keys. A FieldParseInfo object contains an IsoType and an optional length; with this information and the field number, @@ -48,7 +49,7 @@ The MessageFactory and IsoMessage classes contain all the fields specified in the bitmap of a message, or the MessageFactory won't be able to parse it because it has no way of knowing how it should parse that field (and also all subsequent fields). -* The TraceNumberGenerator +** The TraceNumberGenerator When creating new messages, they usually need to have a unique trace number, contained in field 11. Also, they usually need to have the date they were created (or the date the transaction was originated) in field 7. @@ -64,7 +65,7 @@ The MessageFactory and IsoMessage classes TraceNumberGenerator, getting the new trace number from a sequence in a database or some similar mechanism. As an example, the library includes the SimpleTraceGenerator, which simply increments an in-memory value. -* Custom field encoders +** Custom field encoders Certain implementations of ISO8583 specify fields which contain many subfields. If you only handle strings in those fields, you'll have to encode all those values before storing them in an IsoMessage, and decode them diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 66526cf..1c5ba85 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -22,7 +22,7 @@ ISO header (optional)|Message Type|primary bitmap|secondary bitmap (optional)|da The ISO header is a string containing some code that can vary according to the message type. - The message type is a 4-digit number (or 2 bytes when using binary format). + The message type is a number expressed as 4 hex digits (or 2 bytes when using binary format). The bitmap is 64 bits long and it is encoded as 16 hex characters or as 8 bytes when using binary format. Every bit that is set in the bitmap indicates that the corresponding field is present. If the first bit is set, @@ -37,7 +37,7 @@ ISO header (optional)|Message Type|primary bitmap|secondary bitmap (optional)|da * How does j8583 work? j8583 offers a MessageFactory, which once properly configured, can create different message types with - some values predefined, and can also parse a byte array to create a iso message. Messages are represented + some values predefined, and can also parse a byte array to create an ISO message. Messages are represented by IsoMessage objects, which store IsoValue instances for their data fields. You can work with the IsoValues or use the convenience methods of IsoMessage to work directly with the stored values. diff --git a/src/site/es/apt/guide.apt b/src/site/es/apt/guide.apt index d48a87f..1bc1f65 100644 --- a/src/site/es/apt/guide.apt +++ b/src/site/es/apt/guide.apt @@ -4,79 +4,90 @@ Usage Guide - This guide explains how to setup j8583. If you want to know more about the ISO8583 protocol, - please read the {{{iso8583.html}corresponding page}}. + 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 {{{iso8583.html}página correspondiente}}. -The MessageFactory and IsoMessage classes +* Las clases MessageFactory e IsoMessage - These are the two main classes you need to use to work with ISO8583 messages. An IsoMessage can be - encoded into a byte array or a ByteBuffer to be written to an OutputStream, or it can directly write itself - to an OutputStream. You can set and get the values for each field in an IsoMessage, and it will adjust itself - to use a secondary bitmap if necessary. An IsoMessage has settings to encode itself in binary or ASCII, - to use a secondary bitmap even if it's not necessary, and it can have its own ISO header. + 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. - However, it can be cumbersome to programmatically create IsoMessages all the time. The MessageFactory is a big aid - in IsoMessages with predefined values; also, it can set the date and the trace number in each new message. + 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. -* Configuring the MessageFactory +* Configuración de la MessageFactory - There are five main things you need to configure in a MessageFactory: ISO headers, message templates, - parsing templates, TraceNumberGenerator, and custom field encoders. + 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. -* ISO headers +** Encabezados ISO - ISO headers are strings that are associated with a message type. Whenever you ask the message factory - to create an IsoMessage, it will pass the corresponding ISO header (if present) to the new message. + 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. -* Message templates +** Plantillas de mensajes - A message template is an IsoMessage itself; the MessageFactory can have a template for each message type - it needs to create. When it creates a message and it has a template for that message type, it copies the - fields from the template to the new message before returning it. + 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. -* Parsing templates +** Plantillas de lectura - A parsing template is a map containing FieldParseInfo objects as values and the field numbers as the keys. - A FieldParseInfo object contains an IsoType and an optional length; with this information and the field number, - the MessageFactory can parse incoming messages, first analyzing the message type and then using the parsing - template for that type; when parsing a message, the MessageFactory only parses the fields that are specified - in the message's bitmap. For example if the bitmap specifies field 4, the factory will get the FieldParseInfo - stored in the map under key 4, and will attempt to parse the field according to the type and length specified - by the FieldParseInfo. + 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. - A message does not need to contain all the fields specified in a parsing template, but a parsing template must - contain all the fields specified in the bitmap of a message, or the MessageFactory won't be able to parse it - because it has no way of knowing how it should parse that field (and also all subsequent fields). + 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. -* The TraceNumberGenerator +** El generador de números de traza - When creating new messages, they usually need to have a unique trace number, contained in field 11. Also, they - usually need to have the date they were created (or the date the transaction was originated) in field 7. - The MessageFactory can automatically set the current date on all new messages, you just need to set the - <<>> property to <<>>. And it can also assign a new trace number to each message it creates, - but for this it needs a TraceNumberGenerator. + 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 <<>>. También puede asignar un nuevo número de traza + a cada mensaje creado, pero para ello necesita la ayuda de un TraceNumberGenerator. - The TraceNumberGenerator interface defines a <<>> method, which must return a new trace number - between 1 and 999999. It needs to be cyclic, so it returns 1 again after returning 999999. And usually, it - needs to be thread-safe. + La interfaz <<>> define un método <<>>, 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 <> (que pueda ser invocado por + varios hilos a la vez). - j8583 only defines the interface; in production environments you will usually need to implement your own - TraceNumberGenerator, getting the new trace number from a sequence in a database or some similar mechanism. - As an example, the library includes the SimpleTraceGenerator, which simply increments an in-memory value. + 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. -* Custom field encoders +** Codificadores de campos especiales - Certain implementations of ISO8583 specify fields which contain many subfields. If you only handle strings - in those fields, you'll have to encode all those values before storing them in an IsoMessage, and decode them - when you get them from an IsoMessage. + 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. - In these cases you can implement a CustomField, which is an interface that defines two methods, one for encoding - an object into a String and another for decoding an object from a String. You can pass the MessageFactory a - CustomField for every field where you want to store custom values, so that parsed messages will return the - objects decoded by the CustomFields instead of just strings; and when you set a value in an IsoMessage, you - can specify the CustomField to be used to encode the value as a String. + 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. -* XML configuration +* Configuración por XML - The easiest way to configure the message templates and parsing templates is by using a - {{{xmlconf.html}XML config file}} and pass it to the MessageFactory. + La manera más fácil de configurar las plantillas de mensajes y de lectura para una fábrica de mensajes es + crear un {{{xmlconf.html}archivo de configuración XML}} y pasarlo a la MessageFactory. diff --git a/src/site/es/apt/index.apt b/src/site/es/apt/index.apt index 66526cf..5058fdd 100644 --- a/src/site/es/apt/index.apt +++ b/src/site/es/apt/index.apt @@ -1,46 +1,49 @@ ----- - Introduction to j8583 + Introducción a j8583 ----- -What it j8583? +¿Qué es j8583? - Simply put, j8583 is a Java library to generate and read ISO8583 messages. It does not handle sending or - reading them over a network connection, but it does parse the data you have read and can generate the - data you need to write, or write it directly to an OutputStream. + Puesto de manera muy simple, j8583 es una biblioteca de clases de Java para generar y leer mensajes de ISO8583. + No maneja el envío y recepción de dichos mensajes a través de una conexión de red, pero sí procesa las tramas + que se lean de un socket y puede generar las tramas que hay que enviar, o escribirlas directamente a un + OutputStream. -* What is ISO8583? +* ¿Qué es ISO8583? - ISO8583 is a message format used for credit card transactions, banking and other commercial interaction between - different systems. It has an ASCII variant and a binary one, and it is somewhat convoluted and difficult to - implement. + ISO8583 es un formato de mensajería utilizado principalmente para transacciones de tarjetas de crédito, + para comunicación con bancos y otras entidades comerciales o financieras. Hay una variante ASCII y una binaria, + y la especificación es bastante enredada y algo difícil de implementar. - The main format of the ISO8583 is something like this: + El formato principal de un mensaje ISO8583 es más o menos así: +----- -ISO header (optional)|Message Type|primary bitmap|secondary bitmap (optional)|data fields +Encabezado ISO (opcional)|Tipo de mensaje|bitmap primario|bitmap secundario (opcional)|campos de datos +----- - The ISO header is a string containing some code that can vary according to the message type. + El encabezado ISO es una cadena que contiene ciertos códigos que varían según el tipo de mensaje. - The message type is a 4-digit number (or 2 bytes when using binary format). + El tipo de mensaje es un número de 4 dígitos hexadecimales (o 2 bytes cuando se usa formato binario). - The bitmap is 64 bits long and it is encoded as 16 hex characters or as 8 bytes when using binary format. - Every bit that is set in the bitmap indicates that the corresponding field is present. If the first bit is set, - then field 1 is present, and so on. + El bitmap contiene 64 bits y se codifica como 16 caracteres hexadecimales, como 8 bytes en formato binario. + Cada bit encendido en el bitmap indica que el campo correspondiente está presente en el mensaje. Si el primer + bit está encendido, entonces el mensaje contiene el campo 1, etc. - The fields in the message are numbered from 1 to 64. Field 1 is the secondary bitmap, if present. The secondary - bitmap allows for the message to have fields from 65 to 128. + Los campos en el mensaje están numerados del 1 al 64. El campo 1 es el bitmap secundario y permite que el mensaje + contenga campos del 64 al 128. - You can {{{iso8583.html}check the ISO8583 guide}} for more information; Wikipedia has - {{{http://en.wikipedia.org/wiki/ISO_8583}a very good article}} on the whole specification. + Puedes {{{iso8583.html}leer la guía de ISO8583}} para mayor información; Wikipedia tiene un + {{{http://es.wikipedia.org/wiki/ISO_8583}excelente artículo}} que abarca la especificación de manera más + completa. -* How does j8583 work? +* ¿Cómo funciona j8583? - j8583 offers a MessageFactory, which once properly configured, can create different message types with - some values predefined, and can also parse a byte array to create a iso message. Messages are represented - by IsoMessage objects, which store IsoValue instances for their data fields. You can work with the IsoValues - or use the convenience methods of IsoMessage to work directly with the stored values. + j8583 ofrece una clase MessageFactory, que una vez configurada, puede crear mensajes de distintos tipos + con algunos valores predefinidos, y también puede leer un arreglo de bytes y convertirlo en un mensaje ISO. + Los mensajes son representados por objetos de la clase IsoMessage, los cuales almacenan instancias de la + clase IsoValue como valores en sus campos. Se puede trabajar directamente son los IsoValues o se pueden + usar algunos métodos de conveniencia del IsoMessage para trabajar directamente con los datos almacenados. - j8583 can directly handle the basic data types: numeric values, strings, and dates. If you want to encode - a custom object in a field, you can implement a custom field encoder. More information is available in the - {{{guide.html}user's guide}}. + j8583 puede manejar de forma directa los tipos de datos básicos: valores numéricos, cadenas, y fechas. + Si deseas guardar objetos de otra clase en un campo, puedes implementar tu propio codificador/decodificador + de datos para ese campo. En la {{{guide.html}guía del usuario}} hay más información al respecto.