Class FileBackedOutputStream

java.lang.Object
java.io.OutputStream
cloud.opencode.base.io.stream.FileBackedOutputStream
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable
public class FileBackedOutputStream extends OutputStream
File-Backed Output Stream 文件后备输出流

An OutputStream that starts writing to an in-memory buffer and automatically spills to a temporary file when a configurable byte threshold is exceeded. This is useful for processing data of unknown size without risking OutOfMemoryError for large inputs.

一个先向内存缓冲区写入数据的输出流，当超过可配置的字节阈值时自动溢出到临时文件。 这对于处理大小未知的数据非常有用，可以避免大输入导致的OutOfMemoryError。

Features | 主要功能:

  • Automatic memory-to-disk spillover - 自动内存到磁盘溢出
  • Configurable byte threshold - 可配置的字节阈值
  • Custom temporary directory support - 支持自定义临时目录
  • Read-back via getInputStream() - 通过getInputStream()回读数据
  • Automatic temp file cleanup on close/reset - 关闭/重置时自动清理临时文件

Usage Examples | 使用示例:

// Write data that may exceed memory threshold
try (FileBackedOutputStream out = new FileBackedOutputStream(1024 * 1024)) {
    out.write(largeData);
    InputStream in = out.getInputStream();
    // process the data from input stream
}

Security | 安全性:

  • Thread-safe: No (single-writer) - 线程安全: 否（单写入者）
  • Temp files are deleted on close/reset - 关闭/重置时删除临时文件
Since:
JDK 25, opencode-base-io V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    FileBackedOutputStream(int threshold)
    Creates a file-backed output stream with default temp directory 创建使用默认临时目录的文件后备输出流
    FileBackedOutputStream(int threshold, Path tempDir)
    Creates a file-backed output stream with custom temp directory 创建使用自定义临时目录的文件后备输出流

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
     
    void
    flush()
     
    Path
    getFile()
    Returns the temp file path, or null if data is in memory 返回临时文件路径，如果数据在内存中则返回null
    InputStream
    getInputStream()
    Returns an InputStream to read all written data 返回用于读取所有已写入数据的InputStream
    boolean
    isInMemory()
    Checks whether data is still in memory 检查数据是否仍在内存中
    void
    reset()
    Resets the stream, clearing all data and deleting temp file if exists 重置流，清除所有数据并删除临时文件（如果存在）
    long
    size()
    Returns the total number of bytes written 返回已写入的总字节数
    void
    write(byte[] b, int off, int len)
     
    void
    write(int b)
     

    Methods inherited from class OutputStream

    nullOutputStream, write

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • FileBackedOutputStream

      public FileBackedOutputStream(int threshold)
      Creates a file-backed output stream with default temp directory 创建使用默认临时目录的文件后备输出流
      Parameters:
      threshold - the byte threshold before spilling to disk | 溢出到磁盘前的字节阈值
      Throws:
      IllegalArgumentException - if threshold is not positive | 当阈值非正数时抛出

    • FileBackedOutputStream

      public FileBackedOutputStream(int threshold, Path tempDir)
      Creates a file-backed output stream with custom temp directory 创建使用自定义临时目录的文件后备输出流
      Parameters:
      threshold - the byte threshold before spilling to disk | 溢出到磁盘前的字节阈值
      tempDir - the directory for temp files, or null for system default | 临时文件目录，null使用系统默认
      Throws:
      IllegalArgumentException - if threshold is not positive | 当阈值非正数时抛出

  • Method Details

    • write

      public void write(int b) throws IOException
      Specified by:
      write in class OutputStream
      Throws:
      IOException

    • write

      public void write(byte[] b, int off, int len) throws IOException
      Overrides:
      write in class OutputStream
      Throws:
      IOException

    • flush

      public void flush() throws IOException
      Specified by:
      flush in interface Flushable
      Overrides:
      flush in class OutputStream
      Throws:
      IOException

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class OutputStream
      Throws:
      IOException

    • getInputStream

      public InputStream getInputStream()
      Returns an InputStream to read all written data 返回用于读取所有已写入数据的InputStream

      If data is in memory, returns a ByteArrayInputStream. If data has spilled to disk, flushes the file output stream and returns a FileInputStream.

      如果数据在内存中，返回ByteArrayInputStream。 如果数据已溢出到磁盘，刷新文件输出流并返回FileInputStream。

      After calling this method, no further writes should be performed. The returned InputStream must be closed by the caller. When data has spilled to disk, the temp file is deleted when this stream is closed (not when getInputStream()'s result is closed).

      调用此方法后，不应再进行写入操作。返回的InputStream必须由调用方关闭。 当数据已溢出到磁盘时，临时文件在此流关闭时删除。

      Returns:
      an InputStream over all written data | 包含所有已写入数据的InputStream
      Throws:
      OpenIOOperationException - if an IO error occurs | 当IO错误发生时抛出

    • isInMemory

      public boolean isInMemory()
      Checks whether data is still in memory 检查数据是否仍在内存中
      Returns:
      true if data is in memory, false if spilled to disk | 如果数据在内存中返回true，溢出到磁盘返回false

    • size

      public long size()
      Returns the total number of bytes written 返回已写入的总字节数
      Returns:
      total bytes written | 已写入的总字节数

    • getFile

      public Path getFile()
      Returns the temp file path, or null if data is in memory 返回临时文件路径，如果数据在内存中则返回null
      Returns:
      the temp file path, or null | 临时文件路径，或null

    • reset

      public void reset()
      Resets the stream, clearing all data and deleting temp file if exists 重置流，清除所有数据并删除临时文件（如果存在）

      After reset, the stream returns to memory mode and can accept new writes.

      重置后，流恢复为内存模式，可以接受新的写入。

      Throws:
      OpenIOOperationException - if temp file deletion fails | 当临时文件删除失败时抛出