Package org.aoju.bus.core.io.source

Interface BufferSource

All Superinterfaces:

AutoCloseable, Channel, Closeable, ReadableByteChannel, Source

All Known Implementing Classes:

Buffer, RealSource

public interface BufferSource
extends Source, ReadableByteChannel

内部保存一个缓冲区,以便调用者可以在没有性能的情况下进行少量读取 它还允许客户端提前读取,在消费之前进行必要的缓冲输入

Since:

Java 17+

Author:

Kimi Liu

Method Summary

Modifier and Type	Method	Description
Buffer	buffer()
boolean	exhausted()
Buffer	getBuffer()
long	indexOf(byte bytes)	Equivalent to indexOf(b, 0).
long	indexOf(byte bytes, long fromIndex)	Returns the index of the first b in the buffer at or after fromIndex.
long	indexOf(byte bytes, long fromIndex, long toIndex)	Returns the index of b if it is found in the range of fromIndex inclusive to toIndex exclusive.
long	indexOf(ByteString bytes)	Equivalent to indexOf(bytes, 0).
long	indexOf(ByteString bytes, long fromIndex)	Returns the index of the first match for bytes in the buffer at or after fromIndex.
long	indexOfElement(ByteString targetBytes)
long	indexOfElement(ByteString bytes, long fromIndex)
InputStream	inputStream()	an input stream that reads from this source.
BufferSource	peek()	a new BufferSource that can read data from this BufferSource without consuming it.
boolean	rangeEquals(long offset, ByteString bytes)	true if the bytes at offset in this source equal bytes.
boolean	rangeEquals(long offset, ByteString bytes, int bytesOffset, int byteCount)	if byteCount bytes at offset in this source equal bytes * at bytesOffset.
int	read(byte[] sink)	Removes up to sink.length bytes from this and copies them into sink.
int	read(byte[] sink, int offset, int byteCount)	Removes up to byteCount bytes from this and copies them into sink at offset.
long	readAll(Sink sink)	Removes all bytes from this and appends them to sink.
byte	readByte()
byte[]	readByteArray()	Removes all bytes from this and returns them as a byte array.
byte[]	readByteArray(long byteCount)	Removes byteCount bytes from this and returns them as a byte array.
ByteString	readByteString()	Removes all bytes bytes from this and returns them as a byte string.
ByteString	readByteString(long byteCount)	Removes byteCount bytes from this and returns them as a byte string.
long	readDecimalLong()	Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading '-').
void	readFully(byte[] sink)	Removes exactly sink.length bytes from this and copies them into sink.
void	readFully(Buffer sink, long byteCount)	Removes exactly byteCount bytes from this and appends them to sink.
long	readHexadecimalUnsignedLong()	Reads a long form this source in hexadecimal form (i.e., as a string in base 16).
int	readInt()
int	readIntLe()
long	readLong()
long	readLongLe()	Removes eight bytes from this source and returns a little-endian long.
short	readShort()
short	readShortLe()	Removes two bytes from this source and returns a little-endian short.
String	readString(long byteCount, Charset charset)	Removes byteCount bytes from this, decodes them as charset,
String	readString(Charset charset)
String	readUtf8()	Removes all bytes from this, decodes them as UTF-8, and returns the string.
String	readUtf8(long byteCount)	Removes byteCount bytes from this, decodes them as UTF-8, and returns the string.
int	readUtf8CodePoint()
String	readUtf8Line()	Removes and returns characters up to but not including the next line break.
String	readUtf8LineStrict()	Removes and returns characters up to but not including the next line break.
String	readUtf8LineStrict(long limit)	Like readUtf8LineStrict(), except this allows the caller to specify the longest allowed match.
boolean	request(long byteCount)
void	require(long byteCount)	when the buffer contains at least byteCount bytes.
int	select(Blending options)	Finds the first string in options that is a prefix of this buffer, consumes it from this buffer, and returns its index.
void	skip(long byteCount)	Reads and discards byteCount bytes from this source.

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Methods inherited from interface java.nio.channels.ReadableByteChannel

read

Methods inherited from interface org.aoju.bus.core.io.source.Source

close, read, timeout

Method Details

buffer

Buffer buffer()

Returns:

this source's internal buffer. use getBuffer() instead.

getBuffer

Buffer getBuffer()

Returns:

This source's internal buffer.

exhausted

boolean exhausted()
           throws IOException

Returns:

true if there are no more bytes in this source. This will block until there are bytes to read or the source is definitely exhausted.

Throws:

IOException - IOException IOException.

require

void require(long byteCount)
      throws IOException

when the buffer contains at least byteCount bytes.

Parameters:

byteCount - long

Throws:

IOException - IOException IOException.

request

boolean request(long byteCount)
         throws IOException

Parameters:

byteCount - long

Returns:

true when the buffer contains at least byteCount bytes, expanding it as necessary. Returns false if the source is exhausted before the requested bytes can be read.

Throws:

IOException - IOException IOException.

readByte

byte readByte()
       throws IOException

Returns:

Removes a byte from this source and returns it.

Throws:

IOException - IOException IOException.

readShort

short readShort()
         throws IOException

Returns:

two bytes from this source and returns a big-endian short.

   Buffer buffer = new Buffer()
       .writeByte(0x7f)
       .writeByte(0xff)
       .writeByte(0x00)
       .writeByte(0x0f);
   assertEquals(4, buffer.size());

   assertEquals(32767, buffer.readShort());
   assertEquals(2, buffer.size());

   assertEquals(15, buffer.readShort());
   assertEquals(0, buffer.size());
 

Throws:

IOException - IOException IOException.

readShortLe

short readShortLe()
           throws IOException

Removes two bytes from this source and returns a little-endian short.

   Buffer buffer = new Buffer()
       .writeByte(0xff)
       .writeByte(0x7f)
       .writeByte(0x0f)
       .writeByte(0x00);
   assertEquals(4, buffer.size());

   assertEquals(32767, buffer.readShortLe());
   assertEquals(2, buffer.size());

   assertEquals(15, buffer.readShortLe());
   assertEquals(0, buffer.size());
 

Returns:

the short

Throws:

IOException - IOException IOException.

readInt

int readInt()
     throws IOException

Returns:

the int

Throws:

IOException - IOException IOException.

readIntLe

int readIntLe()
       throws IOException

Returns:

the int

Throws:

IOException - IOException IOException.

readLong

long readLong()
       throws IOException

Returns:

the long

Throws:

IOException - IOException IOException.

readLongLe

long readLongLe()
         throws IOException

Removes eight bytes from this source and returns a little-endian long.

   Buffer buffer = new Buffer()
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0xff)
       .writeByte(0x7f)
       .writeByte(0x0f)
       .writeByte(0x00)
       .writeByte(0x00)
       .writeByte(0x00)
       .writeByte(0x00)
       .writeByte(0x00)
       .writeByte(0x00)
       .writeByte(0x00);
   assertEquals(16, buffer.size());

   assertEquals(9223372036854775807L, buffer.readLongLe());
   assertEquals(8, buffer.size());

   assertEquals(15, buffer.readLongLe());
   assertEquals(0, buffer.size());
 

Returns:

the long

Throws:

IOException - IOException IOException.

readDecimalLong

long readDecimalLong()
              throws IOException

Reads a long from this source in signed decimal form (i.e., as a string in base 10 with optional leading '-'). This will iterate until a non-digit character is found.

   Buffer buffer = new Buffer()
       .writeUtf8("8675309 -123 00001");

   assertEquals(8675309L, buffer.readDecimalLong());
   assertEquals(' ', buffer.readByte());
   assertEquals(-123L, buffer.readDecimalLong());
   assertEquals(' ', buffer.readByte());
   assertEquals(1L, buffer.readDecimalLong());
 

Returns:

the long

Throws:

IOException - if the found digits do not fit into a long or a decimal number was not present.

readHexadecimalUnsignedLong

long readHexadecimalUnsignedLong()
                          throws IOException

Reads a long form this source in hexadecimal form (i.e., as a string in base 16). This will iterate until a non-hexadecimal character is found.

   Buffer buffer = new Buffer()
       .writeUtf8("ffff CAFEBABE 10");

   assertEquals(65535L, buffer.readHexadecimalUnsignedLong());
   assertEquals(' ', buffer.readByte());
   assertEquals(0xcafebabeL, buffer.readHexadecimalUnsignedLong());
   assertEquals(' ', buffer.readByte());
   assertEquals(0x10L, buffer.readHexadecimalUnsignedLong());
 

Returns:

the long

Throws:

IOException - if the found hexadecimal does not fit into a long or hexadecimal was not found.

skip

void skip(long byteCount)
   throws IOException

Reads and discards byteCount bytes from this source. Throws an IOException if the source is exhausted before the requested bytes can be skipped.

Parameters:

byteCount - long

Throws:

IOException - IOException IOException.

readByteString

ByteString readByteString()
                   throws IOException

Removes all bytes bytes from this and returns them as a byte string.

Returns:

the ByteString

Throws:

IOException - IOException IOException.

readByteString

ByteString readByteString(long byteCount)
                   throws IOException

Removes byteCount bytes from this and returns them as a byte string.

Parameters:

byteCount - long

Returns:

the ByteString

Throws:

IOException - IOException IOException.

select

int select(Blending options)
    throws IOException

Finds the first string in options that is a prefix of this buffer, consumes it from this buffer, and returns its index. If no byte string in options is a prefix of this buffer this returns -1 and no bytes are consumed.

This can be used as an alternative to readByteString() or even readUtf8() if the set of expected values is known in advance.

   Options FIELDS = Options.of(
       ByteString.encodeUtf8("depth="),
       ByteString.encodeUtf8("height="),
       ByteString.encodeUtf8("width="));

   Buffer buffer = new Buffer()
       .writeUtf8("width=640\n")
       .writeUtf8("height=480\n");

   assertEquals(2, buffer.select(FIELDS));
   assertEquals(640, buffer.readDecimalLong());
   assertEquals('\n', buffer.readByte());
   assertEquals(1, buffer.select(FIELDS));
   assertEquals(480, buffer.readDecimalLong());
   assertEquals('\n', buffer.readByte());
 

Parameters:

options - Options

Returns:

the int

Throws:

IOException - IOException IOException.

readByteArray

byte[] readByteArray()
              throws IOException

Removes all bytes from this and returns them as a byte array.

Returns:

the byte[]

Throws:

IOException - IOException IOException.

readByteArray

byte[] readByteArray(long byteCount)
              throws IOException

Removes byteCount bytes from this and returns them as a byte array.

Parameters:

byteCount - long

Returns:

the byte[]

Throws:

IOException - IOException IOException.

read

int read(byte[] sink)
  throws IOException

Removes up to sink.length bytes from this and copies them into sink. Returns the number of bytes read, or -1 if this source is exhausted.

Parameters:

sink - byte[]

Returns:

the long

Throws:

IOException - IOException IOException.

readFully

void readFully(byte[] sink)
        throws IOException

Removes exactly sink.length bytes from this and copies them into sink. Throws an IOException if the requested number of bytes cannot be read.

Parameters:

sink - byte[]

Throws:

IOException - IOException IOException.

read

int read(byte[] sink,
 int offset,
 int byteCount)
  throws IOException

Removes up to byteCount bytes from this and copies them into sink at offset. Returns the number of bytes read, or -1 if this source is exhausted.

Parameters:

sink - byte[]

offset - int

byteCount - int

Returns:

the int

Throws:

IOException - IOException IOException.

readFully

void readFully(Buffer sink,
 long byteCount)
        throws IOException

Removes exactly byteCount bytes from this and appends them to sink. Throws an IOException if the requested number of bytes cannot be read.

Parameters:

sink - Buffer

byteCount - long

Throws:

IOException - IOException IOException.

readAll

long readAll(Sink sink)
      throws IOException

Removes all bytes from this and appends them to sink. Returns the total number of bytes written to sink which will be 0 if this is exhausted.

Parameters:

sink - Sink

Returns:

the long

Throws:

IOException - IOException IOException.

readUtf8

String readUtf8()
         throws IOException

Removes all bytes from this, decodes them as UTF-8, and returns the string. Returns the empty string if this source is empty.

   Buffer buffer = new Buffer()
       .writeUtf8("Uh uh uh!")
       .writeByte(' ')
       .writeUtf8("You didn't say the magic word!");

   assertEquals("Uh uh uh! You didn't say the magic word!", buffer.readUtf8());
   assertEquals(0, buffer.size());

   assertEquals("", buffer.readUtf8());
   assertEquals(0, buffer.size());
 

Returns:

the String

Throws:

IOException - IOException IOException.

readUtf8

String readUtf8(long byteCount)
         throws IOException

Removes byteCount bytes from this, decodes them as UTF-8, and returns the string.

   Buffer buffer = new Buffer()
       .writeUtf8("Uh uh uh!")
       .writeByte(' ')
       .writeUtf8("You didn't say the magic word!");
   assertEquals(40, buffer.size());

   assertEquals("Uh uh uh! You ", buffer.readUtf8(14));
   assertEquals(26, buffer.size());

   assertEquals("didn't say the", buffer.readUtf8(14));
   assertEquals(12, buffer.size());

   assertEquals(" magic word!", buffer.readUtf8(12));
   assertEquals(0, buffer.size());
 

Parameters:

byteCount - long

Returns:

the String

Throws:

IOException - IOException IOException.

readUtf8Line

String readUtf8Line()
             throws IOException

Removes and returns characters up to but not including the next line break. A line break is either "\n" or "\r\n"; these characters are not included in the result.

   Buffer buffer = new Buffer()
       .writeUtf8("I'm a hacker!\n")
       .writeUtf8("That's what I said: you're a nerd.\n")
       .writeUtf8("I prefer to be called a hacker!\n");
   assertEquals(81, buffer.size());

   assertEquals("I'm a hacker!", buffer.readUtf8Line());
   assertEquals(67, buffer.size());

   assertEquals("That's what I said: you're a nerd.", buffer.readUtf8Line());
   assertEquals(32, buffer.size());

   assertEquals("I prefer to be called a hacker!", buffer.readUtf8Line());
   assertEquals(0, buffer.size());

   assertEquals(null, buffer.readUtf8Line());
   assertEquals(0, buffer.size());
 

On the end of the stream this method returns null, just like BufferedReader. If the source doesn't end with a line break then an implicit line break is assumed. Null is returned once the source is exhausted. Use this for human-generated data, where a trailing line break is optional.

Returns:

the String

Throws:

IOException - IOException IOException.

readUtf8LineStrict

String readUtf8LineStrict()
                   throws IOException

Removes and returns characters up to but not including the next line break. A line break is either "\n" or "\r\n"; these characters are not included in the result.

On the end of the stream this method throws. Every call must consume either '\r\n' or '\n'. If these characters are absent in the stream, an IOException is thrown. Use this for machine-generated data where a missing line break implies truncated input.

Returns:

the String

Throws:

IOException - IOException IOException.

readUtf8LineStrict

String readUtf8LineStrict(long limit)
                   throws IOException

Like readUtf8LineStrict(), except this allows the caller to specify the longest allowed match. Use this to protect against streams that may not include "\n" or "\r\n".

The returned string will have at most limit UTF-8 bytes, and the maximum number of bytes scanned is limit + 2. If limit == 0 this will always throw an IOException because no bytes will be scanned.

This method is safe. No bytes are discarded if the match fails, and the caller is free to try another match:

   Buffer buffer = new Buffer();
   buffer.writeUtf8("12345\r\n");

   // This will throw! There must be \r\n or \n at the limit or before it.
   buffer.readUtf8LineStrict(4);

   // No bytes have been consumed so the caller can retry.
   assertEquals("12345", buffer.readUtf8LineStrict(5));
 

Parameters:

limit - long

Returns:

String String

Throws:

IOException - IOException IOException.

readUtf8CodePoint

int readUtf8CodePoint()
               throws IOException

Returns:

Removes and returns a single UTF-8 code point, reading between 1 and 4 bytes as necessary.

If this source is exhausted before a complete code point can be read, this throws an IOException and consumes no input.

If this source doesn't start with a properly-encoded UTF-8 code point, this method will remove 1 or more non-UTF-8 bytes and return the replacement character (U+FFFD). This covers encoding problems (the input is not properly-encoded UTF-8), characters out of range (beyond the 0x10ffff limit of Unicode), code points for UTF-16 surrogates (U+d800..U+dfff) and overlong encodings (such as 0xc080 for the NUL character in modified UTF-8).

Throws:

IOException - IOException IOException.

readString

String readString(Charset charset)
           throws IOException

Parameters:

charset - Charset Removes all bytes from this, decodes them as charset,

Returns:

the string.

Throws:

IOException - IOException IOException.

readString

String readString(long byteCount,
 Charset charset)
           throws IOException

Removes byteCount bytes from this, decodes them as charset,

Parameters:

byteCount - byteCount

charset - Charset

Returns:

the string.

Throws:

IOException - IOException IOException.

indexOf

long indexOf(byte bytes)
      throws IOException

Equivalent to indexOf(b, 0).

Parameters:

bytes - byte

Returns:

the long

Throws:

IOException - IOException IOException.

indexOf

long indexOf(byte bytes,
 long fromIndex)
      throws IOException

Returns the index of the first b in the buffer at or after fromIndex. This expands the buffer as necessary until b is found. This reads an unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the requested byte is found.

   Buffer buffer = new Buffer();
   buffer.writeUtf8("Don't move! He can't see us if we don't move.");

   byte m = 'm';
   assertEquals(6,  buffer.indexOf(m));
   assertEquals(40, buffer.indexOf(m, 12));
 

Parameters:

bytes - byte

fromIndex - long

Returns:

the long

Throws:

IOException - IOException IOException.

indexOf

long indexOf(byte bytes,
 long fromIndex,
 long toIndex)
      throws IOException

Returns the index of b if it is found in the range of fromIndex inclusive to toIndex exclusive. If b isn't found, or if fromIndex == toIndex, then -1 is returned.

The scan terminates at either toIndex or the end of the buffer, whichever comes first. The maximum number of bytes scanned is toIndex-fromIndex.

Parameters:

bytes - byte

fromIndex - long

toIndex - long

Returns:

the long

Throws:

IOException - IOException IOException.

indexOf

long indexOf(ByteString bytes)
      throws IOException

Equivalent to indexOf(bytes, 0).

Parameters:

bytes - ByteString

Returns:

the long

Throws:

IOException - IOException IOException.

indexOf

long indexOf(ByteString bytes,
 long fromIndex)
      throws IOException

Returns the index of the first match for bytes in the buffer at or after fromIndex. This expands the buffer as necessary until bytes is found. This reads an unbounded number of bytes into the buffer. Returns -1 if the stream is exhausted before the requested bytes are found.

   ByteString MOVE = ByteString.encodeUtf8("move");

   Buffer buffer = new Buffer();
   buffer.writeUtf8("Don't move! He can't see us if we don't move.");

   assertEquals(6,  buffer.indexOf(MOVE));
   assertEquals(40, buffer.indexOf(MOVE, 12));
 

Parameters:

bytes - ByteString

fromIndex - long

Returns:

the long

Throws:

IOException - IOException IOException.

indexOfElement

long indexOfElement(ByteString targetBytes)
             throws IOException

Parameters:

targetBytes - ByteString Equivalent to indexOfElement(targetBytes, 0).

Returns:

the long

Throws:

IOException - IOException IOException.

indexOfElement

long indexOfElement(ByteString bytes,
 long fromIndex)
             throws IOException

Parameters:

fromIndex - long

bytes - ByteString

Returns:

the long

Throws:

IOException - IOException IOException.

rangeEquals

boolean rangeEquals(long offset,
 ByteString bytes)
             throws IOException

true if the bytes at offset in this source equal bytes. This expands the buffer as necessary until a byte does not match, all bytes are matched, or if the stream is exhausted before enough bytes could determine a match.

                 ByteString simonSays = ByteString.encodeUtf8("Simon says:");

                 Buffer standOnOneLeg = new Buffer().writeUtf8("Simon says: Stand on first leg.");
                 assertTrue(standOnOneLeg.rangeEquals(0, simonSays));

                 Buffer payMeMoney = new Buffer().writeUtf8("Pay me $1,000,000.");
                 assertFalse(payMeMoney.rangeEquals(0, simonSays));
               

Parameters:

offset - long

bytes - ByteString

Returns:

the long

Throws:

IOException - IOException IOException.

rangeEquals

boolean rangeEquals(long offset,
 ByteString bytes,
 int bytesOffset,
 int byteCount)
             throws IOException

if byteCount bytes at offset in this source equal bytes * at bytesOffset. This expands the buffer as necessary until a byte does not match, all * bytes are matched, or if the stream is exhausted before enough bytes could determine a match.

Parameters:

offset - long

bytes - ByteString

bytesOffset - int

byteCount - int

Returns:

the true

Throws:

IOException - IOException IOException.

peek

BufferSource peek()

a new BufferSource that can read data from this BufferSource without consuming it. The returned source becomes invalid once this source is next read or closed.

For example, we can use peek() to lookahead and read the same data multiple times.

 

   Buffer buffer = new Buffer();
   buffer.writeUtf8("abcdefghi");

   buffer.readUtf8(3) // returns "abc", buffer contains "defghi"

   BufferSource peek = buffer.peek();
   peek.readUtf8(3); // returns "def", buffer contains "defghi"
   peek.readUtf8(3); // returns "ghi", buffer contains "defghi"

   buffer.readUtf8(3); // returns "def", buffer contains "ghi"
 

Returns:

the long

inputStream

InputStream inputStream()

an input stream that reads from this source.

Returns:

the InputStream