Class ByteSource

java.lang.Object
cloud.opencode.base.io.source.ByteSource
public abstract class ByteSource extends Object
Abstract Byte Source - A readable source of bytes 抽象字节源 - 可读的字节来源

An abstraction over different sources of byte data. Each instance represents an immutable source that can be read multiple times.

对不同字节数据源的抽象。每个实例代表一个可以多次读取的不可变源。

Features | 主要功能:

  • Unified byte reading - 统一的字节读取
  • Copy to OutputStream - 复制到输出流
  • Content equality checks - 内容相等性检查
  • Size estimation - 大小估算
  • Hash computation - 哈希计算

Usage Examples | 使用示例:

// From file
ByteSource source = ByteSource.fromPath(Paths.get("data.bin"));
byte[] data = source.read();

// From URL
ByteSource urlSource = ByteSource.fromUrl(new URL("https://example.com/data"));
urlSource.copyTo(outputStream);

// From byte array
ByteSource memSource = ByteSource.wrap(new byte[]{1, 2, 3});
long size = memSource.size();

Security | 安全性:

  • Thread-safe: Yes (immutable source, each read opens new stream) - 线程安全: 是（不可变源，每次读取打开新流）
  • Null-safe: No, arguments must not be null - 空值安全: 否，参数不可为null
Since:
JDK 25, opencode-base-io V1.2.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • ByteSource

      public ByteSource()

  • Method Details

    • openStream

      public abstract InputStream openStream()
      Opens a new InputStream for reading. 打开新的输入流进行读取。

      The caller is responsible for closing the stream.

      调用者负责关闭流。

      Returns:
      a new InputStream | 新的输入流
      Throws:
      OpenIOOperationException - if the stream cannot be opened | 如果流无法打开

    • asCharSource

      public CharSource asCharSource(Charset charset)
      Returns a view of the contents as a CharSource with the given charset. 返回使用给定字符集作为CharSource的内容视图。
      Parameters:
      charset - the charset to use | 要使用的字符集
      Returns:
      a CharSource view | CharSource视图

    • asCharSource

      public CharSource asCharSource()
      Returns a view of the contents as a CharSource with UTF-8 charset. 返回使用UTF-8字符集作为CharSource的内容视图。
      Returns:
      a CharSource view | CharSource视图

    • sizeIfKnown

      public Optional<Long> sizeIfKnown()
      Returns the size of this source in bytes, if known. 返回此源的字节大小（如果已知）。
      Returns:
      an Optional containing the size, or empty if unknown | 包含大小的Optional，如果未知则为空

    • size

      public long size()
      Returns the size of this source in bytes. 返回此源的字节大小。

      If the size is not known, this method reads the entire source.

      如果大小未知，此方法会读取整个源。

      Returns:
      the size in bytes | 字节大小
      Throws:
      OpenIOOperationException - if reading fails | 如果读取失败

    • read

      public byte[] read()
      Reads the entire contents as a byte array. 将整个内容读取为字节数组。
      Returns:
      the byte array | 字节数组
      Throws:
      OpenIOOperationException - if reading fails | 如果读取失败

    • copyTo

      public long copyTo(OutputStream output)
      Copies the contents to an OutputStream. 将内容复制到输出流。
      Parameters:
      output - the target OutputStream | 目标输出流
      Returns:
      the number of bytes copied | 复制的字节数
      Throws:
      OpenIOOperationException - if copying fails | 如果复制失败

    • copyTo

      public long copyTo(ByteSink sink)
      Copies the contents to a ByteSink. 将内容复制到ByteSink。
      Parameters:
      sink - the target ByteSink | 目标ByteSink
      Returns:
      the number of bytes copied | 复制的字节数
      Throws:
      OpenIOOperationException - if copying fails | 如果复制失败

    • contentEquals

      public boolean contentEquals(ByteSource other)
      Checks if this source has the same content as another. 检查此源是否与另一个源具有相同的内容。
      Parameters:
      other - the other ByteSource | 另一个ByteSource
      Returns:
      true if contents are equal | 如果内容相等返回true
      Throws:
      OpenIOOperationException - if reading fails | 如果读取失败

    • isEmpty

      public boolean isEmpty()
      Checks if the source is empty. 检查源是否为空。
      Returns:
      true if empty | 如果为空返回true
      Throws:
      OpenIOOperationException - if reading fails | 如果读取失败

    • hash

      public byte[] hash(String algorithm)
      Computes the hash of the contents using the specified algorithm. 使用指定算法计算内容的哈希值。
      Parameters:
      algorithm - the hash algorithm (e.g., "SHA-256", "MD5") | 哈希算法
      Returns:
      the hash bytes | 哈希字节
      Throws:
      OpenIOOperationException - if hashing fails | 如果哈希失败

    • slice

      public ByteSource slice(long offset, long length)
      Returns a ByteSource that returns a slice of this source. 返回此源的一个切片的ByteSource。
      Parameters:
      offset - the starting offset | 起始偏移量
      length - the maximum length | 最大长度
      Returns:
      a sliced ByteSource | 切片后的ByteSource

    • concat

      public static ByteSource concat(ByteSource... sources)
      Returns a concatenated ByteSource. 返回连接后的ByteSource。
      Parameters:
      sources - the sources to concatenate | 要连接的源
      Returns:
      a concatenated ByteSource | 连接后的ByteSource

    • concat

      public static ByteSource concat(Iterable<? extends ByteSource> sources)
      Returns a concatenated ByteSource. 返回连接后的ByteSource。
      Parameters:
      sources - the sources to concatenate | 要连接的源
      Returns:
      a concatenated ByteSource | 连接后的ByteSource

    • wrap

      public static ByteSource wrap(byte[] bytes)
      Creates a ByteSource from a byte array. 从字节数组创建ByteSource。
      Parameters:
      bytes - the byte array | 字节数组
      Returns:
      a ByteSource | ByteSource

    • empty

      public static ByteSource empty()
      Creates an empty ByteSource. 创建空的ByteSource。
      Returns:
      an empty ByteSource | 空的ByteSource

    • fromPath

      public static ByteSource fromPath(Path path)
      Creates a ByteSource from a file path. 从文件路径创建ByteSource。
      Parameters:
      path - the file path | 文件路径
      Returns:
      a ByteSource | ByteSource

    • fromUrl

      public static ByteSource fromUrl(URL url)
      Creates a ByteSource from a URL. 从URL创建ByteSource。
      Parameters:
      url - the URL | URL
      Returns:
      a ByteSource | ByteSource

    • fromResource

      public static ByteSource fromResource(String resourcePath)
      Creates a ByteSource from a classpath resource. 从类路径资源创建ByteSource。
      Parameters:
      resourcePath - the resource path | 资源路径
      Returns:
      a ByteSource | ByteSource

    • fromResource

      public static ByteSource fromResource(String resourcePath, ClassLoader classLoader)
      Creates a ByteSource from a classpath resource. 从类路径资源创建ByteSource。
      Parameters:
      resourcePath - the resource path | 资源路径
      classLoader - the class loader | 类加载器
      Returns:
      a ByteSource | ByteSource