Alawn/Java-8583-Util
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Created XML Configuration (markdown)

Enrique Zamudio
2016-07-04 10:08:22 -05:00
parent 9beba7e6a9
commit 293ee9fbf3
1 changed files with 149 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
XML-Configuration.md
+149
@@ -0,0 +1,149 @@
# XML Configuration
The `MessageFactory` can read a XML file to setup message templates, ISO headers by type and parsing templates, which are the most cumbersome parts to configure programmatically.
There are three types of main elements that you need to specify in the config file: `header`, `template`, and `parse`. All these must be contained in a single `j8583-config` element. There is a DTD available [here](http://j8583.sourceforge.net/j8583.dtd).
## `header` element
Specify a `header` element for every type of message that needs an ISO header. Only one per message type:
```
<header type="0200">ISO015000050</header>
<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.
**New in 1.12:** You can specify that a header is binary, even if the rest of the message is encoded as text. Just set the `binary` attribute to `true` in the `header` element.
## `template` element
Each `template` element defines a message template, with the message type and the fields that the
template should include. Every new message of that type that the MessageFactory creates will contain those
same values, so this is very useful for defining fixed values, which will be the same in every message.
Only one template per type.
```
<template type="0200">
<field num="3" type="NUMERIC" length="6">650000</field>
<field num="32" type="LLVAR">456</field>
<field num="35" type="LLVAR">4591700012340000=</field>
<field num="43" type="ALPHA" length="40">Fixed-width data</field>
<field num="48" type="LLLVAR">Life, the Universe, and Everything|42</field>
<field num="49" type="ALPHA" length="3">840</field>
<field num="60" type="LLLVAR">B456PRO1+000</field>
<field num="61" type="LLLVAR">This field can have a value up to 999 characters long.</field>
<field num="100" type="LLVAR">999</field>
<field num="102" type="LLVAR">ABCD</field>
</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
an incoming message can contain, each field with its type and length (if needed). Only ALPHA and NUMERIC
types need to have a length specified. The other types either have a fixed length, or have their length
specified as part of the field (LLVAR and LLLVAR).
```
<parse type="0210">
<field num="3" type="NUMERIC" length="6" />
<field num="4" type="AMOUNT" />
<field num="7" type="DATE10" />
<field num="11" type="NUMERIC" length="6" />
<field num="12" type="TIME" />
<field num="13" type="DATE4" />
<field num="15" type="DATE4" />
<field num="17" type="DATE_EXP" />
<field num="32" type="LLVAR" />
<field num="35" type="LLVAR" />
<field num="37" type="NUMERIC" length="12" />
<field num="38" type="NUMERIC" length="6" />
<field num="39" type="NUMERIC" length="2" />
<field num="41" type="ALPHA" length="16" />
<field num="43" type="ALPHA" length="40" />
<field num="48" type="LLLVAR" />
<field num="49" type="ALPHA" length="3" />
<field num="60" type="LLLVAR" />
<field num="61" type="LLLVAR" />
<field num="70" type="ALPHA" length="3" />
<field num="100" type="LLVAR" />
<field num="102" type="LLVAR" />
<field num="126" type="LLLVAR" />
</parse>
```
**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:
```java
//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:
```java
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`".