Skip to content

README.md

Latest commit

 

History

History
87 lines (71 loc) · 3.57 KB

README.md

File metadata and controls

87 lines (71 loc) · 3.57 KB

zstd-java

CI Quality Gate Status Coverage Maven Central zstd Java License

zstd-java is a Java wrapper for Zstandard built on the Foreign Function & Memory (FFM) API — no JNI, no sun.misc.Unsafe. It targets JDK 25+ (for stable java.lang.foreign) and leads with the feature missing from most JVM zstd bindings: dictionary compression, trained straight from your own data.

AI-assisted development: This project uses Claude Code for implementation — C header mapping, test generation, docs. Architecture, API design, and all decisions are human-driven.

Documentation

The docs follow the Diátaxis framework:

Purpose Start here
Tutorial Learning by doing Clean checkout → first round-trip
How-to guides Solving a specific task Hot paths, dictionaries, zero-copy, self-built lib
Reference Looking up facts Platforms, API surface, symbol coverage, build
Explanation Understanding the why Why FFM + Zig, when zero-copy pays, benchmarks

Install

The zstd jar is pure Java and ships no libzstd — you always pair it with a native artifact. Two ways:

1. Everything, any platform — one dependency on zstd-platform, an empty jar that transitively pulls the bindings plus all six natives (~3.8 MB). Zero choices; the build runs on any OS/arch.

<dependency>
  <groupId>io.github.dfa1.zstd</groupId>
  <artifactId>zstd-platform</artifactId>
  <version>0.4</version>
</dependency>

2. Leaner, one platform — import zstd-bom to pin versions, then take zstd plus only the zstd-native-<classifier> you target.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.dfa1.zstd</groupId>
      <artifactId>zstd-bom</artifactId>
      <version>0.4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.github.dfa1.zstd</groupId>
    <artifactId>zstd</artifactId>
  </dependency>
  <dependency>
    <groupId>io.github.dfa1.zstd</groupId>
    <artifactId>zstd-native-osx-aarch64</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

Classifiers: osx-aarch64, osx-x86_64, linux-x86_64, linux-aarch64, windows-x86_64, windows-aarch64. Gradle and more detail in the tutorial. Requires JDK 25+ and --enable-native-access=ALL-UNNAMED at runtime. Building from source is for contributors — see the reference.

License

BSD 3-Clause — the same primary license as zstd, which is bundled under its BSD terms (zstd is dual BSD / GPLv2, © Meta Platforms, Inc.).