From ce4f150e8b5d3ef51dc46a58ded653a76051d5c1 Mon Sep 17 00:00:00 2001
From: Enrique Zamudio <alterbass@gmail.com>
Date: Wed, 27 Nov 2013 12:18:47 -0600
Subject: [PATCH] update documentation for new XML config features

---
 src/site/apt/xmlconf.apt    | 80 ++++++++++++++++++++++++++++++++++++-
 src/site/es/apt/xmlconf.apt | 77 ++++++++++++++++++++++++++++++++++-
 src/site/site.xml           |  2 +-
 src/site/site_es.xml        |  2 +-
 4 files changed, 155 insertions(+), 6 deletions(-)

diff --git a/src/site/apt/xmlconf.apt b/src/site/apt/xmlconf.apt
index 12ec299..6fd2176 100644
--- a/src/site/apt/xmlconf.apt
+++ b/src/site/apt/xmlconf.apt
@@ -20,6 +20,14 @@ XML Configuration
 <header type="0400">ISO015000050</header>
 +-----
 
+  <<New in 1.9:>> You can define a header as a reference to another header:
+
++-----
+<header type="0800" ref="0200" />
++-----
+
+  The header for 0800 messages will be the same as the header for 0200 messages.
+
 * <<<template>>> element
 
   Each <<<template>>> element defines a message template, with the message type and the fields that the
@@ -42,6 +50,20 @@ XML Configuration
 </template>
 +-----
 
+  <<New in 1.9:>> You can define a template as extending another template, so that it includes
+  all the fields from the referenced template as well as any new fields defined in it, as well
+  as excluding fields from the referenced template:
+
++-----
+<template type="0400" extends="0200">
+    <field num="90" type="ALPHA" length="42">Bla bla</field>
+    <field num="102" type="exclude" />
+</template>
++-----
+
+  In the above example, the template for message type 0400 will include all fields defined in the
+  template for message type 0200 <except> field 102, and will additionally include field 90.
+
 * <<<parse>>> element
 
   Each <<<parse>>> element defines a parsing template for a message type. It must include all the fields that
@@ -71,10 +93,64 @@ XML Configuration
     <field num="60" type="LLLVAR" />
     <field num="61" type="LLLVAR" />
     <field num="70" type="ALPHA" length="3" />
-    <field num="90" type="ALPHA" length="42" />
     <field num="100" type="LLVAR" />
     <field num="102" type="LLVAR" />
     <field num="126" type="LLLVAR" />
 </parse>
 +-----
-  
\ No newline at end of file
+
+  <<New in 1.9:>> As with message templates, you can define parsing guides that extend other
+  parsing guides:
+
++-----
+<parse type="0410" extends="0210">
+    <field num="90" type="ALPHA" length="42" />
+    <field num="102" type="exclude" />
+</parse>
++----
+
+* Composite fields
+
+  Another new feature introduced in 1.9 is the CompositeField. This is a CustomField that acts
+  as a container for several IsoValues, and it can be configured in the parsing guide of
+  a message type:
+
++-----
+<parse type="0410">
+    <field num="125" type="LLLVAR">
+        <field num="1" type="ALPHA" length="5" />
+        <field num="2" type="LLVAR" />
+        <field num="3" type="NUMERIC" length="6" />
+        <field num="4" type="ALPHA" length="2" />
+    </field>
+</parse>
++-----
+
+  In the above example, when a message with type 0410 is parsed, the value for field 125 will
+  be a <<<CompositeField>>> and you can obtain the subfields via <<<getField()>>> or
+  <<<getObjectValue()>>>. The <<<num>>> attribute of the subfields is ignored; it's just
+  there to pass the DTD validation.
+
+  This means that you can do this via code:
+
++-----
+//Assuming original data for field 125 is "018one  03two123456OK"
+CompositeField f = message.getObjectValue(125);
+String sub1 = f.getObjectValue(0); //"one  "
+String sub2 = f.getObjectValue(1); //"two"
+String sub3 = f.getObjectValue(2); //"123456"
+String sub4 = f.getObjectValue(3); //"OK"
++-----
+
+  You can also create a CompositeField, store several subfields inside it, and store it in any
+  field inside an IsoMessage, specifying the same instance as the CustomField:
+
++-----
+CompositeField f = new CompositeField().addValue(new IsoValue<String>(IsoType.ALPHA, "one", 5))
+    .addValue(new IsoValue<String>(IsoType.LLVAR, "two"))
+    .addValue(new IsoValue<Long>(IsoType.NUMERIC, 123l, 6))
+    .addValue(new IsoValue<String>(IsoType.ALPHA, "OK", 2));
+message.setValue(125, f, f, IsoType.LLLVAR, 0);
++-----
+
+  When the message is encoded, field 125 will be "<<<018one  03two000123OK>>>".
diff --git a/src/site/es/apt/xmlconf.apt b/src/site/es/apt/xmlconf.apt
index 578ab83..ef4367d 100644
--- a/src/site/es/apt/xmlconf.apt
+++ b/src/site/es/apt/xmlconf.apt
@@ -19,6 +19,13 @@ Configuración por XML
 +-----
 <header type="0200">ISO015000050</header>
 <header type="0400">ISO015000050</header>
++-----
+
+  <<Nuevo en 1.9:>> Se puede definir un elemento <<<header>>> como referencia a otro elemento para que tengan
+  el mismo valor:
+
++-----
+<header type="0800" ref="0200" />
 +-----
 
 * Elemento <<<template>>>
@@ -43,6 +50,19 @@ Configuración por XML
 </template>
 +-----
 
+  <<Nuevo en 1.9:>> Se puede definir una plantilla que extienda otra plantilla, de modo que incluya todos
+  los campos de la plantilla que extiende, además de poder excluir campos de la plantilla original.
+
++-----
+<template type="0400">
+    <field num="90" type="ALPHA" length="42">bla bla</field>
+    <field num="102" type="exclude" />
+</template>
++-----
+
+  En este ejemplo, la plantilla para mensajes 0400 include todos los campos de los mensajes 0200
+  <excepto> el campo 102, y además incluye el campo 90.
+
 * Elemento <<<parse>>>
 
   Cada elemento <<<parse>>> define una plantilla de lectura para un tipo de mensaje. Debe incluir todos los
@@ -72,10 +92,63 @@ Configuración por XML
     <field num="60" type="LLLVAR" />
     <field num="61" type="LLLVAR" />
     <field num="70" type="ALPHA" length="3" />
-    <field num="90" type="ALPHA" length="42" />
     <field num="100" type="LLVAR" />
     <field num="102" type="LLVAR" />
     <field num="126" type="LLLVAR" />
 </parse>
 +-----
-  
\ No newline at end of file
+
+  <<Nuevo en 1.9:>> Al igual que las plantillas, las guías de lectura también pueden extender otras guías:
+
++-----
+<parse type="0410">
+    <field num="90" type="ALPHA" length="42" />
+    <field num="102" type="exclude" />
+</parse>
++-----
+
+* Campos compuestos
+
+  Otra característica nueva a partir de la versión 1.9 son los campos compuestos, por medio de la clase
+  CompositeField, que es una implementación de CustomField que funciona como un contenedor de varios
+  IsoValues, y puede ser configurado en la guía de lectura de un tipo de mensaje:
+
++-----
+<parse type="0410">
+    <field num="125" type="LLLVAR">
+        <field num="1" type="ALPHA" length="5" />
+        <field num="2" type="LLVAR" />
+        <field num="3" type="NUMERIC" length="6" />
+        <field num="4" type="ALPHA" length="2" />
+    </field>
+</parse>
++-----
+
+  En este ejemplo, cuando un mensaje tipo 0410 se decodifica, el valor del campo 125 será una instancia
+  de <<<CompositeField>>> y se pueden obtener sus subcampos con los métodos <<<getField()>>> y
+  <<<getObjectValue()>>>. El atributo <<<num>>> de los subcampos es ignorado; simplemente se tiene que
+  incluir para pasar la validación del DTD.
+
+  Lo anterior significa que se puede hacer esto con código, una vez que se ha leído el mensaje:
+
++-----
+//Suponiendo que originalmente el campo 125 trae "018one  03two123456OK"
+CompositeField f = message.getObjectValue(125);
+String sub1 = f.getObjectValue(0); //"one  "
+String sub2 = f.getObjectValue(1); //"two"
+String sub3 = f.getObjectValue(2); //"123456"
+String sub4 = f.getObjectValue(3); //"OK"
++-----
+
+  También se puede crear un CompositeField, guardar varios valores en él, y luego ponerlo
+  como valor en cualquier campo de un IsoMessage, usando el mismo objeto como CustomField:
+
++-----
+CompositeField f = new CompositeField().addValue(new IsoValue<String>(IsoType.ALPHA, "one", 5))
+    .addValue(new IsoValue<String>(IsoType.LLVAR, "two"))
+    .addValue(new IsoValue<Long>(IsoType.NUMERIC, 123l, 6))
+    .addValue(new IsoValue<String>(IsoType.ALPHA, "OK", 2));
+message.setValue(125, f, f, IsoType.LLLVAR, 0);
++-----
+
+  Cuando ese mensaje sea codificado, el campo 125 se verá como "<<<018one 03two000123OK>>>".
diff --git a/src/site/site.xml b/src/site/site.xml
index 9928129..08e38c3 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -15,7 +15,7 @@
 		<item name="Download" href="http://sourceforge.net/projects/j8583/files/j8583/"/>
 	</links>
 
-	<menu name="j8583 1.8.0">
+	<menu name="j8583 1.9.0">
 		<item name="Introduction" href="index.html"/>
 		<item name="API docs" href="javadoc/index.html" />
 		<item name="Beginner's Guide" href="guide.html"/>
diff --git a/src/site/site_es.xml b/src/site/site_es.xml
index 25a5dec..23ac235 100644
--- a/src/site/site_es.xml
+++ b/src/site/site_es.xml
@@ -15,7 +15,7 @@
 		<item name="Descargar" href="http://sourceforge.net/projects/j8583/files/j8583/"/>
 	</links>
 
-	<menu name="j8583 1.8.0">
+	<menu name="j8583 1.9.0">
 		<item name="Introducción" href="index.html"/>
 		<item name="Documentación API" href="../javadoc/index.html" />
 		<item name="Guía de inicio" href="guide.html"/>