ZIP - convenience methods

Continuous Integration

Quick Overview

The project was started and coded by Rein Raudjärv when he needed to process a large set of large ZIP archives for LiveRebel internals. Soon after we started using the utility in other projects because of the ease of use and it just worked.

The project is built using java.util.zip.* packages for stream based access. Most convenience methods for filesystem usage is also supported.

Installation

The project artifacts are available in Maven Central Repository. To include it in your maven project then you have to specify the dependency.

...
<dependency>
    <groupId>org.zeroturnaround</groupId>
    <artifactId>zt-zip</artifactId>
    <version>1.14</version>
    <type>jar</type>
</dependency>
...

Notice that 1.8 is the last Java 1.4 compatible release. Since then Java 1.5 is required.

If you are using with ProGuard, please add the following configuration

-dontwarn org.slf4j.**

Background

We had the following functional requirements:

1. pack and unpack directories recursively
2. include/exclude entries
3. rename entries
4. packing/unpacking in place - ZIP becomes directory and vice versa
5. iterate through ZIP entries
6. add or replace entries from files or byte arrays
7. transform ZIP entries
8. compare two archives - compare all entries ignoring time stamps

and these non-functional requirements:

1. use existing APIs as much as possible
2. be simple to use
3. be effective to use - do not traverse an entire ZIP file if only a single entry is needed
4. be safe to use - do not enable user to leave streams open and keep files locked
5. do not declare exceptions
6. be compatible with Java 1.5

Examples

The examples don't include all the possible ways how to use the library but will give an overview. When you see a method that is useful but doesn't necessarily solve your use case then just head over to ZipUtil.class file and see the sibling methods that are named the same but arguments might be different.

Unpacking

Check if an entry exists in a ZIP archive

boolean exists = ZipUtil.containsEntry(new File("/tmp/demo.zip"), "foo.txt");

Extract an entry from a ZIP archive into a byte array

byte[] bytes = ZipUtil.unpackEntry(new File("/tmp/demo.zip"), "foo.txt");

Extract an entry from a ZIP archive with a specific Charset into a byte array

byte[] bytes = ZipUtil.unpackEntry(new File("/tmp/demo.zip"), "foo.txt", Charset.forName("IBM437"));

Extract an entry from a ZIP archive into file system

ZipUtil.unpackEntry(new File("/tmp/demo.zip"), "foo.txt", new File("/tmp/bar.txt"));

Extract a ZIP archive

ZipUtil.unpack(new File("/tmp/demo.zip"), new File("/tmp/demo"));

Extract a ZIP archive which becomes a directory

ZipUtil.explode(new File("/tmp/demo.zip"));

Extract a directory from a ZIP archive including the directory name

ZipUtil.unpack(new File("/tmp/demo.zip"), new File("/tmp/demo"), new NameMapper() {
  public String map(String name) {
    return name.startsWith("doc/") ? name : null;
  }
});

Extract a directory from a ZIP archive excluding the directory name

final String prefix = "doc/"; 
ZipUtil.unpack(new File("/tmp/demo.zip"), new File("/tmp/demo"), new NameMapper() {
  public String map(String name) {
    return name.startsWith(prefix) ? name.substring(prefix.length()) : name;
  }
});

Extract files from a ZIP archive that match a name pattern

ZipUtil.unpack(new File("/tmp/demo.zip"), new File("/tmp/demo"), new NameMapper() {
  public String map(String name) {
    if (name.contains("/doc")) {
      return name;
    }
    else {
      // returning null from the map method will disregard the entry
      return null;
    }
  }
});

Print .class entry names in a ZIP archive

ZipUtil.iterate(new File("/tmp/demo.zip"), new ZipInfoCallback() {
  public void process(ZipEntry zipEntry) throws IOException {
    if (zipEntry.getName().endsWith(".class"))
      System.out.println("Found " + zipEntry.getName());
  }
});

Print .txt entries in a ZIP archive (uses IoUtils from Commons IO)

ZipUtil.iterate(new File("/tmp/demo.zip"), new ZipEntryCallback() {
  public void process(InputStream in, ZipEntry zipEntry) throws IOException {
    if (zipEntry.getName().endsWith(".txt")) {
      System.out.println("Found " + zipEntry.getName());
      IOUtils.copy(in, System.out);
    }
  }
});

Packing

Compress a directory into a ZIP archive

ZipUtil.pack(new File("/tmp/demo"), new File("/tmp/demo.zip"));

Compress a directory which becomes a ZIP archive

ZipUtil.unexplode(new File("/tmp/demo.zip"));

Compress a directory into a ZIP archive with a parent directory

ZipUtil.pack(new File("/tmp/demo"), new File("/tmp/demo.zip"), new NameMapper() {
  public String map(String name) {
    return "foo/" + name;
  }
});

Compress a file into a ZIP archive

ZipUtil.packEntry(new File("/tmp/demo.txt"), new File("/tmp/demo.zip"));

Add an entry from file to a ZIP archive

ZipUtil.addEntry(new File("/tmp/demo.zip"), "doc/readme.txt", new File("f/tmp/oo.txt"), new File("/tmp/new.zip"));

Add an entry from byte array to a ZIP archive

ZipUtil.addEntry(new File("/tmp/demo.zip"), "doc/readme.txt", "bar".getBytes(), new File("/tmp/new.zip"));

Add an entry from file and from byte array to a ZIP archive

ZipEntrySource[] entries = new ZipEntrySource[] {
    new FileSource("doc/readme.txt", new File("foo.txt")),
    new ByteSource("sample.txt", "bar".getBytes())
};
ZipUtil.addEntries(new File("/tmp/demo.zip"), entries, new File("/tmp/new.zip"));

Add an entry from file and from byte array to a output stream

ZipEntrySource[] entries = new ZipEntrySource[] {
    new FileSource("doc/readme.txt", new File("foo.txt")),
    new ByteSource("sample.txt", "bar".getBytes())
};
OutputStream out = null;
try {
  out = new BufferedOutputStream(new FileOutputStream(new File("/tmp/new.zip")));
  ZipUtil.addEntries(new File("/tmp/demo.zip"), entries, out);
}
finally {
  IOUtils.closeQuietly(out);
}

Replace a ZIP archive entry from file

boolean replaced = ZipUtil.replaceEntry(new File("/tmp/demo.zip"), "doc/readme.txt", new File("/tmp/foo.txt"), new File("/tmp/new.zip"));

Replace a ZIP archive entry from byte array

boolean replaced = ZipUtil.replaceEntry(new File("/tmp/demo.zip"), "doc/readme.txt", "bar".getBytes(), new File("/tmp/new.zip"));

Replace a ZIP archive entry from file and byte array

ZipEntrySource[] entries = new ZipEntrySource[] {
    new FileSource("doc/readme.txt", new File("foo.txt")),
    new ByteSource("sample.txt", "bar".getBytes())
};
boolean replaced = ZipUtil.replaceEntries(new File("/tmp/demo.zip"), entries, new File("/tmp/new.zip"));

Add or replace entries in a ZIP archive

ZipEntrySource[] addedEntries = new ZipEntrySource[] {
        new FileSource("/path/in/zip/File1.txt", new File("/tmp/file1.txt")),
        new FileSource("/path/in/zip/File2.txt", new File("/tmp/file2.txt")),
        new FileSource("/path/in/zip/File3.txt", new File("/tmp/file2.txt")),
    };
ZipUtil.addOrReplaceEntries(new File("/tmp/demo.zip"), addedEntries);

Transforming

Transform a ZIP archive entry into uppercase

boolean transformed = ZipUtil.transformEntry(new File("/tmp/demo"), "sample.txt", new StringZipEntryTransformer() {
    protected String transform(ZipEntry zipEntry, String input) throws IOException {
        return input.toUpperCase();
    }
}, new File("/tmp/demo.zip"));

Comparison

Compare two ZIP archives (ignoring timestamps of the entries)

boolean equals = ZipUtil.archiveEquals(new File("/tmp/demo1.zip"), new File("/tmp/demo2.zip"));

Compare two ZIP archive entries with same name (ignoring timestamps of the entries)

boolean equals = ZipUtil.entryEquals(new File("/tmp/demo1.zip"), new File("/tmp/demo2.zip"), "foo.txt");

Compare two ZIP archive entries with different names (ignoring timestamps of the entries)

boolean equals = ZipUtil.entryEquals(new File("/tmp/demo1.zip"), new File("/tmp/demo2.zip"), "foo1.txt", "foo2.txt");

Progress bar

There have been multiple requests for a progress bar. See ZT Zip Progress Bar for a sample implementation.

Debugging

The library is using the slf4j-api logging framework. All the log statements are either DEBUG or TRACE level. Depending on the logging framework you are using a simple -Dorg.slf4j.simpleLogger.defaultLogLevel=debug or System.setProperty("org.slf4j.simpleLogger.defaultLogLevel", "debug"); will do the trick of showing log statements from the zt-zip library. You can further fine tune the levels and inclusion of log messages per package with your logging framework.