[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"));
}