archie

Archie - Streaming Archive Transformation Library

Java library for stream-based manipulation of archive files (ZIP, JAR, TAR.GZ). Apply transformations on-the-fly without extracting to disk: inject entries, replace content, prepend text, skip entries, and enhance bytecode -- all while streaming.

Package: org.tomitribe.archie

Maven Coordinates

<groupId>org.tomitribe</groupId>
<artifactId>archie</artifactId>
<version>1.1-SNAPSHOT</version>

Core Concept

Build a Transformations object with rules, then apply it to an archive via a format-specific transformer. Entries stream through one at a time -- no disk extraction, no full archive in memory.

Transformations transformations = Transformations.builder()
    .before(InsertEntry.builder()
        .name("README.txt")
        .content("Hello, World!")
        .build())
    .build();

new JarTransformation(transformations)
    .transform(new File("input.jar"), new File("output.jar"));

Transformations Builder

Central configuration for all transformation rules. Built via Transformations.builder().

Content Transformation

Transform entry contents using Function<byte[], byte[]>:

Transformations.builder()
    // Replace content of specific entries
    .add(name -> name.equals("config.xml"),
         bytes -> newContent.getBytes())

    // Enhance class files (bytecode manipulation)
    .enhance("org/example/MyClass.class", enhancerFunction)

    // Enhance by predicate
    .enhance(name -> name.endsWith(".class"), enhancerFunction)

    // Prepend text to matching entries
    .prepend(name -> name.equals("META-INF/LICENSE"),
        "Copyright Acme Corporation. 2025\n\n")

    .build();

Entry Injection

Insert new entries before or after archive processing:

Transformations.builder()
    // Insert at start of archive
    .before(InsertEntry.builder()
        .name("META-INF/NOTICE")
        .content("Added by build pipeline")
        .build())

    // Insert at end of archive
    .after(InsertEntry.builder()
        .name("build-info.txt")
        .file(new File("build-info.txt"))
        .build())

    // Inline all entries from another JAR (fat JAR)
    .after(new InlineJar(new File("library.jar")))

    // Raw Consumer<ArchiveOutputStream> callback
    .before(archiveOut -> {
        final byte[] bytes = "content".getBytes();
        final JarArchiveEntry entry = new JarArchiveEntry("added.txt");
        entry.setSize(bytes.length);
        archiveOut.putArchiveEntry(entry);
        archiveOut.write(bytes);
        archiveOut.closeArchiveEntry();
    })

    .build();

Entry-Level Callbacks

Execute logic before or after specific entries:

Transformations.builder()
    .beforeEntry(name -> name.endsWith("Red.class"), out -> {
        out.writeEntry("BeforeRed.txt", "Pre-content");
    })
    .afterEntry(name -> name.endsWith("Red.class"), out -> {
        out.writeEntry("AfterRed.txt", "Post-content");
    })
    .build();

Skipping Entries

Remove entries from the output:

Transformations.builder()
    .skip(entry -> entry.equals("unwanted.txt"))
    .skip(entry -> entry.endsWith(".bak"))
    .build();

Skip Transformation (Signed JARs)

Prevent content transformation on signed JARs or specific entries:

Transformations.builder()
    .skipTransformation(name -> name.startsWith("META-INF/"))
    .build();

Archie automatically detects signed JARs (manifest with -Digest attributes) and skips their transformation.

Callback Execution Order

1. beforeArchive() -- executed first
2. For each entry:
   • beforeEntry(name) if predicate matches
   • Content transformation via enhance() / prepend() / add()
   • Entry written to output
   • afterEntry(name) if predicate matches
3. afterArchive() -- executed last

Format-Specific Transformers

Each implements the Transformer interface and has a fluent builder.

JarTransformation

For JAR, WAR, EAR, RAR files. Preserves compression method, timestamps, Unix mode, CRC32.

JarTransformation.builder()
    .enhance("org/example/MyClass.class", enhancerFunction)
    .skip(entry -> entry.equals("old-file.txt"))
    .before(InsertEntry.builder().name("added.txt").content("hello").build())
    .build()
    .transform(inputFile, outputFile);

ZipTransformation

For ZIP files. Same builder pattern.

ZipTransformation.builder()
    .prepend(name -> name.equals("README"), "Header\n\n")
    .build()
    .transform(inputStream, outputStream);

TarGzTransformation

For TAR.GZ files. Handles symlinks, hard links, and long filenames (POSIX mode).

TarGzTransformation.builder()
    .before(InsertEntry.builder().name("notice.txt").content("Built by CI").build())
    .build()
    .transform(inputFile, outputFile);

PassThroughTransformation

Copies input to output unchanged. Used as fallback for unsupported formats.

Auto-Detection

Transformations.transformer(File) selects the right transformer by extension:

Extension	Transformer
.jar, .war, .ear, .rar	JarTransformation
.zip	ZipTransformation
.tar.gz	TarGzTransformation
.pdf	PassThroughTransformation

transformations.transformer(archiveFile).transform(archiveFile, outputFile);

Transformer Interface

public interface Transformer {
    void transform(InputStream in, OutputStream out) throws IOException;
    default void transform(File src, File dest) throws IOException;
}

InsertEntry

Inserts a new entry into an archive. Detects archive type automatically.

InsertEntry.builder()
    .name("path/in/archive.txt")
    .content("string content")     // or
    .file(new File("local.txt"))   // or
    .bytes(() -> byteArray)        // lazy Supplier<byte[]>
    .build();

ReplaceFileContent

Replaces entry content with a new string:

ReplaceFileContent.builder()
    .content("new content")
    .build();
// Returns Function<byte[], byte[]>

InlineJar

Extracts entries from a source JAR and inlines them into the output archive. Preserves all entry metadata.

new InlineJar(new File("library.jar"))
// Use as Consumer<ArchiveOutputStream> in .after() or .before()

Binary — Digest File Management

File wrapper that manages associated digest files (.md5, .sha1, .sha256).

Binary binary = new Binary("application.jar");

// Write with automatic digest generation
try (Binary.BinaryOutputStream out = binary.write()) {
    out.write(fileBytes);
}
// Creates application.jar.md5, application.jar.sha1, application.jar.sha256

// Read digests
String md5 = binary.getMd5();
String sha1 = binary.getSha1();
String sha256 = binary.getSha256();

// Verify against stored digests
binary.verify();                    // throws on mismatch
binary.verify(System.out);          // logs results, returns boolean

// Generate digests for existing file
binary.generate();
binary.generate(true);              // overwrite existing digest files

Digest Enum

Digest.MD5.digest(file)             // hex digest of file
Digest.SHA1.digest(file)
Digest.SHA256.digest(file)

// Wrap streams for transparent digest calculation
DigestsOutputStream dos = Digest.SHA256.digest(outputStream);
dos.write(data);
String hex = dos.hex();

DigestsInputStream dis = Digest.MD5.digest(inputStream);
// read all data...
String hex = dis.hex();
String base64 = dis.base64();

Utility Classes

Zips

Zips.unzip(zipFile, destinationDir);
String listing = Zips.list(zipFile);    // tree listing with hashes

TarGzs

TarGzs.untargz(tarGzFile, destinationDir);
String listing = TarGzs.list(tarGzFile);

Both support recursive listing of nested archives and stream-based extraction with file filters.