Created User's Guide (markdown)

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`.