Record Class ZipOptions

java.lang.Object
java.lang.Record
cloud.opencode.base.io.compress.ZipOptions
Record Components:
compressionLevel - compression level 0..9 | 压缩级别 0..9
password - encryption password, or null for none | 加密口令，null 不加密
encryption - encryption method | 加密方式
zip64 - whether to enable ZIP64 extensions | 是否启用 ZIP64
encoding - filename encoding (default "UTF-8") | 文件名编码（默认 "UTF-8"）
includeRootDir - include the root directory when compressing | 压缩时是否包含根目录
overwrite - overwrite policy during extraction | 解压覆盖策略
excludePatterns - glob patterns for files to exclude — each pattern is tested against BOTH the full entry path AND the file-name leaf to be lenient with simple "*.log" style. Callers wanting strict path matching (no leaf fallback) should use "**/*.log" explicitly. | 排除文件的 glob 模式 — 每个模式同时对完整条目路径与叶子文件名匹配， 兼容简单形式如 "*.log"；需要严格路径匹配（不走叶子兜底）时 请显式使用 "**/*.log"
bombProtection - anti-bomb threshold preset | 反炸弹阈值组
public record ZipOptions(int compressionLevel, String password, EncryptionMethod encryption, boolean zip64, String encoding, boolean includeRootDir, OverwritePolicy overwrite, List<String> excludePatterns, BombProtection bombProtection) extends Record
Configuration for ZIP compress and extract operations. ZIP 压缩与解压操作的配置。

Provides comprehensive control: compression level, password encryption, ZIP64, filename encoding, overwrite policy, file exclusion globs, and ZIP-bomb protection thresholds (grouped into a BombProtection nested record).

提供完整控制：压缩级别、密码加密、ZIP64、文件名编码、覆盖策略、文件排除 glob，以及 ZIP 炸弹防护阈值（聚合为 BombProtection 嵌套记录）。

Usage Examples | 使用示例:

// Defaults
ZipOptions opts = ZipOptions.defaults();

// Custom via builder — individual cap setters route to a builder-local BombProtection
ZipOptions opts = ZipOptions.builder()
        .compressionLevel(9)
        .password("secret")
        .encryption(EncryptionMethod.AES_256)
        .zip64(true)
        .maxCompressionRatio(200)        // routed into bombProtection
        .addExcludePattern("*.log")
        .build();

// Or pass a BombProtection preset directly
ZipOptions opts = ZipOptions.builder()
        .bombProtection(new BombProtection(20, 100L*1024*1024, 1000, 1, 50L*1024*1024))
        .build();

Security | 安全性:

  • Thread-safe: Yes (immutable record) - 线程安全：是（不可变记录）
  • Null-safe: Yes — null fields are normalised in canonical constructor — 空值安全：是，规范构造器将 null 字段归一化

Naming convention | 命名约定: boolean record components follow the canonical record style and are exposed as includeRootDir() / zip64() (no is prefix). Note that ZipEntryInfo.isDirectory() predates this record and uses the JavaBean is prefix — kept stable for binary compatibility with V1.0.3. 布尔字段访问器遵循记录习惯，不带 is 前缀（includeRootDir() / zip64()）。ZipEntryInfo.isDirectory() 早于本记录，沿用 JavaBean 风格的 is 前缀以与 V1.0.3 二进制兼容，故不一致是有意保留的。

Since:
JDK 25, opencode-base-io V1.0.4
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • ZipOptions

      public ZipOptions(int compressionLevel, String password, EncryptionMethod encryption, boolean zip64, String encoding, boolean includeRootDir, OverwritePolicy overwrite, List<String> excludePatterns, BombProtection bombProtection)
      Canonical constructor with normalisation and validation. 带归一化与校验的规范构造器。

  • Method Details

    • maxCompressionRatio

      public long maxCompressionRatio()
      Equivalent to bombProtection().maxCompressionRatio(). / 等价于 bombProtection().maxCompressionRatio()。
      Returns:
      max compression ratio | 最大压缩比

    • maxTotalSize

      public long maxTotalSize()
      Equivalent to bombProtection().maxTotalSize(). / 等价于 bombProtection().maxTotalSize()。
      Returns:
      max total decompressed bytes | 最大解压总字节

    • maxEntryCount

      public int maxEntryCount()
      Equivalent to bombProtection().maxEntryCount(). / 等价于 bombProtection().maxEntryCount()。
      Returns:
      max entry count | 最大条目数

    • maxNestingDepth

      public int maxNestingDepth()
      Equivalent to bombProtection().maxNestingDepth(). / 等价于 bombProtection().maxNestingDepth()。
      Returns:
      max nested-zip depth | 嵌套 ZIP 最大深度

    • maxSingleEntrySize

      public long maxSingleEntrySize()
      Equivalent to bombProtection().maxSingleEntrySize(). / 等价于 bombProtection().maxSingleEntrySize()。
      Returns:
      max single entry size | 单条目最大字节

    • toString

      public String toString()
      Returns a toString that redacts password(). The auto-generated record toString would otherwise print the password verbatim, leaking it into any debug log, exception-context dump, MDC, or telemetry that snapshots configuration objects. 返回会脱敏 password() 的 toString。否则记录自动生成的 toString 会原文打印口令，泄漏到调试日志、异常上下文、MDC 或快照配置对象的遥测中。
      Specified by:
      toString in class Record
      Returns:
      redacted string representation | 脱敏后的字符串表示

    • defaults

      public static ZipOptions defaults()
      Default options: level 6, no password, UTF-8, OVERWRITE, default BombProtection. 默认选项：级别 6，无密码，UTF-8，OVERWRITE，默认 BombProtection。
      Returns:
      default options | 默认选项

    • builder

      public static ZipOptions.Builder builder()
      Create a fluent builder. 创建流式 Builder。
      Returns:
      new builder | 新 Builder

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • compressionLevel

      public int compressionLevel()
      Returns the value of the compressionLevel record component.
      Returns:
      the value of the compressionLevel record component

    • password

      public String password()
      Returns the value of the password record component.
      Returns:
      the value of the password record component

    • encryption

      public EncryptionMethod encryption()
      Returns the value of the encryption record component.
      Returns:
      the value of the encryption record component

    • zip64

      public boolean zip64()
      Returns the value of the zip64 record component.
      Returns:
      the value of the zip64 record component

    • encoding

      public String encoding()
      Returns the value of the encoding record component.
      Returns:
      the value of the encoding record component

    • includeRootDir

      public boolean includeRootDir()
      Returns the value of the includeRootDir record component.
      Returns:
      the value of the includeRootDir record component

    • overwrite

      public OverwritePolicy overwrite()
      Returns the value of the overwrite record component.
      Returns:
      the value of the overwrite record component

    • excludePatterns

      public List<String> excludePatterns()
      Returns the value of the excludePatterns record component.
      Returns:
      the value of the excludePatterns record component

    • bombProtection

      public BombProtection bombProtection()
      Returns the value of the bombProtection record component.
      Returns:
      the value of the bombProtection record component