Skip to content

Commit 9c0c8e7

Browse files
normanrznormanrz
committed
javadoc
1 parent 65b4bba commit 9c0c8e7

4 files changed

Lines changed: 124 additions & 29 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,3 @@ jobs:
147147
with:
148148
name: blosc-jar
149149
path: target/*.jar
150-
151-
- name: Smoke test
152-
run: java -cp target/*.jar dev.zarr.bloscjava.Blosc

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ byte[] compress(
4040
Default: `ZSTD`
4141
- `compressorLevel`: Number from 0 to 9 (0 = little compression, 9 = strongest compression). Default: 5.
4242
- `shuffle`: Whether to use shuffling. Available choices: `NOSHUFFLE`, `BIT_SHUFFLE`, `BYTE_SHUFFLE`. Default:
43-
`BIT_SHUFFLE` for typeSize == 1, `BYTE_SHUFFLE` else
43+
`BIT_SHUFFLE` for typeSize == 1, `BYTE_SHUFFLE` otherwise.
4444
- `blockSize`: Requested size of compressed blocks. Use 0 for automatic block sizes.
4545
- `numThreads`: Number of threads to be used internally. Default: 1.
4646

‎pom.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
<groupId>dev.zarr</groupId>
88
<artifactId>blosc-java</artifactId>
99
<version>0.1-SNAPSHOT</version>
10-
<packaging>jar</packaging>
1110

1211
<licenses>
1312
<license>
@@ -56,4 +55,4 @@
5655
</dependency>
5756
</dependencies>
5857

59-
</project>
58+
</project>

‎src/main/java/dev/zarr/bloscjava/Blosc.java‎

Lines changed: 122 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@
55
import java.io.InputStream;
66
import java.nio.file.Files;
77
import java.nio.file.StandardCopyOption;
8-
import java.util.Arrays;
98

9+
/**
10+
* A Java library for the Blosc codec. Wraps around the <a href="https://github.com/Blosc/c-blosc">c-blosc library</a> with JNI.
11+
*/
1012
public class Blosc {
1113
static {
1214
try {
@@ -16,47 +18,112 @@ public class Blosc {
1618
}
1719
}
1820

19-
public static void main(String[] args) {
20-
byte[] buf = new byte[256];
21-
for (int i = 0; i < buf.length; i++) buf[i] = (byte) (i % 12);
22-
23-
byte[] compBuf = Blosc.compress(buf, 1, Blosc.Compressor.ZSTD, 9);
24-
System.out.println(compBuf.length);
25-
26-
byte[] decompBuf = Blosc.decompress(compBuf);
27-
28-
System.out.println(Arrays.equals(buf, decompBuf));
21+
// Disable constructor
22+
private Blosc() {
2923
}
3024

25+
/**
26+
* Compresses a byte array with Blosc.
27+
*
28+
* @param src Byte array to be compressed.
29+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
30+
* @param compressor Compression algorithm. Available choices: LZ4, LZ4HC, BLOSCLZ, ZSTD, SNAPPY, ZLIB.
31+
* @param compressorLevel Number from 0 to 9 (0 = little compression, 9 = strongest compression).
32+
* @param shuffle Whether to use shuffling. Available choices: NOSHUFFLE, BIT_SHUFFLE, BYTE_SHUFFLE. Recommended:
33+
* BIT_SHUFFLE for typeSize == 1, BYTE_SHUFFLE otherwise.
34+
* @param blockSize Requested size of compressed blocks. Use 0 for automatic block sizes.
35+
* @param numThreads Number of threads to be used internally.
36+
* @return the compressed byte array
37+
*/
3138
public static byte[] compress(byte[] src, int typeSize, Compressor compressor, int compressorLevel, Shuffle shuffle, int blockSize, int numThreads) {
32-
return _compress(src, typeSize, compressorLevel, shuffle.value(), blockSize, compressor.value(), numThreads);
39+
return _compress(src, typeSize, compressorLevel, shuffle.shuffle, blockSize, compressor.compressor, numThreads);
3340
}
3441

42+
/**
43+
* Compresses a byte array with Blosc.
44+
*
45+
* @param src Byte array to be compressed.
46+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
47+
* @param compressor Compression algorithm. Available choices: LZ4, LZ4HC, BLOSCLZ, ZSTD, SNAPPY, ZLIB.
48+
* @param compressorLevel Number from 0 to 9 (0 = little compression, 9 = strongest compression).
49+
* @param shuffle Whether to use shuffling. Available choices: NOSHUFFLE, BIT_SHUFFLE, BYTE_SHUFFLE. Recommended:
50+
* BIT_SHUFFLE for typeSize == 1, BYTE_SHUFFLE otherwise.
51+
* @param blockSize Requested size of compressed blocks. Use 0 for automatic block sizes.
52+
* @return the compressed byte array
53+
*/
3554
public static byte[] compress(byte[] src, int typeSize, Compressor compressor, int compressorLevel, Shuffle shuffle, int blockSize) {
3655
return compress(src, typeSize, compressor, compressorLevel, shuffle, blockSize, 1);
3756
}
3857

58+
/**
59+
* Compresses a byte array with Blosc with default settings.
60+
*
61+
* @param src Byte array to be compressed.
62+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
63+
* @param compressor Compression algorithm. Available choices: Available choices: LZ4, LZ4HC, BLOSCLZ, ZSTD, SNAPPY, ZLIB.
64+
* @param compressorLevel Number from 0 to 9 (0 = little compression, 9 = strongest compression).
65+
* @param shuffle Whether to use shuffling. Available choices: NOSHUFFLE, BIT_SHUFFLE, BYTE_SHUFFLE. Recommended:
66+
* BIT_SHUFFLE for typeSize == 1, BYTE_SHUFFLE otherwise.
67+
* @return the compressed byte array
68+
*/
3969
public static byte[] compress(byte[] src, int typeSize, Compressor compressor, int compressorLevel, Shuffle shuffle) {
4070
return compress(src, typeSize, compressor, compressorLevel, shuffle, 0);
4171
}
4272

73+
/**
74+
* Compresses a byte array with Blosc with default settings.
75+
*
76+
* @param src Byte array to be compressed.
77+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
78+
* @param compressor Compression algorithm. Available choices: LZ4, LZ4HC, BLOSCLZ, ZSTD, SNAPPY, ZLIB.
79+
* @param compressorLevel Number from 0 to 9 (0 = little compression, 9 = strongest compression).
80+
* @return the compressed byte array
81+
*/
4382
public static byte[] compress(byte[] src, int typeSize, Compressor compressor, int compressorLevel) {
4483
return compress(src, typeSize, compressor, compressorLevel,
4584
typeSize == 1 ? Shuffle.BIT_SHUFFLE : Shuffle.BYTE_SHUFFLE);
4685
}
4786

87+
/**
88+
* Compresses a byte array with Blosc with default settings.
89+
*
90+
* @param src Byte array to be compressed.
91+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
92+
* @param compressor Compression algorithm. Available choices: LZ4, LZ4HC, BLOSCLZ, ZSTD, SNAPPY, ZLIB.
93+
* @return the compressed byte array
94+
*/
4895
public static byte[] compress(byte[] src, int typeSize, Compressor compressor) {
4996
return compress(src, typeSize, compressor, 5);
5097
}
5198

99+
/**
100+
* Compresses a byte array with Blosc with default settings (ZSTD compression).
101+
*
102+
* @param src Byte array to be compressed.
103+
* @param typeSize Number of bytes per primitive value (e.g. 1 for int8, 2 for int16, 4 for int32).
104+
* @return the compressed byte array
105+
*/
52106
public static byte[] compress(byte[] src, int typeSize) {
53-
return compress(src, typeSize, Compressor.LZ4);
107+
return compress(src, typeSize, Compressor.ZSTD);
54108
}
55109

110+
/**
111+
* Decompresses a byte array with Blosc.
112+
*
113+
* @param src Byte array to be decompressed.
114+
* @param numThreads Number of threads to be used internally.
115+
* @return the decompressed byte array
116+
*/
56117
public static byte[] decompress(byte[] src, int numThreads) {
57118
return _decompress(src, numThreads);
58119
}
59120

121+
/**
122+
* Decompresses a byte array with Blosc.
123+
*
124+
* @param src Byte array to be decompressed.
125+
* @return the decompressed byte array
126+
*/
60127
public static byte[] decompress(byte[] src) {
61128
return decompress(src, 1);
62129
}
@@ -101,29 +168,61 @@ private static File loadLibraryFromJarToTemp() throws IOException {
101168
}
102169
}
103170

171+
/**
172+
* Configures the internal compression of the Blosc codec.
173+
*/
104174
public enum Compressor {
105-
LZ4("lz4"), LZ4HC("lz4hc"), BLOSCLZ("blosclz"), ZSTD("zstd"), SNAPPY("snappy"), ZLIB("zlib");
175+
/**
176+
* <a href="http://www.lz4.org/">LZ4 compression</a>
177+
*/
178+
LZ4("lz4"),
179+
/**
180+
* High compression variant of <a href="http://www.lz4.org/">LZ4 compression</a>
181+
*/
182+
LZ4HC("lz4hc"),
183+
/**
184+
* Compression based on <a href="https://ariya.github.io/FastLZ/">FastLZ</a>
185+
*/
186+
BLOSCLZ("blosclz"),
187+
/**
188+
* <a href="https://facebook.github.io/zstd/">Zstandard compression</a>
189+
*/
190+
ZSTD("zstd"),
191+
/**
192+
* <a href="https://google.github.io/snappy/">Snappy compression</a>
193+
*/
194+
SNAPPY("snappy"),
195+
/**
196+
* <a href="https://zlib.net/">Zlib compression</a>
197+
*/
198+
ZLIB("zlib");
106199
private final String compressor;
107200

108201
Compressor(String compressor) {
109202
this.compressor = compressor;
110203
}
111-
112-
public String value() {
113-
return compressor;
114-
}
115204
}
116205

206+
/**
207+
* Configures the shuffling for the Blosc codec.
208+
*/
117209
public enum Shuffle {
118-
NO_SHUFFLE(0), BYTE_SHUFFLE(1), BIT_SHUFFLE(2);
210+
/**
211+
* Disable shuffling
212+
*/
213+
NO_SHUFFLE(0),
214+
/**
215+
* Byte-wise shuffling
216+
*/
217+
BYTE_SHUFFLE(1),
218+
/**
219+
* Bit-wise shuffling
220+
*/
221+
BIT_SHUFFLE(2);
119222
private final int shuffle;
120223

121224
Shuffle(int shuffle) {
122225
this.shuffle = shuffle;
123226
}
124-
125-
public int value() {
126-
return shuffle;
127-
}
128227
}
129228
}

0 commit comments

Comments
 (0)