diff --git a/XML-Configuration.md b/XML-Configuration.md new file mode 100644 index 0000000..9d9af28 --- /dev/null +++ b/XML-Configuration.md @@ -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: + +``` +
ISO015000050
+
ISO015000050
+``` + + **New in 1.9:** You can define a header as a reference to another header: + +`
` + +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. + +``` + +``` + + **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: + +``` + +``` + + 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). + +``` + + + + + + + + + + + + + + + + + + + + + + + + + +``` + + **New in 1.9:** As with message templates, you can define parsing guides that extend other + parsing guides: + +``` + + + + +``` + +## 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: + +``` + + + + + + + + +``` + + 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(IsoType.ALPHA, "one", 5)) + .addValue(new IsoValue(IsoType.LLVAR, "two")) + .addValue(new IsoValue(IsoType.NUMERIC, 123l, 6)) + .addValue(new IsoValue(IsoType.ALPHA, "OK", 2)); +message.setValue(125, f, f, IsoType.LLLVAR, 0); +``` + + When the message is encoded, field 125 will be "`018one 03two000123OK`".