Annotation Mapping

A practical guide to map binary data to Java fields using FastProto annotations.

Overview

FastProto uses annotations placed on fields to describe how bytes map to values. During decode/encode, these annotations drive the binary-to-object conversion.

Quick Mapping Steps

1. Identify each field’s byte offset (and bit offset if needed).
2. Pick the proper data type annotation (e.g., @UInt16Type).
3. Specify endianness only when it deviates from your class/global default.
4. For strings/arrays, specify length.
5. Validate no overlaps and that total length matches the buffer size.

Core Concepts

• Offsets: offset is the start byte index (0‑based). Bit fields use byteOffset + bitOffset.
• Byte/Bit Order: Use @DefaultByteOrder / @DefaultBitOrder at class level; override per field only when necessary. See Byte & Bit Order.
• Lengths: Strings and arrays require an explicit length (fixed-length mapping).

Reference Tables

Primitive & Unsigned Types

Composite Types

Array Types

Supplementary Annotations

Examples

Basic object

import org.indunet.fastproto.annotation.*;
 
public class Weather {
  @UInt8Type(offset = 0) int id;
  @TimeType(offset = 2) java.sql.Timestamp time;
  @UInt16Type(offset = 10) int humidity;
  @Int16Type(offset = 12) int temperature;
  @UInt32Type(offset = 14) long pressure;
}

Nested object

public class Header {
  @UInt8Type(offset = 0) int version;
  @UInt8Type(offset = 1) int flags;
}
 
public class Frame {
  Header header;               // map a nested class
  @UInt16Type(offset = 2) int length;
}

Advanced: Reverse Addressing

• Encode to a fixed-length buffer via FastProto.encode(obj, length) so fields near the end can be addressed safely.

Best Practices

• Keep offsets aligned and avoid overlaps; leave explicit gaps with comments when reserving bytes.
• Prefer class-level defaults for byte/bit order, override only when needed. See Byte & Bit Order.
• For checksums, use a single @Checksum (start/length/offset). See Checksum/CRC.
• For magic bytes and fixed version fields, prefer @Expect. See Expect Assertions.