All Superinterfaces:: AutoCloseable

All Known Implementing Classes:: DefaultByteInput, NullByteInput

public interface ByteInput extends AutoCloseable

ByteInput

方法分为两大类, 动作方法/请求方法.

动作方法 read / readUpTo / readFully 以及相关的 peek, skip 镜像方法.
- 当 maxLength / length = 0 时, 我们将其看作一种无动作, 均采用统一策略, 立即返回, 不抛异常, 无关流的状态 (即使流以及结束).
- 在 maxLength / length > 0 时, 读取操作必须产生有效数据 (至少读取一个字节), 这样保证动作不会成为空操作并消除了 "0 字节读取歧义".
- EOF (流结束) 被设计为一种明确的信号, 当无法再读取任何字节时, 会抛出 NoMoreDataException. 这保证循环读取的安全性和逻辑自洽性. 同时消除了 EOF 表达性歧义.
- 严格契约保证用户可以安全循环读取, 同时明确何时流结束.
- 方法对读取的容忍度分成三个级别:
  - read(ByteConsumer,long) — 宽松 (可能少于指定长度)
  - readUpTo(ByteConsumer,long) — 中等 (尽量读取指定长度)
  - readFully(ByteConsumer,long) — 严格 (必须读取指定长度)
动作方法 indexOf.
- 空匹配模式的 indexOf 看作一种无动作 (因其事实上可以匹配任何数据), 恒返回 0.
请求方法 readAll / peekAll / skipAll.
- 和动作方法唯一的不同在于, 请求方法的调用者一般只关心结果而不是流的结束状态, 所以即使处于 EOF 状态也会宽松的返回空数组.

Version:: 0.0.1
Author:: scx567888

Method Summary

Modifier and Type

Method

Description

void

close()

default long

indexOf(byte b)

default long

indexOf(byte[] b)

default long

indexOf(byte[] b, long maxLength)

default long

indexOf(byte b, long maxLength)

long

indexOf(ByteIndexer indexer, long maxLength)

在最多 maxLength 个字节中查找匹配 (或直到 EOF).

boolean

isClosed()

void

mark()

标记当前读取位置.

byte

peek()

查看字节, 行为参考 read()

default byte[]

peek(int maxLength)

<X extends Throwable> void

peek(ByteConsumer<X> byteConsumer, long maxLength)

查看字节, 行为参考 read(ByteConsumer, long)

default byte[]

peekAll()

default <X extends Throwable> void

peekAll(ByteConsumer<X> byteConsumer)

default byte[]

peekFully(int length)

<X extends Throwable> void

peekFully(ByteConsumer<X> byteConsumer, long length)

查看字节, 行为参考 readFully(ByteConsumer, long)

default byte[]

peekUntil(byte b)

default byte[]

peekUntil(byte[] b)

default byte[]

peekUntil(byte[] b, int maxLength)

default byte[]

peekUntil(byte b, int maxLength)

default byte[]

peekUpTo(int length)

<X extends Throwable> void

peekUpTo(ByteConsumer<X> byteConsumer, long length)

查看字节, 行为参考 readUpTo(ByteConsumer, long)

byte

read()

读取单个字节

default byte[]

read(int maxLength)

<X extends Throwable> void

read(ByteConsumer<X> byteConsumer, long maxLength)

最多读取 maxLength 个字节, 可能少于 maxLength (即使尚未遇到 EOF, 如底层缓冲区不足)

default byte[]

readAll()

default <X extends Throwable> void

readAll(ByteConsumer<X> byteConsumer)

default byte[]

readFully(int length)

<X extends Throwable> void

readFully(ByteConsumer<X> byteConsumer, long length)

恰好读取 length 个字节

default byte[]

readUntil(byte b)

default byte[]

readUntil(byte[] b)

default byte[]

readUntil(byte[] b, int maxLength)

从当前 ByteInput 中读取数据直到遇到指定分隔符 (单字节或多字节).

default byte[]

readUntil(byte b, int maxLength)

default byte[]

readUpTo(int length)

<X extends Throwable> void

readUpTo(ByteConsumer<X> byteConsumer, long length)

尽量读取 length 个字节, 可能少于 length (仅在 EOF 时发生)

void

reset()

将读取位置恢复到上一次 mark() 时的状态.

default long

skip(long length)

default long

skipAll()

default long

skipFully(long length)

default long

skipUpTo(long length)

Method Details
- read
  byte read() throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  读取单个字节
  
  如果当前没有数据可读 (立即遇到 EOF), 则会抛出 NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- read
  <X extends Throwable> void read(ByteConsumer<X> byteConsumer, long maxLength) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  最多读取 maxLength 个字节, 可能少于 maxLength (即使尚未遇到 EOF, 如底层缓冲区不足)
  
  如果 maxLength = 0, 立即返回 (不抛出异常, 即使在 EOF 状态)
  
  如果 maxLength > 0, 至少读取 1 个字节.
  
  如果数据不足 (读取过程中遇到 EOF), 则停止读取
  
  如果当前没有数据可读 (立即遇到 EOF), 则会抛出 NoMoreDataException
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUpTo
  <X extends Throwable> void readUpTo(ByteConsumer<X> byteConsumer, long length) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  尽量读取 length 个字节, 可能少于 length (仅在 EOF 时发生)
  
  如果 length = 0, 立即返回 (不抛出异常, 即使在 EOF 状态)
  
  如果 length > 0, 至少读取 1 个字节.
  
  如果数据不足 (读取过程中遇到 EOF), 则停止读取
  
  如果当前没有数据可读 (立即遇到 EOF), 则会抛出 NoMoreDataException
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readFully
  <X extends Throwable> void readFully(ByteConsumer<X> byteConsumer, long length) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  恰好读取 length 个字节
  
  如果 length = 0, 立即返回且不抛出异常 (即使在 EOF 状态)
  
  如果 length > 0. 一定读取 length 个字节.
  
  如果数据不足 (读取过程中遇到 EOF), 则会抛出 NoMoreDataException
  
  如果当前没有数据可读 (立即遇到 EOF), 则会抛出 NoMoreDataException
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peek
  
  byte peek() throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  查看字节, 行为参考 read()
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peek
  
  <X extends Throwable> void peek(ByteConsumer<X> byteConsumer, long maxLength) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  查看字节, 行为参考 read(ByteConsumer, long)
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUpTo
  
  <X extends Throwable> void peekUpTo(ByteConsumer<X> byteConsumer, long length) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  查看字节, 行为参考 readUpTo(ByteConsumer, long)
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekFully
  
  <X extends Throwable> void peekFully(ByteConsumer<X> byteConsumer, long length) throws X, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  查看字节, 行为参考 readFully(ByteConsumer, long)
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- indexOf
  long indexOf(ByteIndexer indexer, long maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  在最多 maxLength 个字节中查找匹配 (或直到 EOF).
  
  如果 indexer 是空匹配模式. (意味着没有消费数据的能力和意义)
  
  在任意情况下都返回 0. (恒为 0)
  
  如果 indexer 不是空匹配模式.
  
  如果 maxLength = 0, 抛 NoMatchFoundException (恒 NoMatch, 因为这是不可能完成的任务).
  
  如果 maxLength > 0. (正常逻辑)
  
  如果在边界达成条件内仍未匹配到 (如达到 maxLength限制或读取过程中遇到 EOF) 抛出 NoMatchFoundException.
  
  如果当前没有数据可读 (立即遇到 EOF), 则会抛出 NoMoreDataException.
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- mark
  void mark() throws AlreadyClosedException
  
  标记当前读取位置.
  
  每次调用 mark() 会覆盖上一次的标记 (即不支持嵌套 mark)
  
  Throws:
  
  AlreadyClosedException
- reset
  void reset() throws AlreadyClosedException
  
  将读取位置恢复到上一次 mark() 时的状态.
  
  若尚未调用 mark(), 则无效果.
  
  调用 reset() 不会清除标记, 可重复 reset().
  
  Throws:
  
  AlreadyClosedException
- isClosed
  
  boolean isClosed()
- close
  
  void close() throws ScxIOException
  
  Specified by:
  
  close in interface AutoCloseable
  
  Throws:
  
  ScxIOException
- read
  
  default byte[] read(int maxLength) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUpTo
  
  default byte[] readUpTo(int length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readFully
  
  default byte[] readFully(int length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readAll
  
  default byte[] readAll() throws ScxIOException, AlreadyClosedException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
- readAll
  
  default <X extends Throwable> void readAll(ByteConsumer<X> byteConsumer) throws X, ScxIOException, AlreadyClosedException
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
- peek
  
  default byte[] peek(int maxLength) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUpTo
  
  default byte[] peekUpTo(int length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekFully
  
  default byte[] peekFully(int length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekAll
  
  default byte[] peekAll() throws ScxIOException, AlreadyClosedException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
- peekAll
  
  default <X extends Throwable> void peekAll(ByteConsumer<X> byteConsumer) throws X, ScxIOException, AlreadyClosedException
  
  Throws:
  
  X
  
  ScxIOException
  
  AlreadyClosedException
- skip
  
  default long skip(long length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- skipUpTo
  
  default long skipUpTo(long length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- skipFully
  
  default long skipFully(long length) throws ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- skipAll
  
  default long skipAll() throws ScxIOException, AlreadyClosedException
  
  Throws:
  
  ScxIOException
  
  AlreadyClosedException
- indexOf
  
  default long indexOf(byte b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- indexOf
  
  default long indexOf(byte b, long maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- indexOf
  
  default long indexOf(byte[] b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- indexOf
  
  default long indexOf(byte[] b, long maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUntil
  
  default byte[] readUntil(byte b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUntil
  
  default byte[] readUntil(byte b, int maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUntil
  
  default byte[] readUntil(byte[] b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- readUntil
  default byte[] readUntil(byte[] b, int maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  从当前 ByteInput 中读取数据直到遇到指定分隔符 (单字节或多字节).
  
  返回的数据不包含分隔符.
  
  方法调用结束后, ByteInput 的读取指针会跳过分隔符, 即下一次读取从分隔符之后开始.
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUntil
  
  default byte[] peekUntil(byte b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUntil
  
  default byte[] peekUntil(byte b, int maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUntil
  
  default byte[] peekUntil(byte[] b) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException
- peekUntil
  
  default byte[] peekUntil(byte[] b, int maxLength) throws NoMatchFoundException, ScxIOException, AlreadyClosedException, NoMoreDataException
  
  Throws:
  
  NoMatchFoundException
  
  ScxIOException
  
  AlreadyClosedException
  
  NoMoreDataException

Interface ByteInput

Method Summary

Method Details

read

read

readUpTo

readFully

peek

peek

peekUpTo

peekFully

indexOf

mark

reset

isClosed

close

read

readUpTo

readFully

readAll

readAll

peek

peekUpTo

peekFully

peekAll

peekAll

skip

skipUpTo

skipFully

skipAll

indexOf

indexOf

indexOf

indexOf

readUntil

readUntil

readUntil

readUntil

peekUntil

peekUntil

peekUntil

peekUntil