Usage Guide
This guide explains how to setup j8583. If you want to know more about the ISO8583 protocol, please read the corresponding page.
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 CustomFields 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](Custom Field 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.