How to customize encoding for new venue?

1. Obtain the SBE XML template and venue documentation. The SBE communication is always based on the XML SBE template. Such a template must be published by any venue that provides SBE communication.
2. Find and understand message headers. The SBE message always has two headers: framing header and message header.
   1. Find definition of the Framing Header. This header is rarely described in the XML SBE template, but should be defined somewhere in another documentation of the chosen venue.
   2. Find definition of the message header. The message header usually defined in the XML SBE template. PLease pay attention that in particular cases this header can be extended with additional, non-standard fields.
   3. Check group headers. Such headers can appear a few times in the XML SBE template, and, also, can have additional non-standard fields.
3. Map custom composites. Here it is needed to locate non-standard composites and prepare Java classes to bind data to such composites.
4. Compose all the above into the single package and run decoder.

Value Narrowing

The SBE toolkit allows you to convert integers of different types. When the target type is smaller than the source type, or the source and target types are signed and unsigned, the conversion is called narrowing.

The narrowing performed and controlled at runtime and its success depends on the value being narrowed. The source value of an operation must be within the range of valid values of the target type, otherwise an exception is thrown.

Let's look to the few samples:

• int32 -> int16 The source value should be in the range of [-32768..32767] (valid range for the int16 type).

• int16 -> uint32 The source value should be in the range of [0..32767], because negative values can not be converted to the unsigned type.

• uint16 -> int16 The source value should be in the range of [0..32767], because positive values larger than 32767 can not be represented by the 16-bit signed type (valid range is [-32768..32767]).

• unit8 -> int16 No limitations for input value, because all possible source values (the range is [0..255]) can be correctly reflected by the target type.

The narrowing can be implicitly requested during read or write operations:

• Write narrowing appears when used API call operates with numeric type that is wider then SBE type. For instance, when the SBE templates defines a field of int8 type, and the field is written using the IFieldSet.setInt method.
• Read narrowing appears when the SBE field is read using API call which value type is narrower than the SBE type. For instance, when the SBE templates defines a field of int32 type, and the field is read using the IFieldSet.getShort method.

Please note that by default the narrowing is disabled, and all reads and writes should not assume any corresponding transformations. In other words, it is necessary to use accessor that exactly correspond to the SBE template specification. setInt/getInt for int32 fields, setShort/getShort for int16, etc.

The narrowing should be explicitly enabled using DecoderSettings class object. A pair of flags must be configured for each type of operations, read and write: the flag that enables the narrowing itself, and the flag that enables validation during the narrowing.

The first flag mentioned simply allows the operation, but the original value may still be outside the allowed range. This is a quick conversion, but it can lead to unexpected results and is not recommended for use unless absolutely necessary.

The second flag mentioned enables validation during conversion, i.e., comparing the source value with the bounds of the target type. It is recommended to always enable this flag (along with the first one, of course).

Please find the table with references to appropriate settings:

The “Full control” preset contains all narrowing flags enabled. This preset is returned by the DecoderSettings.createFullControlSettings function.