org.apache.hadoop.fs

Interface ByteBufferPositionedReadable

All Known Implementing Classes:

FSDataInputStream, HdfsDataInputStream

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public interface ByteBufferPositionedReadable

Implementers of this interface provide a positioned read API that writes to a ByteBuffer rather than a byte[].

See Also:

PositionedReadable, ByteBufferReadable

Method Summary

Modifier and Type	Method and Description
int	read(long position, ByteBuffer buf) Reads up to buf.remaining() bytes into buf from a given position in the file and returns the number of bytes read.
void	readFully(long position, ByteBuffer buf) Reads buf.remaining() bytes into buf from a given position in the file or until the end of the data was reached before the read operation completed.

Method Detail

read

int read(long position,
         ByteBuffer buf)
  throws IOException

Reads up to buf.remaining() bytes into buf from a given position in the file and returns the number of bytes read. Callers should use buf.limit(...) to control the size of the desired read and buf.position(...) to control the offset into the buffer the data should be written to.

After a successful call, buf.position() will be advanced by the number of bytes read and buf.limit() will be unchanged.

In the case of an exception, the state of the buffer (the contents of the buffer, the buf.position(), the buf.limit(), etc.) is undefined, and callers should be prepared to recover from this eventuality.

Callers should use StreamCapabilities.hasCapability(String) with StreamCapabilities.PREADBYTEBUFFER to check if the underlying stream supports this interface, otherwise they might get a UnsupportedOperationException.

Implementations should treat 0-length requests as legitimate, and must not signal an error upon their receipt.

This does not change the current offset of a file, and is thread-safe.

Parameters:

position - position within file

buf - the ByteBuffer to receive the results of the read operation.

Returns:

the number of bytes read, possibly zero, or -1 if reached end-of-stream

Throws:

IOException - if there is some error performing the read

readFully

void readFully(long position,
               ByteBuffer buf)
        throws IOException

Reads buf.remaining() bytes into buf from a given position in the file or until the end of the data was reached before the read operation completed. Callers should use buf.limit(...) to control the size of the desired read and buf.position(...) to control the offset into the buffer the data should be written to.

This operation provides similar semantics to read(long, ByteBuffer), the difference is that this method is guaranteed to read data until the ByteBuffer is full, or until the end of the data stream is reached.

Parameters:

position - position within file

buf - the ByteBuffer to receive the results of the read operation.

Throws:

IOException - if there is some error performing the read

EOFException - the end of the data was reached before the read operation completed

See Also:

read(long, ByteBuffer)