java.lang.Object

cloud.opencode.base.io.compress.ZipUtil

public final class ZipUtil extends Object

Zip Archive Utility Zip归档工具类

Provides static utility methods for creating, extracting, and inspecting Zip archives. Includes security protections against zip bombs and path traversal attacks.

提供创建、提取和检查Zip归档的静态工具方法。包含针对zip炸弹和路径穿越攻击的安全保护。

Features | 主要功能:

Zip files and directories - 压缩文件和目录
Extract zip archives safely - 安全提取zip归档
List and read individual entries - 列出和读取单个条目
Fluent builder API for complex archives - 复杂归档的流式构建器API
Path traversal protection - 路径穿越防护
Zip bomb protection - Zip炸弹防护

Usage Examples | 使用示例:

// Zip a directory
ZipUtil.zip(sourceDir, targetZip);

// Unzip safely
ZipUtil.unzip(zipFile, outputDir);

// List entries
List<ZipEntryInfo> entries = ZipUtil.list(zipFile);

// Builder API
ZipUtil.builder()
    .addFile(path1)
    .addString("note.txt", "hello")
    .writeTo(outputZip);

Security | 安全性:

Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
Path traversal: Blocked - 路径穿越: 已阻止
Zip bomb: Size and entry count limits - Zip炸弹: 大小和条目数限制

Since:

JDK 25, opencode-base-io V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final int

MAX_ENTRIES

Maximum number of entries allowed in a zip archive Zip归档中允许的最大条目数

static final int

MAX_ENTRY_NAME_LENGTH

Maximum entry name length allowed 允许的最大条目名长度

static final long

MAX_UNCOMPRESSED_SIZE

Maximum total uncompressed size allowed (4GB) 允许的最大总未压缩大小（4GB）
Method Summary

Modifier and Type

Method

Description

static ZipBuilder

builder()

Creates a new fluent builder for assembling a zip archive 创建一个新的流式构建器用于组装zip归档

static boolean

containsEntry(Path zipFile, String entryName)

Checks whether a zip archive contains an entry with the given name 检查zip归档中是否包含给定名称的条目

static List<ZipEntryInfo>

list(Path zipFile)

Lists all entries in a zip archive 列出zip归档中的所有条目

static byte[]

readEntry(Path zipFile, String entryName)

Reads a single entry from a zip archive 从zip归档中读取单个条目

static byte[]

readEntry(Path zipFile, String entryName, long maxSize)

Reads a single entry from a zip archive with a size limit 从zip归档中读取单个条目（带大小限制）

static void

unzip(Path zipFile, Path targetDir)

Extracts a zip archive to the target directory with security checks 使用安全检查将zip归档提取到目标目录

static void

zip(Path source, Path target)

Zips a single file or directory to the target zip file 将单个文件或目录压缩到目标zip文件

static void

zip(Collection<Path> sources, Path target)

Zips multiple files to the target zip file 将多个文件压缩到目标zip文件

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- MAX_ENTRIES
  public static final int MAX_ENTRIES
  
  Maximum number of entries allowed in a zip archive Zip归档中允许的最大条目数
  
  See Also:
  
  Constant Field Values
- MAX_UNCOMPRESSED_SIZE
  public static final long MAX_UNCOMPRESSED_SIZE
  
  Maximum total uncompressed size allowed (4GB) 允许的最大总未压缩大小（4GB）
  
  See Also:
  
  Constant Field Values
- MAX_ENTRY_NAME_LENGTH
  public static final int MAX_ENTRY_NAME_LENGTH
  
  Maximum entry name length allowed 允许的最大条目名长度
  
  See Also:
  
  Constant Field Values
Method Details
- zip
  
  public static void zip(Path source, Path target)
  
  Zips a single file or directory to the target zip file 将单个文件或目录压缩到目标zip文件
  If source is a directory, its contents are added recursively.
  
  如果源是目录，则递归添加其内容。
  
  Parameters:
  
  source - the source file or directory | 源文件或目录
  
  target - the target zip file path | 目标zip文件路径
  
  Throws:
  
  NullPointerException - if source or target is null | 当source或target为null时抛出
  
  OpenIOOperationException - if zipping fails | 当压缩失败时抛出
- zip
  
  public static void zip(Collection<Path> sources, Path target)
  
  Zips multiple files to the target zip file 将多个文件压缩到目标zip文件
  
  Parameters:
  
  sources - the source files | 源文件集合
  
  target - the target zip file path | 目标zip文件路径
  
  Throws:
  
  NullPointerException - if sources or target is null | 当sources或target为null时抛出
  
  OpenIOOperationException - if zipping fails | 当压缩失败时抛出
- unzip
  public static void unzip(Path zipFile, Path targetDir)
  
  Extracts a zip archive to the target directory with security checks 使用安全检查将zip归档提取到目标目录
  Security protections applied:
  
  Path traversal detection (rejects entries containing "..")
  
  Resolved path must be within target directory
  
  Total uncompressed size limited to MAX_UNCOMPRESSED_SIZE
  
  Entry count limited to MAX_ENTRIES
  
  Entry name length limited to MAX_ENTRY_NAME_LENGTH
  
  Parameters:
  
  zipFile - the zip file to extract | 要提取的zip文件
  
  targetDir - the target directory | 目标目录
  
  Throws:
  
  NullPointerException - if zipFile or targetDir is null | 当zipFile或targetDir为null时抛出
  
  OpenIOOperationException - if extraction fails or security check fails | 当提取失败或安全检查失败时抛出
- list
  
  public static List<ZipEntryInfo> list(Path zipFile)
  
  Lists all entries in a zip archive 列出zip归档中的所有条目
  
  Parameters:
  
  zipFile - the zip file path | zip文件路径
  
  Returns:
  
  list of entry metadata | 条目元数据列表
  
  Throws:
  
  NullPointerException - if zipFile is null | 当zipFile为null时抛出
  
  OpenIOOperationException - if reading fails | 当读取失败时抛出
- readEntry
  
  public static byte[] readEntry(Path zipFile, String entryName)
  
  Reads a single entry from a zip archive 从zip归档中读取单个条目
  
  Parameters:
  
  zipFile - the zip file path | zip文件路径
  
  entryName - the entry name to read | 要读取的条目名
  
  Returns:
  
  the entry data | 条目数据
  
  Throws:
  
  NullPointerException - if zipFile or entryName is null | 当zipFile或entryName为null时抛出
  
  OpenIOOperationException - if entry not found or reading fails | 当条目未找到或读取失败时抛出
- readEntry
  
  public static byte[] readEntry(Path zipFile, String entryName, long maxSize)
  
  Reads a single entry from a zip archive with a size limit 从zip归档中读取单个条目（带大小限制）
  
  Parameters:
  
  zipFile - the zip file path | zip文件路径
  
  entryName - the entry name to read | 要读取的条目名
  
  maxSize - the maximum entry size in bytes | 最大条目大小（字节）
  
  Returns:
  
  the entry data | 条目数据
  
  Throws:
  
  NullPointerException - if zipFile or entryName is null | 当zipFile或entryName为null时抛出
  
  IllegalArgumentException - if maxSize is not positive | 当maxSize非正数时抛出
  
  OpenIOOperationException - if entry not found, reading fails, or size limit exceeded | 当条目未找到、读取失败或超出大小限制时抛出
- containsEntry
  
  public static boolean containsEntry(Path zipFile, String entryName)
  
  Checks whether a zip archive contains an entry with the given name 检查zip归档中是否包含给定名称的条目
  
  Parameters:
  
  zipFile - the zip file path | zip文件路径
  
  entryName - the entry name to check | 要检查的条目名
  
  Returns:
  
  true if the entry exists | 如果条目存在返回true
  
  Throws:
  
  NullPointerException - if zipFile or entryName is null | 当zipFile或entryName为null时抛出
  
  OpenIOOperationException - if reading the zip fails | 当读取zip失败时抛出
- builder
  
  public static ZipBuilder builder()
  
  Creates a new fluent builder for assembling a zip archive 创建一个新的流式构建器用于组装zip归档
  
  Returns:
  
  a new ZipBuilder | 新的ZipBuilder

Class ZipUtil

Field Summary

Method Summary

Methods inherited from class Object

Field Details

MAX_ENTRIES

MAX_UNCOMPRESSED_SIZE

MAX_ENTRY_NAME_LENGTH

Method Details

zip

zip

unzip

list

readEntry

readEntry

containsEntry

builder