Skip to main content
Search Documentation & Spec
Type to search all 11 pages

OmniBuf
for Java 21.

Pure Java 21 library on Maven Central with a companion Buf plugin. Works with annotated records and POJOs, standard Protobuf Java messages, and generated codecs that inspect or splice fields directly inside byte arrays.

Maven Coordinate
com.omnibuf:omnibuf-java:0.1.1

Three ways to use OmniBuf in Java.

All three produce identical wire bytes in standard safe Java 21.

Annotated Java 21 records and POJOs

@OmniBufMessage and @OmniBufField map record components or class fields onto explicit wire numbers and WireKind overrides. OmniBufMapper caches field descriptors per Class<?> on first call.

@OmniBufMessage Java 21 Record
import com.omnibuf.OmniBufMapper;
import com.omnibuf.annotation.OmniBufField;
import com.omnibuf.annotation.OmniBufMessage;
import com.omnibuf.annotation.WireKind;

@OmniBufMessage(name = "SensorReading")
public record SensorReading(
    @OmniBufField(id = 1, name = "sensor_id") String sensorId,
    @OmniBufField(id = 2, name = "delta_mk", wire = WireKind.SINT) int deltaMk,
    @OmniBufField(id = 3, name = "healthy") boolean healthy
) {}

byte[] pkt = OmniBufMapper.marshal(new SensorReading("rack-12", -45, true));
SensorReading out = OmniBufMapper.unmarshal(pkt, SensorReading.class);

Standard protobuf-java messages

Services with existing com.google.protobuf.Message builders and gRPC stubs pass them straight to OmniBufProtobuf.marshal and OmniBufProtobuf.unmarshal. Presence, oneof unions, maps, and Editions descriptors preserve exact semantics.

protobuf-java Bridge
import com.omnibuf.OmniBufProtobuf;
import com.omnibuf.pb.bench.PeerUpdate;

byte[] pkt = OmniBufProtobuf.marshal(protoPeer);
PeerUpdate out = OmniBufProtobuf.unmarshal(pkt, PeerUpdate.getDefaultInstance());

Generated classes with protoc-gen-omnibuf-java

protoc-gen-omnibuf-java emits mutable model classes, static <Msg>OmniBuf codecs, and Opaque<Msg> views over raw byte[] packets. Checking a nested string and splicing a 64-bit sequence field takes 294 ns end-to-end on OpenJDK 21.

buf.gen.yaml
version: v2
clean: true
plugins:
  - protoc_builtin: java
    out: src/main/gen
  - local: ./bin/protoc-gen-omnibuf-java
    out: src/main/gen
Lint & Generate with Buf
$ buf lint
$ buf generate
Generated Codec & Opaque Splice
import com.omnibuf.pb.bench.OmniBufPeerUpdate;
import com.omnibuf.pb.bench.OpaquePeerUpdate;
import com.omnibuf.pb.bench.PeerUpdateOmniBuf;

byte[] pkt = PeerUpdateOmniBuf.marshal(msg);

OpaquePeerUpdate view = new OpaquePeerUpdate(pkt);
String city = view.getLocation().getCity();

byte[] updated = view.setSequence(9_876_543_211L).marshal();

Java 21 benchmarks.

11-field PeerUpdate workload on OpenJDK 21.0.13 (C2 JIT) across com.omnibuf, protobuf-java, FlatBuffers, Jackson JSON, and Jackson MessagePack. Shorter bars = Faster.

Full Message Encode Speed

Serializing PeerUpdate into a fresh byte[] across generated OmniBuf, protobuf-java, FlatBuffers, and Jackson.

OmniBuf (Generated)
1.0x (base) (315 ns)
Protobuf (protobuf-java)
1.2x slower (364 ns)
OmniBuf (@OmniBufField)
2.1x slower (662 ns)
FlatBuffers
3.2x slower (1,021 ns)
OmniBuf (Protobuf)
4.3x slower (1,358 ns)
JSON (Jackson)
4.9x slower (1,559 ns)
MessagePack (Jackson)
7.6x slower (2,401 ns)
Full Message Decode Speed

Decoding byte[] into a fresh PeerUpdate object and reading all 11 fields.

OmniBuf (Generated)
1.0x (base) (1,045 ns)
OmniBuf (@OmniBufField)
1.0x slower (1,056 ns)
FlatBuffers
1.0x slower (1,061 ns)
Protobuf (protobuf-java)
1.5x slower (1,520 ns)
OmniBuf (Protobuf)
2.6x slower (2,704 ns)
JSON (Jackson)
2.8x slower (2,950 ns)
MessagePack (Jackson)
4.2x slower (4,346 ns)
Read a Single Nested Field

Reading a nested city string via FlatBuffers vtables or OpaquePeerUpdate vs full decode.

FlatBuffers
5.3x faster (24 ns)
OmniBuf (Generated)
1.0x (base) (127 ns)
Protobuf (protobuf-java)
8.2x slower (1,036 ns)
JSON (Jackson)
20.5x slower (2,607 ns)
MessagePack (Jackson)
31.4x slower (3,991 ns)
Selective Single-Field Mutation

Checking a nested city string and splicing an updated sequence counter via OpaquePeerUpdate vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (294 ns)
FlatBuffers
4.9x slower (1,453 ns)
Protobuf (protobuf-java)
4.9x slower (1,454 ns)
JSON (Jackson)
14.2x slower (4,166 ns)
MessagePack (Jackson)
21.9x slower (6,453 ns)
Large Embedded Message Encode

Serializing a 39 KiB packet with >16 KiB nested strings. Immutable protobuf-java reuses cached ByteString UTF-8 bytes and memoizedSerializedSize.

Protobuf (protobuf-java)
1.2x faster (4,384 ns)
OmniBuf (Generated)
1.0x (base) (5,044 ns)
OmniBuf (@OmniBufField)
1.0x slower (5,211 ns)
OmniBuf (Protobuf)
1.2x slower (6,004 ns)
JSON (Jackson)
12.5x slower (62,896 ns)
FlatBuffers
15.3x slower (77,382 ns)
MessagePack (Jackson)
23.1x slower (116,427 ns)
Embedded Message Growth

Growing a nested string field past 16 KiB ahead of 32 trailing Neighbor entries via Opaque splicing vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (3,020 ns)
Protobuf (protobuf-java)
8.1x slower (24,464 ns)
FlatBuffers
15.3x slower (46,102 ns)
JSON (Jackson)
16.2x slower (48,786 ns)
MessagePack (Jackson)
29.1x slower (87,759 ns)

Benchmark Environment

Hardware & Runtime
CPU: Apple M1 Pro (darwin/arm64)
Runtime: OpenJDK 21.0.13 (Temurin C2)
Command: just bench

Measured on Eclipse Temurin OpenJDK 21.0.13 after C2 JIT warmup on an Apple M1 Pro Mac. Every decode benchmark reads all 11 fields into a volatile checksum sink. Immutable protobuf-java instances cache UTF-8 ByteString slices and memoizedSerializedSize after the first pass, giving it an advantage on repeated encodes of unchanged 39 KiB messages.

Benchmark source lives in BenchmarkMain.java, with recorded output in testdata/benchmarks.json.

Java 21 questions.

Why does protobuf-java lead on the 39 KiB Large Embedded Message Encode test?

Immutable protobuf-java messages cache memoizedSerializedSize and UTF-8 ByteString slices. Repeated toByteArray() calls allocate the exact 39,227-byte array upfront and copy cached bytes in one pass (4.38 µs). Mutable OmniBuf classes never cache stale sizes, streaming UTF-8 into a pooled encoder and copying out in 5.04 µs. OmniBuf leads every other Java benchmark, up to about 8x faster on single-field reads.

Can OmniBufMapper reuse mutable POJO instances on decode?

Java 21 record types construct fresh instances via canonical constructors through OmniBufMapper.unmarshal(pkt, RecordClass.class). Mutable POJOs also accept OmniBufMapper.unmarshal(pkt, existingInstance) to clear fields and decode into an existing object.

What does OmniBufBlind output on raw packets?

OmniBufBlind.decodeBlind(pkt) returns a Map<String, Object> with synthetic field_1, field_2, ... keys on compact packets, or resolves schema field names when encoded with MarshalOptions.SELF_DESCRIBING.

Example
import com.omnibuf.MarshalOptions;
import com.omnibuf.OmniBufBlind;

byte[] pkt = PeerUpdateOmniBuf.marshal(msg, MarshalOptions.SELF_DESCRIBING);
String json = OmniBufBlind.decodeBlindJson(pkt);

Language implementations.

v0.1 Draft Wire Format · GitHub Feedback →
Architecture, Tooling & Wire Specification