java.lang.Object

cloud.opencode.base.io.compress.GzipUtil

public final class GzipUtil extends Object

Gzip Compression/Decompression Utility Gzip压缩/解压缩工具类

Provides static utility methods for compressing and decompressing data using the Gzip algorithm. Supports byte arrays, files, and streams.

提供使用Gzip算法压缩和解压缩数据的静态工具方法。支持字节数组、文件和流。

Features | 主要功能:

Byte array compression/decompression - 字节数组压缩/解压缩
File compression/decompression - 文件压缩/解压缩
Stream-based compression/decompression - 基于流的压缩/解压缩
Gzip format detection - Gzip格式检测

Usage Examples | 使用示例:

// Compress byte array
byte[] compressed = GzipUtil.compress(data);
byte[] original = GzipUtil.decompress(compressed);

// Compress file
GzipUtil.compress(sourcePath, targetPath);
GzipUtil.decompress(gzipPath, outputPath);

// Check if data is gzipped
boolean isGzip = GzipUtil.isGzipped(data);

Security | 安全性:

Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
Null-safe: Yes, null inputs throw NullPointerException - 空值安全: 是，null输入抛出NullPointerException

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 long

DEFAULT_MAX_DECOMPRESSED_SIZE

Default maximum decompressed size (256 MB) to guard against gzip bombs 默认最大解压大小（256 MB），防止gzip炸弹
Method Summary

Modifier and Type

Method

Description

static byte[]

compress(byte[] data)

Compresses a byte array using Gzip 使用Gzip压缩字节数组

static byte[]

compress(InputStream input)

Compresses data from an InputStream using Gzip 使用Gzip压缩输入流中的数据

static void

compress(Path source, Path target)

Compresses a file using Gzip 使用Gzip压缩文件

static InputStream

compressStream(InputStream input)

Returns a compressed InputStream that wraps the given input 返回一个包装给定输入的压缩InputStream

static byte[]

decompress(byte[] data)

Decompresses a Gzip-compressed byte array 解压缩Gzip压缩的字节数组

static byte[]

decompress(byte[] data, long maxSize)

Decompresses a Gzip-compressed byte array with a size limit 带大小限制解压缩Gzip压缩的字节数组

static byte[]

decompress(InputStream input)

Decompresses data from a Gzip-compressed InputStream 从Gzip压缩的输入流中解压缩数据

static byte[]

decompress(InputStream input, long maxSize)

Decompresses data from a Gzip-compressed InputStream with a size limit 带大小限制从Gzip压缩的输入流中解压缩数据

static void

decompress(Path source, Path target)

Decompresses a Gzip file 解压缩Gzip文件

static void

decompress(Path source, Path target, long maxSize)

Decompresses a Gzip file with a size limit 带大小限制解压缩Gzip文件

static InputStream

decompressStream(InputStream input)

Returns a decompressed InputStream that wraps the given compressed input, with the default DEFAULT_MAX_DECOMPRESSED_SIZE cap on output bytes.

static InputStream

decompressStream(InputStream input, long maxDecompressedSize)

Returns a decompressed InputStream that wraps the given compressed input with an explicit size cap on the decompressed output.

static boolean

isGzipped(byte[] data)

Checks if the given byte array starts with Gzip magic bytes 检查给定的字节数组是否以Gzip魔数开头

static boolean

isGzipped(Path path)

Checks if the file at the given path starts with Gzip magic bytes 检查给定路径的文件是否以Gzip魔数开头

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

Field Details
- DEFAULT_MAX_DECOMPRESSED_SIZE
  public static final long DEFAULT_MAX_DECOMPRESSED_SIZE
  
  Default maximum decompressed size (256 MB) to guard against gzip bombs 默认最大解压大小（256 MB），防止gzip炸弹
  
  See Also:
  
  Constant Field Values
Method Details
- compress
  
  public static byte[] compress(byte[] data)
  
  Compresses a byte array using Gzip 使用Gzip压缩字节数组
  
  Parameters:
  
  data - the data to compress | 要压缩的数据
  
  Returns:
  
  compressed data | 压缩后的数据
  
  Throws:
  
  NullPointerException - if data is null | 当data为null时抛出
  
  OpenIOOperationException - if compression fails | 当压缩失败时抛出
- compress
  
  public static void compress(Path source, Path target)
  
  Compresses a file using Gzip 使用Gzip压缩文件
  
  Parameters:
  
  source - the source file path | 源文件路径
  
  target - the target file path | 目标文件路径
  
  Throws:
  
  NullPointerException - if source or target is null | 当source或target为null时抛出
  
  OpenIOOperationException - if compression fails | 当压缩失败时抛出
- compress
  
  public static byte[] compress(InputStream input)
  
  Compresses data from an InputStream using Gzip 使用Gzip压缩输入流中的数据
  
  Parameters:
  
  input - the input stream to compress | 要压缩的输入流
  
  Returns:
  
  compressed data | 压缩后的数据
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  OpenIOOperationException - if compression fails | 当压缩失败时抛出
- decompress
  
  public static byte[] decompress(byte[] data)
  
  Decompresses a Gzip-compressed byte array 解压缩Gzip压缩的字节数组
  
  Parameters:
  
  data - the compressed data | 压缩的数据
  
  Returns:
  
  decompressed data | 解压缩后的数据
  
  Throws:
  
  NullPointerException - if data is null | 当data为null时抛出
  
  OpenIOOperationException - if decompression fails | 当解压缩失败时抛出
- decompress
  
  public static byte[] decompress(byte[] data, long maxSize)
  
  Decompresses a Gzip-compressed byte array with a size limit 带大小限制解压缩Gzip压缩的字节数组
  
  Parameters:
  
  data - the compressed data | 压缩的数据
  
  maxSize - the maximum decompressed size in bytes | 最大解压大小（字节）
  
  Returns:
  
  decompressed data | 解压缩后的数据
  
  Throws:
  
  NullPointerException - if data is null | 当data为null时抛出
  
  IllegalArgumentException - if maxSize is not positive | 当maxSize非正数时抛出
  
  OpenIOOperationException - if decompression fails or size limit exceeded | 当解压缩失败或超出大小限制时抛出
- decompress
  
  public static void decompress(Path source, Path target)
  
  Decompresses a Gzip file 解压缩Gzip文件
  
  Parameters:
  
  source - the Gzip file path | Gzip文件路径
  
  target - the target file path | 目标文件路径
  
  Throws:
  
  NullPointerException - if source or target is null | 当source或target为null时抛出
  
  OpenIOOperationException - if decompression fails | 当解压缩失败时抛出
- decompress
  
  public static void decompress(Path source, Path target, long maxSize)
  
  Decompresses a Gzip file with a size limit 带大小限制解压缩Gzip文件
  
  Parameters:
  
  source - the Gzip file path | Gzip文件路径
  
  target - the target file path | 目标文件路径
  
  maxSize - the maximum decompressed size in bytes | 最大解压大小（字节）
  
  Throws:
  
  NullPointerException - if source or target is null | 当source或target为null时抛出
  
  IllegalArgumentException - if maxSize is not positive | 当maxSize非正数时抛出
  
  OpenIOOperationException - if decompression fails or size limit exceeded | 当解压缩失败或超出大小限制时抛出
- decompress
  
  public static byte[] decompress(InputStream input)
  
  Decompresses data from a Gzip-compressed InputStream 从Gzip压缩的输入流中解压缩数据
  
  Parameters:
  
  input - the compressed input stream | 压缩的输入流
  
  Returns:
  
  decompressed data | 解压缩后的数据
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  OpenIOOperationException - if decompression fails | 当解压缩失败时抛出
- decompress
  
  public static byte[] decompress(InputStream input, long maxSize)
  
  Decompresses data from a Gzip-compressed InputStream with a size limit 带大小限制从Gzip压缩的输入流中解压缩数据
  
  Parameters:
  
  input - the compressed input stream | 压缩的输入流
  
  maxSize - the maximum decompressed size in bytes | 最大解压大小（字节）
  
  Returns:
  
  decompressed data | 解压缩后的数据
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  IllegalArgumentException - if maxSize is not positive | 当maxSize非正数时抛出
  
  OpenIOOperationException - if decompression fails or size limit exceeded | 当解压缩失败或超出大小限制时抛出
- compressStream
  
  public static InputStream compressStream(InputStream input)
  
  Returns a compressed InputStream that wraps the given input 返回一个包装给定输入的压缩InputStream
  The returned stream contains gzip-compressed data read from the input. The input data is compressed in memory for simplicity and safety.
  
  返回的流包含从输入读取的gzip压缩数据。为了简便和安全，输入数据在内存中压缩。
  
  Parameters:
  
  input - the input stream to compress | 要压缩的输入流
  
  Returns:
  
  an InputStream of compressed data | 压缩数据的InputStream
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  OpenIOOperationException - if compression fails | 当压缩失败时抛出
- decompressStream
  
  public static InputStream decompressStream(InputStream input)
  
  Returns a decompressed InputStream that wraps the given compressed input, with the default DEFAULT_MAX_DECOMPRESSED_SIZE cap on output bytes. 返回一个包装给定压缩输入的解压缩 InputStream，输出字节按默认 DEFAULT_MAX_DECOMPRESSED_SIZE 上限。
  
  Parameters:
  
  input - the compressed input stream | 压缩的输入流
  
  Returns:
  
  an InputStream of decompressed data | 解压缩数据的 InputStream
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  OpenIOOperationException - if wrapping fails | 当包装失败时抛出
- decompressStream
  
  public static InputStream decompressStream(InputStream input, long maxDecompressedSize)
  
  Returns a decompressed InputStream that wraps the given compressed input with an explicit size cap on the decompressed output. 返回一个包装给定压缩输入的解压缩 InputStream，可显式指定解压输出的字节上限。
  V1.0.4 sec round-4 P1: pre-fix this method returned a raw GZIPInputStream with no size enforcement. A 1 KB gzip bomb decompressing to 1 GB would silently OOM any caller that consumed the stream via readAllBytes() or similar — gzip-bomb DoS. Now wraps the GZIPInputStream with a counting wrapper that throws OpenIOOperationException once maxDecompressedSize bytes are read.
  
  V1.0.4 sec round-4 P1：修复前本方法返回未受控的 GZIPInputStream。1 KB gzip bomb 解压成 1 GB 会让任何 readAllBytes() 类调用方 OOM —— gzip-bomb DoS。现用计数包装包住 GZIPInputStream，读到 maxDecompressedSize 字节即抛 OpenIOOperationException。
  
  Parameters:
  
  input - the compressed input stream | 压缩的输入流
  
  maxDecompressedSize - maximum decompressed bytes (must be positive) | 最大解压字节数（必须为正）
  
  Returns:
  
  an InputStream of decompressed data, capped at maxDecompressedSize | 上限为 maxDecompressedSize 的解压 InputStream
  
  Throws:
  
  NullPointerException - if input is null | 当input为null时抛出
  
  IllegalArgumentException - if maxDecompressedSize is not positive | 上限非正时抛出
  
  OpenIOOperationException - if wrapping fails | 当包装失败时抛出
  
  Since:
  
  opencode-base-io V1.0.4
- isGzipped
  
  public static boolean isGzipped(byte[] data)
  
  Checks if the given byte array starts with Gzip magic bytes 检查给定的字节数组是否以Gzip魔数开头
  
  Parameters:
  
  data - the data to check | 要检查的数据
  
  Returns:
  
  true if data is Gzip compressed | 如果数据是Gzip压缩的返回true
  
  Throws:
  
  NullPointerException - if data is null | 当data为null时抛出
- isGzipped
  
  public static boolean isGzipped(Path path)
  
  Checks if the file at the given path starts with Gzip magic bytes 检查给定路径的文件是否以Gzip魔数开头
  
  Parameters:
  
  path - the file path to check | 要检查的文件路径
  
  Returns:
  
  true if file is Gzip compressed | 如果文件是Gzip压缩的返回true
  
  Throws:
  
  NullPointerException - if path is null | 当path为null时抛出
  
  OpenIOOperationException - if reading the file fails | 当读取文件失败时抛出

Class GzipUtil

Field Summary

Method Summary

Methods inherited from class Object

Field Details

DEFAULT_MAX_DECOMPRESSED_SIZE

Method Details

compress

compress

compress

decompress

decompress

decompress

decompress

decompress

decompress

compressStream

decompressStream

decompressStream

isGzipped

isGzipped