ARCHIVER

archiver는 Java 21+ Virtual Threads 기반으로 설계된 경량화 및 고성능 모듈형 압축/해제 라이브러리입니다.

의존성이 없는 경량 Core 모듈(archiver)과 Apache Commons Compress 기반의 확장 모듈(archiver-extension)로 구별되며, Java SPI(Service Provider Interface)를 통해 동적으로 엔진을 분리 및 결합합니다.

---

Key Features

• Java 21+ Virtual Threads & CompletableFuture: 비동기 I/O 수행 시 가상 스레드를 활용하여 스레드 블로킹 최소화

• Modular Architecture:

• archiver: 외부 의존성이 전혀 없는 경량 모듈 (ZIP, GZIP 지원)

• archiver-extension: 고급 포맷 지원 (7Z, TAR, TAR_GZ, XZ, BZIP2, ZSTD)

• Default Security Hardening:

• Zip Slip 예외 검증: 상위 디렉터리 경로 이탈 공격(../) 차단

• Zip Bomb 예외 검증: 최대 허용 해제 용량 및 엔트리 수 제한

• Fluent Builder Pattern: intuitive하고 가독성 높은 일관된 API 제공

• In-Memory Utility: 단일 바이트 배열(byte[]) 대상 fast DEFLATE, ZSTD 유틸리티 제공

---

Installation

Gradle (Kotlin DSL)

repositories {
    maven {
        name = "Elex Repository"
        url = "https://artifacts.elex-project.com/repository/maven/"
    }
}
dependencies {
    // 1. 핵심 모듈 (ZIP, GZIP 기본 지원)
    implementation("com.elex_project:archiver:1.0.0")

    // 2. 확장 모듈 (7Z, TAR, XZ, BZIP2, ZSTD 등 - 필요 시 추가)
    implementation("com.elex_project:archiver-extension:1.0.0")
}

---

Usage

1. Synchronous File Compression / Decompression

ZIP 압축

Path sourceDir = Paths.get("./data");
Path zipFile = Paths.get("./backup.zip");

Archiver.compress()
    .source(sourceDir)
    .destination(zipFile)
    .format(ArchiveFormat.ZIP)
    .execute();

보안 정책이 적용된 ZIP 압축 해제

Path zipFile = Paths.get("./backup.zip");
Path targetDir = Paths.get("./extracted");

Archiver.decompress()
    .source(zipFile)
    .destination(targetDir)
    .format(ArchiveFormat.ZIP)
    .maxUncompressedSize(500 * 1024 * 1024L) // 최대 500MB 해제 허용 (Zip Bomb 방지)
    .maxEntryCount(1000)                      // 최대 1,000개 엔트리 허용
    .execute();

---

2. Extension Formats (7Z, TAR_GZ, ZSTD 등)

archiver-extension 모듈을 의존성에 추가하면 별도의 코드 수정 없이 ArchiveFormat 지정만으로 엔진이 자동으로 등록됩니다.

// 7-Zip 압축 및 암호화
Archiver.compress()
    .source(Paths.get("./data"))
    .destination(Paths.get("./archive.7z"))
    .format(ArchiveFormat.SEVEN_ZIP)
    .password("secret123".toCharArray())
    .execute();

// Zstandard (ZSTD) 단일 파일 압축
Archiver.compress()
    .source(Paths.get("./large_log.txt"))
    .destination(Paths.get("./large_log.txt.zst"))
    .format(ArchiveFormat.ZSTD)
    .execute();

---

3. Asynchronous Execution (Virtual Threads)

executeAsync()를 사용하면 Java 21 Virtual Thread 상에서 비동기로 실행되며 CompletableFuture<Void>를 반환합니다.

Path archive = Paths.get("./data.tar.gz");
Path output = Paths.get("./out");

Archiver.compress()
    .source(Paths.get("./data"))
    .destination(archive)
    .format(ArchiveFormat.TAR_GZ)
    .executeAsync()
    .thenCompose(v -> Archiver.decompress()
        .source(archive)
        .destination(output)
        .format(ArchiveFormat.TAR_GZ)
        .executeAsync())
    .thenRun(() -> System.out.println("Async processing completed!"))
    .exceptionally(ex -> {
        ex.printStackTrace();
        return null;
    });

---

4. Progress Listener

압축 및 해제 과정에서 실시간 진행률을 추적할 수 있습니다.

Archiver.compress()
    .source(Paths.get("./large_folder"))
    .destination(Paths.get("./output.zip"))
    .format(ArchiveFormat.ZIP)
    .progressListener((path, processedBytes, totalBytes) -> {
        System.out.printf("Processing: %s (%d / %d bytes)\n", 
            path.getFileName(), processedBytes, totalBytes);
    })
    .execute();

---

Supported Formats

Format	Module	Support Type	Password Support
ZIP	archiver-core	Multi-file / Directory	X
GZIP	archiver-core	Single File	X
7Z	archiver-extension	Multi-file / Directory	(AES)
TAR	archiver-extension	Multi-file / Directory	X
TAR_GZ	archiver-extension	Multi-file / Directory	X
XZ	archiver-extension	Single File	X
BZIP2	archiver-extension	Single File	X
ZSTD	archiver-extension	Single File	X

---

Exception Handling

라이브러리에서 발생하는 전용 예외 구조:

• ArchiverException: 최상위 표준 예외
• ZipSlipException: 디렉터리 이탈 공격(Zip Slip) 차단 시 발생
• ZipBombException: 최대 해제 용량 또는 엔트리 개수 초과 시 발생

try {
    Archiver.decompress()
        .source(untrustedZip)
        .destination(targetDir)
        .format(ArchiveFormat.ZIP)
        .execute();
} catch (ZipSlipException e) {
    System.err.println("Security Warning: Zip Slip attempt detected!");
} catch (ZipBombException e) {
    System.err.println("Security Warning: Zip Bomb threshold exceeded!");
} catch (ArchiverException e) {
    System.err.println("Archiver process failed: " + e.getMessage());
}

---

5. Fast In-Memory Byte Utilities

메모리 상에서 바이트 배열을 고속으로 압축/해제할 수 있는 유틸리티 클래스입니다.

• Deflate
• LZ4 (requires lz4-java)
• LZMA (requires xz)
• Snappy (requires snappy-java)
• Zstandard (requires zstd-jni)

dependencies {
    implementation("com.elex_project:archiver-deflate:1.0.0")
    implementation("com.elex_project:archiver-lz4:1.0.0")
    implementation("com.elex_project:archiver-lzma:1.0.0")
    implementation("com.elex_project:archiver-snappy:1.0.0")
    implementation("com.elex_project:archiver-zstd:1.0.0")
}

// DEFLATE (java.util.zip)
byte[] data = "Hello Archiver".getBytes(StandardCharsets.UTF_8);

byte[] compressed = DeflateUtils.compress(data);
byte[] decompressed = DeflateUtils.decompress(compressed);

// ZSTD (zstd-jni)
byte[] zstdCompressed = ZstdUtils.compress(data);
byte[] zstdDecompressed = ZstdUtils.decompress(zstdCompressed);

---

License

This project is licensed under the APACHE 2.0 License.

---

Copyright © 2026 Elex Project. All rights reserved.

https://www.elex-project.com/