0
# Zstd-jni
1

2
Zstd-jni provides JNI (Java Native Interface) bindings for the Zstd (Zstandard) compression library, enabling Java and JVM language applications to use fast, lossless compression with high compression ratios. The library offers static compress/decompress methods for direct data compression, implements InputStream and OutputStream interfaces for transparent stream compression fully compatible with the standard zstd program, and maintains minimal performance overhead through efficient native bindings.
3

4
## Package Information
5

6
- **Package Name**: zstd-jni  
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.github.luben</groupId>
13
      <artifactId>zstd-jni</artifactId>
14
      <version>1.2.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.github.luben.zstd.Zstd;
22
import com.github.luben.zstd.ZstdInputStream;
23
import com.github.luben.zstd.ZstdOutputStream;
24
import com.github.luben.zstd.ZstdDictCompress;
25
import com.github.luben.zstd.ZstdDictDecompress;
26
```
27

28
## Basic Usage
29

30
```java
31
import com.github.luben.zstd.Zstd;
32

33
// Simple compression with default level
34
byte[] originalData = "Hello, World!".getBytes();
35
byte[] compressed = Zstd.compress(originalData);
36

37
// Decompress back to original
38
byte[] decompressed = Zstd.decompress(compressed, originalData.length);
39
String result = new String(decompressed); // "Hello, World!"
40

41
// Compression with specific level (1-22, higher = better compression)
42
byte[] compressedLevel10 = Zstd.compress(originalData, 10);
43
```
44

45
## Architecture
46

47
Zstd-jni is built around several key components:
48

49
- **Static API (Zstd class)**: Direct compression/decompression methods for byte arrays and ByteBuffers
50
- **Stream API**: Standard Java I/O streams (ZstdInputStream, ZstdOutputStream) for transparent compression
51
- **Direct Buffer Streams**: High-performance streaming for direct ByteBuffers with minimal copying
52
- **Dictionary Support**: Pre-compiled dictionaries (ZstdDictCompress, ZstdDictDecompress) for improved compression ratios on similar data
53
- **Native Library Management**: Automatic loading of platform-specific native libraries embedded in the JAR
54

55
## Capabilities
56

57
### Static Compression/Decompression
58

59
Core compression and decompression functionality using static methods. Ideal for one-shot operations on complete data sets with byte arrays and ByteBuffers.
60

61
```java { .api }
62
// Basic compression
63
public static byte[] compress(byte[] src);
64
public static byte[] compress(byte[] src, int level);
65
public static long compress(byte[] dst, byte[] src, int level);
66

67
// Basic decompression  
68
public static byte[] decompress(byte[] src, int originalSize);
69
public static long decompress(byte[] dst, byte[] src);
70

71
// ByteBuffer compression
72
public static int compress(ByteBuffer dstBuf, ByteBuffer srcBuf, int level);
73
public static ByteBuffer compress(ByteBuffer srcBuf, int level);
74

75
// ByteBuffer decompression
76
public static int decompress(ByteBuffer dstBuf, ByteBuffer srcBuf);
77
public static ByteBuffer decompress(ByteBuffer srcBuf, int originalSize);
78
```
79

80
[Static Compression and Decompression](./static-compression.md)
81

82
### Dictionary-Based Compression
83

84
Dictionary-based compression for improved compression ratios when compressing similar data. Supports both byte array dictionaries and pre-compiled dictionary objects.
85

86
```java { .api }
87
// Dictionary compression with byte arrays
88
public static byte[] compressUsingDict(byte[] src, byte[] dict, int level);
89
public static long compress(byte[] dst, byte[] src, byte[] dict, int level);
90

91
// Dictionary compression with dictionary objects
92
public static byte[] compress(byte[] src, ZstdDictCompress dict);
93
public static int compress(ByteBuffer dstBuf, ByteBuffer srcBuf, ZstdDictCompress dict);
94

95
// Dictionary decompression
96
public static byte[] decompress(byte[] src, byte[] dict, int originalSize);
97
public static byte[] decompress(byte[] src, ZstdDictDecompress dict, int originalSize);
98
```
99

100
[Dictionary-Based Compression](./dictionary-compression.md)
101

102
### Stream Compression
103

104
Standard Java I/O streams for transparent compression and decompression. Compatible with existing Java I/O patterns and fully interoperable with the standard zstd command-line tool.
105

106
```java { .api }
107
// Input stream for decompression
108
public ZstdInputStream(InputStream inStream) throws IOException;
109
public ZstdInputStream setContinuous(boolean b);
110

111
// Output stream for compression
112
public ZstdOutputStream(OutputStream outStream) throws IOException;
113
public ZstdOutputStream(OutputStream outStream, int level) throws IOException;
114
public ZstdOutputStream(OutputStream outStream, int level, boolean closeFrameOnFlush) throws IOException;
115
```
116

117
[Stream Compression](./stream-compression.md)
118

119
### Direct Buffer Streaming
120

121
High-performance streaming API for direct ByteBuffers with minimal memory copying. Suitable for high-throughput applications and custom buffer management strategies.
122

123
```java { .api }
124
// Direct buffer compression stream
125
protected ZstdDirectBufferCompressingStream(ByteBuffer target, int level) throws IOException;
126
public void compress(ByteBuffer source) throws IOException;
127
public static int recommendedOutputBufferSize();
128

129
// Direct buffer decompression stream  
130
public ZstdDirectBufferDecompressingStream(ByteBuffer source);
131
public int read(ByteBuffer target) throws IOException;
132
public static int recommendedTargetBufferSize();
133
```
134

135
[Direct Buffer Streaming](./direct-buffer-streaming.md)
136

137
### Utility Functions
138

139
Utility methods for size estimation, error handling, dictionary creation, and accessing Zstd constants.
140

141
```java { .api }
142
// Size and bounds
143
public static long compressBound(long srcSize);
144
public static long decompressedSize(byte[] src);
145
public static long decompressedSize(ByteBuffer srcBuf);
146

147
// Error handling
148
public static boolean isError(long code);
149
public static String getErrorName(long code);
150

151
// Dictionary training
152
public static long trainFromBuffer(byte[][] samples, byte[] dictBuffer);
153

154
// Zstd constants
155
public static int magicNumber();
156
public static int windowLogMin();
157
public static int windowLogMax();
158
```
159

160
[Utility Functions](./utility-functions.md)
161

162
## Types
163

164
```java { .api }
165
// Dictionary classes
166
class ZstdDictCompress implements Closeable {
167
    public ZstdDictCompress(byte[] dict, int level);
168
    public ZstdDictCompress(byte[] dict, int offset, int length, int level);
169
    public void close() throws IOException;
170
}
171

172
class ZstdDictDecompress implements Closeable {
173
    public ZstdDictDecompress(byte[] dict);
174
    public ZstdDictDecompress(byte[] dict, int offset, int length);
175
    public void close() throws IOException;
176
}
177
```