This version is still in development and is not considered stable yet. For the latest stable version, please use Compress4J 5.x!

tar

Tar archives are plain or compressed. TarArchiveCreator and TarArchiveExtractor handle every variant; the compression is a Compression value, not a separate class.

Example Usage

Tar Creation
try (TarArchiveCreator tarCreator = TarArchiveCreator.builder(Path.of("example.tar"))
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarCreator.addDirectoryRecursively(Path.of("exampleDir"));
    tarCreator.addFile(Path.of("path/to/file.txt"));
}
Tar Extraction
try (TarArchiveExtractor tarExtractor = TarArchiveExtractor.builder(Path.of("example.tar"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarExtractor.extract(Path.of("outputDir"));
}

Compression

Pass a Compression to TarArchiveCreator.builder(…​).compression(…​) to write a compressed tar. The value carries the codec options, such as Compression.gzip().level(9) or Compression.zstd().level(6). Every writable codec in the codec table works except Pack200, and raw Snappy, which needs uncompressedSize(…​) that a tar stream rarely knows up front.

The extractor detects the compression from the leading bytes when you set none:

  • gzip, bzip2, xz, Zstandard, framed LZ4, framed Snappy and Unix .Z have strong magic numbers and are detected. Concatenated gzip, bzip2, xz and framed LZ4 members are read; the others are not verified for it.

  • LZMA has no magic number: call .compression(Compression.lzma()) on the extractor.

  • Pack200 is never detected and the tar extractor does not read it.

  • Input with no detected signature reads as plain tar; input that is not a tar archive fails with an IOException.

An explicit compression(…​) on the extractor is used exactly as given.

Tar Gzip Creation
try (TarArchiveCreator tarGzCreator = TarArchiveCreator.builder(Path.of("example.tar.gz"))
        .compression(Compression.gzip()
                .bufferSize(1024)
                .level(BEST_COMPRESSION)
                .comment("comment")
                .deflateStrategy(DeflateStrategy.HUFFMAN_ONLY)
                .operatingSystem(0))
        .longFileMode(TarLongFileMode.POSIX)
        .bigNumberMode(TarBigNumberMode.POSIX)
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarGzCreator.addDirectoryRecursively(Path.of("exampleDir"));
    tarGzCreator.addFile(Path.of("path/to/file.txt"));
}
Tar Gzip Extraction
try (TarArchiveExtractor tarGzExtractor = TarArchiveExtractor.builder(Path.of("example.tar.gz"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarGzExtractor.extract(Path.of("outputDir"));
}
Tar BZip2 Creation
try (TarArchiveCreator tarBzip2Creator = TarArchiveCreator.builder(Path.of("example.tar.bz2"))
        .compression(Compression.bzip2().blockSize(9))
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarBzip2Creator.addDirectoryRecursively(Path.of("exampleDir"));
    tarBzip2Creator.addFile(Path.of("path/to/file.txt"));
}
Tar Bzip2 Extraction
try (TarArchiveExtractor tarBzip2Extractor = TarArchiveExtractor.builder(Path.of("example.tar.bz2"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarBzip2Extractor.extract(Path.of("outputDir"));
}
Tar XZ Creation
try (TarArchiveCreator tarXzCreator = TarArchiveCreator.builder(Path.of("example.tar.xz"))
        .compression(Compression.xz().preset(6))
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarXzCreator.addDirectoryRecursively(Path.of("exampleDir"));
    tarXzCreator.addFile(Path.of("path/to/file.txt"));
}
Tar XZ Extraction
try (TarArchiveExtractor tarXzExtractor = TarArchiveExtractor.builder(Path.of("example.tar.xz"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarXzExtractor.extract(Path.of("outputDir"));
}
Tar Zstandard Creation
try (TarArchiveCreator tarZstdCreator = TarArchiveCreator.builder(Path.of("example.tar.zst"))
        .compression(Compression.zstd().level(6))
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarZstdCreator.addDirectoryRecursively(Path.of("exampleDir"));
    tarZstdCreator.addFile(Path.of("path/to/file.txt"));
}
Tar Zstandard Extraction
try (TarArchiveExtractor tarZstdExtractor = TarArchiveExtractor.builder(Path.of("example.tar.zst"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarZstdExtractor.extract(Path.of("outputDir"));
}
Tar LZMA Creation
try (TarArchiveCreator tarLzmaCreator = TarArchiveCreator.builder(Path.of("example.tar.lzma"))
        .compression(Compression.lzma())
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarLzmaCreator.addDirectoryRecursively(Path.of("exampleDir"));
    tarLzmaCreator.addFile(Path.of("path/to/file.txt"));
}
Tar LZMA Extraction
try (TarArchiveExtractor tarLzmaExtractor = TarArchiveExtractor.builder(Path.of("example.tar.lzma"))
        .compression(Compression.lzma())
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarLzmaExtractor.extract(Path.of("outputDir"));
}
Tar framed LZ4 Creation
try (TarArchiveCreator tarLz4Creator = TarArchiveCreator.builder(Path.of("example.tar.lz4"))
        .compression(Compression.lz4Framed())
        .blockSize(1024)
        .encoding(UTF_8)
        .addPaxHeadersForNonAsciiNames(true)
        .bigNumberMode(TarBigNumberMode.ERROR)
        .longFileMode(TarLongFileMode.GNU)
        .filter(s -> !s.name().endsWith("some_file.txt"))
        .build()) {
    tarLz4Creator.addDirectoryRecursively(Path.of("exampleDir"));
    tarLz4Creator.addFile(Path.of("path/to/file.txt"));
}
Tar framed LZ4 Extraction
try (TarArchiveExtractor tarLz4Extractor = TarArchiveExtractor.builder(Path.of("example.tar.lz4"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarLz4Extractor.extract(Path.of("outputDir"));
}
Read-only: Compress4J can extract this format but cannot create it.
Tar Unix compress (.Z) Extraction
try (TarArchiveExtractor tarZExtractor = TarArchiveExtractor.builder(Path.of("example.tar.Z"))
        .filter(entry -> !entry.name().startsWith("bad"))
        .errorHandler((entry, failure) -> entry.name().endsWith(".tmp") ? SKIP : ABORT)
        .escapingSymlinkPolicy(EscapingSymlinkPolicy.DISALLOW)
        .postProcessor((entry, exception) -> {})
        .stripComponents(1)
        .overwrite(true)
        .build()) {
    tarZExtractor.extract(Path.of("outputDir"));
}