Package net.jpountz.lz4

Class LZ4Factory

java.lang.Object
net.jpountz.lz4.LZ4Factory
public final class LZ4Factory extends Object
Entry point for the LZ4 API.

This class has 3 instances

Only the safe instance is guaranteed to work on your JVM, as a consequence it is advised to use the fastestInstance() or fastestJavaInstance() to pull a LZ4Factory instance.

All methods from this class are very costly, so you should get an instance once, and then reuse it whenever possible. This is typically done by storing a LZ4Factory instance in a static field.

  • Method Details

    • nativeInstance

      public static LZ4Factory nativeInstance()
      Returns a LZ4Factory instance that returns compressors and decompressors that are native bindings to the original C library.

      Please note that this instance has some traps you should be aware of:

      1. Upon loading this instance, files will be written to the temporary directory of the system. Although these files are supposed to be deleted when the JVM exits, they might remain on systems that don't support removal of files being used such as Windows.
      2. The instance can only be loaded once per JVM. This can be a problem if your application uses multiple class loaders (such as most servlet containers): this instance will only be available to the children of the class loader which has loaded it. As a consequence, it is advised to either not use this instance in webapps or to put this library in the lib directory of your servlet container so that it is loaded by the system class loader.
      3. From lz4-java version 1.6.0, a LZ4FastDecompressor instance returned by fastDecompressor() of this instance is SLOWER than a LZ4SafeDecompressor instance returned by safeDecompressor(), due to a change in the original LZ4 C implementation. The corresponding C API function is deprecated. Hence use of fastDecompressor() is deprecated for this instance.
      Returns:
      a LZ4Factory instance that returns compressors and decompressors that are native bindings to the original C library

    • nativeInsecureInstance

      @Deprecated public static LZ4Factory nativeInsecureInstance()
      Deprecated.
      Never decompress untrusted inputs with this instance. Prefer nativeInstance().
      Insecure variant of nativeInstance(). The JNI-based LZ4FastDecompressor is not secure for untrusted inputs, so nativeInstance() will instead return the slower safe java implementation from fastDecompressor(). If that implementation is too slow for you, it is recommended to move to safeDecompressor(), which is actually faster even than the JNI fastDecompressor(). Only if that is not an option for you, and you can guarantee no untrusted inputs will be decompressed, should you use this method.
      Returns:
      An insecure, JNI-backed LZ4Factory

    • safeInstance

      public static LZ4Factory safeInstance()
      Returns a LZ4Factory instance that returns compressors and decompressors that are written with Java's official API.
      Returns:
      a LZ4Factory instance that returns compressors and decompressors that are written with Java's official API.

    • unsafeInstance

      @Deprecated public static LZ4Factory unsafeInstance()
      Deprecated.
      Note: It is not yet clear which Unsafe-based implementations are secure. Out of caution, this method currently returns the safeInstance(). In a future version, when security has been assessed, this method may return to Unsafe.
      Returns a LZ4Factory instance that returns compressors and decompressors that may use Unsafe to speed up compression and decompression.
      Returns:
      a LZ4Factory instance that returns compressors and decompressors that may use Unsafe to speed up compression and decompression.

    • unsafeInsecureInstance

      @Deprecated public static LZ4Factory unsafeInsecureInstance()
      Deprecated.
      Never decompress untrusted inputs with this instance. Prefer unsafeInstance().
      Insecure variant of unsafeInstance(). The Unsafe-based LZ4FastDecompressor is not secure for untrusted inputs, so unsafeInstance() will instead return the slower safe java implementation from fastDecompressor(). If that implementation is too slow for you, it is recommended to move to safeDecompressor(). Only if that is not an option for you, and you can guarantee no untrusted inputs will be decompressed, should you use this method.
      Returns:
      An insecure, Unsafe-backed LZ4Factory

    • fastestJavaInstance

      public static LZ4Factory fastestJavaInstance()
      Returns the fastest available LZ4Factory instance which does not rely on JNI bindings. It first tries to load the unsafe instance, and then the safe Java instance if the JVM doesn't have a working Unsafe.
      Returns:
      the fastest available LZ4Factory instance which does not rely on JNI bindings.

    • fastestInstance

      public static LZ4Factory fastestInstance()
      Returns the fastest available LZ4Factory instance. If the class loader is the system class loader and if the native instance loads successfully, then the native instance is returned, otherwise the fastest Java instance is returned.

      Please read javadocs of nativeInstance() before using this method.

      Returns:
      the fastest available LZ4Factory instance

    • fastCompressor

      public LZ4Compressor fastCompressor()
      Returns a blazing fast LZ4Compressor.
      Returns:
      a blazing fast LZ4Compressor

    • highCompressor

      public LZ4Compressor highCompressor()
      Returns a LZ4Compressor which requires more memory than fastCompressor() and is slower but compresses more efficiently.
      Returns:
      a LZ4Compressor which requires more memory than fastCompressor() and is slower but compresses more efficiently.

    • highCompressor

      public LZ4Compressor highCompressor(int compressionLevel)
      Returns a LZ4Compressor which requires more memory than fastCompressor() and is slower but compresses more efficiently. The compression level can be customized.

      For current implementations, the following is true about compression level:

      1. It should be in range [1, 17]
      2. A compression level higher than 17 would be treated as 17.
      3. A compression level lower than 1 would be treated as 9.
      Note that compression levels from different implementations (native, unsafe Java, and safe Java) cannot be compared with one another. Specifically, the native implementation of a high compression level is not necessarily faster than the safe/unsafe Java implementation of the same compression level.
      Parameters:
      compressionLevel - the compression level between [1, 17]; the higher the level, the higher the compression ratio
      Returns:
      a LZ4Compressor which requires more memory than fastCompressor() and is slower but compresses more efficiently.

    • fastDecompressor

      public LZ4FastDecompressor fastDecompressor()
      Returns a LZ4FastDecompressor instance. Use of this method is deprecated for the native instance.
      Returns:
      a LZ4FastDecompressor instance
      See Also:

    • safeDecompressor

      public LZ4SafeDecompressor safeDecompressor()
      Returns a LZ4SafeDecompressor instance.
      Returns:
      a LZ4SafeDecompressor instance

    • unknownSizeDecompressor

      public LZ4UnknownSizeDecompressor unknownSizeDecompressor()
      Deprecated.
      use safeDecompressor()
      Returns a LZ4UnknownSizeDecompressor instance.
      Returns:
      a LZ4UnknownSizeDecompressor instance

    • decompressor

      public LZ4Decompressor decompressor()
      Deprecated.
      use fastDecompressor()
      Returns a LZ4Decompressor instance.
      Returns:
      a LZ4Decompressor instance

    • main

      public static void main(String[] args)
      Prints the fastest instance.
      Parameters:
      args - no argument required

    • toString

      public String toString()
      Overrides:
      toString in class Object