Skip to main content

Java implementation

Status: available

The Java implementation is complete and tested. It reads OSF4 and OSF5, writes OSF5 with both writer models, reads OSFZ transparently, and supports the crc integrity profile. The authoritative decision sources are DECISIONS §21 (architecture) and §24 (integrity profile); the current state lives in STATUS.md.

Developer handbook

This page is the overview. The in-depth developer documentation lives in the Java in detail sub-chapter:

PageContent
ArchitectureLayer model, modules, JPMS encapsulation, data models, conventions
ReadingDataManager, DataChannel, BlockReader, ReaderStats, transparent OSFZ
WritingStreamingWriter, BlockWriter, ChannelDef, metadata defaults, integrity profile
Error handlingOsfException hierarchy, verificationStatus(), best-effort reader
Toolsosf-cli (picocli verbs) and osf-viewer (JavaFX)
Building & integratingMaven, Java 21, JPMS, dependencies, tests
Cookbookcopy-paste recipes from inspection to embedded loop
InternalsEncoder, chunking, integrity helper, parsers — for contributors

Target audiences​

Two main audiences: enterprise backends (Spring, microservices, optiCloud) and big-data / AI pipelines (Spark, Flink, data analysis). Plus embedded Java that records operating data on an industrial gateway — the same "both worlds" situation §7 already describes for C++.

Feature set​

  • Reading: OSF4 (XML metablock) and OSF5 (JSON metablock), a typed DataManager with a channel/segment model; a robust best-effort reader.
  • Writing (OSF5): both writers — a BlockWriter (accumulate in memory, write in one pass) for batch workflows and a StreamingWriter (FileChannel.force(true) per block) for crash-safe embedded recording. Both produce on-disk-identical OSF5 files.
  • Transparent OSFZ: gzip-wrapped files are decompressed automatically on read (java.util.zip, in the JDK).
  • Integrity profile crc: optionally enabled on either writer; the reader verifies the metablock and frame CRCs (see below).

Building and using​

Java 21 and Maven. Shipped as a Maven artifact (groupId=com.optimeas.osf, artifactId=osf-java); the POM is publish-ready (deployment to a public repository is still deferred).

# From the repository root: build and test the Java reactor
mvn -f implementations/java/pom.xml test

JPMS (Java Platform Module System): module-info.java exports only com.optimeas.osf; internal helpers under com.optimeas.osf.internal stay encapsulated — even against reflection.

Dependencies: Jackson (OSF5 JSON), StAX (OSF4 XML, in the JDK), java.util.zip (OSFZ + CRC32C, in the JDK), SLF4J (logging facade). Binary I/O via ByteBuffer over FileChannel with LITTLE_ENDIAN.

Modules​

Beyond the core library, the Java reactor ships two tools:

ModulePurpose
osf-javaCore library — reading, both writers, OSFZ, integrity profile.
osf-cliCommand-line tool (picocli): info, channels, dump, convert; built as a runnable jar.
osf-viewerJavaFX multi-channel viewer (min/max per pixel). Run: mvn -pl osf-viewer javafx:run.

Integrity profile (crc)​

Optional OSF5 integrity profile at level crc (CRC32C, java.util.zip.CRC32C, JDK-native; check value 0xE3069283, byte-identical to Rust/C++/Delphi).

  • Reader: MagicHeaderParser recognizes the crc32c token; DataManager verifies the metablock CRC before parsing, BlockReader verifies and strips the 4-byte frame CRC before the typed parse (fail-closed). Signature blocks (channel 0xFFFE) are skipped and counted, so signed files stay readable. ReaderStats exposes integrity + verificationStatus() (none/crc_valid/invalid/signature_unverifiable).
  • Writer: setIntegrity(IntegrityProfile.CRC32C) on both writers (default off) emits the token, the metablock CRC, and a per-block frame CRC.

The signing level (signed, Ed25519) is not implemented yet. Foundations: DECISIONS §24.

Specification conformance​

The Java implementation follows the same semantic rules as Rust, Python, C++ and Delphi: all current data types (unsigned types via Java type promotion or BigInteger for the full range), explicit rejection of the removed types, bytearray as a read-side alias for binary, channeltype as the data shape (scalar/vector/matrix/binary), the version-deterministic null-termination rule for string/binary, and all four magic-header identifiers. Conformance is checked against the shared reference-manifest contract (examples/reference_manifest.json).

Source code and further information​

This document is licensed under CC BY 4.0. Attribution: optiMEAS GmbH und optiMEAS Switzerland GmbH.