bundles/org.simantics.lz4/README.md

   1 # LZ4 Java
   2
   3 LZ4 compression for Java, based on Yann Collet's work available at
   4 http://code.google.com/p/lz4/.
   5
   6 This library provides access to two compression methods that both generate a
   7 valid LZ4 stream:
   8  - fast scan (LZ4):
   9    - low memory footprint (~ 16 KB),
  10    - very fast (fast scan with skipping heuristics in case the input looks
  11      incompressible),
  12    - reasonable compression ratio (depending on the redundancy of the input).
  13  - high compression (LZ4 HC):
  14    - medium memory footprint (~ 256 KB),
  15    - rather slow (~ 10 times slower than LZ4),
  16    - good compression ratio (depending on the size and the redundancy of the
  17      input).
  18
  19 The streams produced by those 2 compression algorithms use the same compression
  20 format, are very fast to decompress and can be decompressed by the same
  21 decompressor instance.
  22
  23 ## Implementations
  24
  25 For LZ4 compressors, LZ4 HC compressors and decompressors, 3 implementations are
  26 available:
  27  - JNI bindings to the original C implementation by Yann Collet,
  28  - a pure Java port of the compression and decompression algorithms,
  29  - a Java port that uses the sun.misc.Unsafe API in order to achieve compression
  30    and decompression speeds close to the C implementation.
  31
  32 Have a look at LZ4Factory for more information.
  33
  34 ## Compatibility notes
  35
  36  - Compressors and decompressors are interchangeable: it is perfectly correct
  37    to compress with the JNI bindings and to decompress with a Java port, or the
  38    other way around.
  39
  40  - Compressors might not generate the same compressed streams on all platforms,
  41    especially if CPU endianness differs, but the compressed streams can be
  42    safely decompressed by any decompressor implementation on any platform.
  43
  44 ## Example
  45
  46 ```java
  47 LZ4Factory factory = LZ4Factory.fastestInstance();
  48
  49 byte[] data = "12345345234572".getBytes("UTF-8");
  50 final int decompressedLength = data.length;
  51
  52 // compress data
  53 LZ4Compressor compressor = factory.fastCompressor();
  54 int maxCompressedLength = compressor.maxCompressedLength(decompressedLength);
  55 byte[] compressed = new byte[maxCompressedLength];
  56 int compressedLength = compressor.compress(data, 0, decompressedLength, compressed, 0, maxCompressedLength);
  57
  58 // decompress data
  59 // - method 1: when the decompressed length is known
  60 LZ4FastDecompressor decompressor = factory.fastDecompressor();
  61 byte[] restored = new byte[decompressedLength];
  62 int compressedLength2 = decompressor.decompress(compressed, 0, restored, 0, decompressedLength);
  63 // compressedLength == compressedLength2
  64
  65 // - method 2: when the compressed length is known (a little slower)
  66 // the destination buffer needs to be over-sized
  67 LZ4SafeDecompressor decompressor2 = factory.safeDecompressor();
  68 int decompressedLength2 = decompressor2.decompress(compressed, 0, compressedLength, restored, 0);
  69 // decompressedLength == decompressedLength2
  70 ```
  71
  72 # xxhash Java
  73
  74 xxhash hashing for Java, based on Yann Collet's work available at
  75 http://code.google.com/p/xxhash/. xxhash is a non-cryptographic, extremly fast
  76 and high-quality ([SMHasher](http://code.google.com/p/smhasher/wiki/SMHasher)
  77 score of 10) hash function.
  78
  79 ## Implementations
  80
  81 Similarly to LZ4, 3 implementations are available: JNI bindings, pure Java port
  82 and pure Java port that uses sun.misc.Unsafe.
  83
  84 Have a look at XXHashFactory for more information.
  85
  86 ## Compatibility notes
  87
  88  - All implementation return the same hash for the same input bytes:
  89    - on any JVM,
  90    - on any platform (even if the endianness or integer size differs).
  91
  92 ## Example
  93
  94 ```java
  95 XXHashFactory factory = XXHashFactory.fastestInstance();
  96
  97 byte[] data = "12345345234572".getBytes("UTF-8");
  98 ByteArrayInputStream in = new ByteArrayInputStream(data);
  99
 100 int seed = 0x9747b28c; // used to initialize the hash value, use whatever
 101                        // value you want, but always the same
 102 StreamingXXHash32 hash32 = factory.newStreamingHash32(seed);
 103 byte[] buf = new byte[8]; // for real-world usage, use a larger buffer, like 8192 bytes
 104 for (;;) {
 105   int read = in.read(buf);
 106   if (read == -1) {
 107     break;
 108   }
 109   hash32.update(buf, 0, read);
 110 }
 111 int hash = hash32.getValue();
 112 ```
 113
 114 # Download
 115
 116 You can download released artifacts from [Maven Central](http://repo1.maven.org/maven2/net/jpountz/lz4/lz4/).
 117
 118 # Documentation
 119
 120  - [lz4](http://jpountz.github.com/lz4-java/1.2.0/docs/net/jpountz/lz4/package-summary.html)
 121  - [xxhash](http://jpountz.github.com/lz4-java/1.2.0/docs/net/jpountz/xxhash/package-summary.html)
 122  - [changelog](http://github.com/jpountz/lz4-java/blob/master/CHANGES.md)
 123
 124 # Performance
 125
 126 Both lz4 and xxhash focus on speed. Although compression, decompression and
 127 hashing performance can depend a lot on the input (there are lies, damn lies
 128 and benchmarks), here are some benchmarks that try to give a sense of the
 129 speed at which they compress/decompress/hash bytes.
 130
 131  - [lz4 compression](http://jpountz.github.com/lz4-java/1.2.0/lz4-compression-benchmark/)
 132  - [lz4 decompression](http://jpountz.github.com/lz4-java/1.2.0/lz4-decompression-benchmark/)
 133  - [xxhash hashing](http://jpountz.github.com/lz4-java/1.2.0/xxhash-benchmark/)
 134
 135 # Build
 136
 137 ## Requirements
 138
 139  - JDK version 7 or newer,
 140  - ant,
 141  - ivy.
 142
 143 If ivy is not installed yet, ant can take care of it for you, just run
 144 `ant ivy-bootstrap`. The library will be installed under ${user.home}/.ant/lib.
 145
 146 ## Instructions
 147
 148 Then run `ant`. It will:
 149
 150  - generate some Java source files in `build/java` from the templates that are
 151    located under `src/build`,
 152  - compile the lz4 and xxhash libraries and their JNI (Java Native Interface)
 153    bindings,
 154  - compile Java sources in `src/java` (normal sources), `src/java-unsafe`
 155    (sources that make use of `sun.misc.Unsafe`) and `build/java`
 156    (auto-generated sources) to `build/classes`, `build/unsafe-classes` and
 157    `build/generated-classes`,
 158  - generate a JAR file called lz4-${version}.jar under the `dist` directory.
 159
 160 The JAR file that is generated contains Java class files, the native library
 161 and the JNI bindings. If you add this JAR to your classpath, the native library
 162 will be copied to a temporary directory and dynamically linked to your Java
 163 application.