public interface ByteSource
A ByteSource contains a sequence of bytes.
The read() action succeeds with a ByteBuffer containing next chunk of bytes,
or fails with End to indicate EOF.
The source must be closed after use.
Example Usage:
ByteSource src = new FileByteSource("/tmp/data.bin");
AsyncIterator.forEach( src::read, System.out::println )
.finally_( src::close );
A ByteSource can optionally support skip(n).
In general, a ByteSource is not thread-safe. See ThreadSafeByteSource
for a thread-safe wrapper.
In general, concurrent pending actions are not allowed.
Particularly, close() cannot be invoked while a read() is pending.
See ThreadSafeByteSource for a solution.
| Abstract Methods | |
|---|---|
Async<ByteBuffer> |
read()
Read the next chunk of bytes.
|
Async<Void> |
close()
Close this source.
|
| Default Methods | |
long |
skip(long n)
Try to skip forward `n` bytes; return number of bytes actually skipped.
|
Async<ByteBuffer> |
readAll(int maxBytes)
Read all bytes from this source into one ByteBuffer.
|
Async<String> |
asString(int maxChars)
Read all bytes from this source and convert them to a String.
|
Async<String> |
asString(int maxChars,
Charset charset)
Read all bytes from this source and convert them to a String.
|
Async<Long> |
toSink(ByteSink sink)
Write the bytes from this source to the sink.
|
Async<ByteBuffer> read()
The method returns an `Async<ByteBuffer>` which eventually completes in 3 possible ways:
End, indicating EOF.
Example Usage:
AsyncIterator.forEach( source::read, System.out::println )
.finally_( source::close );
The resulting ByteBuffer may contain any number of bytes. For example, it may be a view of
a huge ByteBuffer that's cached and shared.
You may use PushbackByteSource to "unread".
The ownership of the ByteBuffer is transferred to the caller. The content of the ByteBuffer should be treated as read-only.
CAUTION: since ByteBuffer is stateful (even for methods like ByteBuffer.get()),
a new ByteBuffer must be created for each read() action.
The implementation may create a view of a shared ByteBuffer through
ByteBuffer.asReadOnlyBuffer().
The app should wait for this read() action to complete before it calls another method on this source.
default long skip(long n)
throws IllegalArgumentException
This is an optional operation. An implementation can simply do nothing and return 0. The default implementation does exactly that.
The returned value must no exceed `n`.
It's possible to skip beyond EOF. For example, if there are 10 bytes left in this source, skip(20) may succeed and return 15. The next read() will see EOF.
The implementation must be non-blocking.
This method should not be invoked while a read() is pending, or after close() has been called. IllegalStateException may be thrown if that happens.
n - number of bytes to skip; n >= 0.0 <= m <= n.IllegalArgumentException - if n < 0.Async<Void> close()
This method can be called multiple times; only the first call is effective.
This method should not be invoked while a read() is pending;
if that's needed, see ThreadSafeByteSource for a solution.
Since ByteSource is a read-only concept, close() should not have any
side effects that the caller cares about.
The caller is allowed to ignore the returned Async<Void>
(as if the method returns void).
The close() action should not fail; if some internal exception arises, it can be logged.
Most implementations return an immediate Async.VOID,
even if there are still background cleanup tasks running.
default Async<ByteBuffer> readAll(int maxBytes)
If this source has more bytes than `maxBytes`, this action fails with
an OverLimitException.
The `maxBytes` parameter is usually a defense against denial-of-service requests.
Example Usage:
ByteSource requestBody = httpRequest.entity().body();
requestBody.readAll(1000).then(...);
This source is automatically closed after `allBytes()` is completed (in success or failure).
maxBytes - max number of bytes expected from this source.default Async<String> asString(int maxChars)
The encoding is required to be UTF-8.
If the bytes are not a valid UTF-8 sequence, this action fails with
CharacterCodingException.
If the number of chars exceeds `maxChars`, this action fails with
an OverLimitException.
The `maxChars` parameter is usually a defense against denial-of-service requests.
CAUTION: `maxChars` refers to the number of Java chars here, not unicode characters.
Example Usage:
ByteSource requestBody = httpRequest.entity().body();
requestBody.asString(1000).then(...);
This source is automatically closed after `asString()` action is completed (in success or failure).
maxChars - max number of chars expected from this source.default Async<String> asString(int maxChars, Charset charset)
If the bytes are not a valid encoding of the `charset`, this action fails with
CharacterCodingException.
If the number of chars exceeds `maxChars`, this action fails with
an OverLimitException.
The `maxChars` parameter is usually a defense against denial-of-service requests.
CAUTION: `maxChars` refers to the number of Java chars here, not unicode characters.
Example Usage:
ByteSource requestBody = httpRequest.entity().body();
requestBody.asString(1000, StandardCharsets.UTF_16).then(...);
This source is automatically closed after `asString()` action is completed (in success or failure).
maxChars - max number of chars expected from this source.