From 8bcdcbec6f167d4c1a7071190cad0fd3fef764bd Mon Sep 17 00:00:00 2001 From: Enrique Zamudio Date: Mon, 4 Jul 2016 10:14:19 -0500 Subject: [PATCH] Created User's Guide (markdown) --- User's-Guide.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 User's-Guide.md diff --git a/User's-Guide.md b/User's-Guide.md new file mode 100644 index 0000000..8266508 --- /dev/null +++ b/User's-Guide.md @@ -0,0 +1,80 @@ +# Usage Guide + + This guide explains how to setup j8583. If you want to know more about the ISO8583 protocol, + please read the [corresponding page](ISO8583). + +## 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 + 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. + + 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 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 + + 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 + + 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`. + + 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). + +### 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. + The `MessageFactory` can automatically set the current date on all new messages, you just need to set the + `assignDate` property to `true`. And it can also assign a new trace number to each message it creates, + but for this it needs a `TraceNumberGenerator`. + + The `TraceNumberGenerator` interface defines a `nextTrace()` 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. + + 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. + +### 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 + when you get them from an `IsoMessage`. + + 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 `CustomField`s 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. + [Learn more about custom field encoders](Encoders). + +## XML configuration + + The easiest way to configure the message templates and parsing templates is by using a + [XML config file](XML Configuration) and pass it to the `MessageFactory`.