Package org.apache.iceberg.io

Interface RangeReadable

All Superinterfaces:

AutoCloseable, Closeable

public interface RangeReadable
extends Closeable

RangeReadable is an interface that allows for implementations of InputFile streams to perform positional, range-based reads, which are more efficient than unbounded reads in many cloud provider object stores.

Thread safety is not a requirement of the interface and is left to the implementation.

If the implementation is also a SeekableInputStream, the position of the stream is not required to be updated based on the positional reads performed by this interface. Usage of SeekableInputStream should always seek to the appropriate position for InputStream based reads.

Method Summary

Modifier and Type	Method	Description
default void	readFully(long position, byte[] buffer)	Fill the entire buffer with the contents of the input source starting at position.
void	readFully(long position, byte[] buffer, int offset, int length)	Fill the provided buffer with the contents of the input source starting at position for the given offset and length.
default int	readTail(byte[] buffer)	Read the full size of the buffer from the end of the file.
int	readTail(byte[] buffer, int offset, int length)	Read the last length bytes from the file.
default void	readVectored(List<FileRange> ranges, IntFunction<ByteBuffer> allocate)	Read fully a list of file ranges asynchronously from this file.
static List<FileRange>	sortRanges(List<FileRange> input)

Methods inherited from interface java.io.Closeable

close

Method Details

readFully

void readFully(long position,
 byte[] buffer,
 int offset,
 int length)
        throws IOException

Fill the provided buffer with the contents of the input source starting at position for the given offset and length.

Parameters:

position - start position of the read

buffer - target buffer to copy data

offset - offset in the buffer to copy the data

length - size of the read

Throws:

IOException

readFully

default void readFully(long position,
 byte[] buffer)
                throws IOException

Fill the entire buffer with the contents of the input source starting at position.

Parameters:

position - start position of the read

buffer - target buffer to copy data

Throws:

IOException

readTail

int readTail(byte[] buffer,
 int offset,
 int length)
      throws IOException

Read the last length bytes from the file.

Parameters:

buffer - the buffer to write data into

offset - the offset in the buffer to start writing

length - the number of bytes from the end of the object to read

Returns:

the actual number of bytes read

Throws:

IOException - if an error occurs while reading

readTail

default int readTail(byte[] buffer)
              throws IOException

Read the full size of the buffer from the end of the file.

Parameters:

buffer - the buffer to write data into

Returns:

the actual number of bytes read

Throws:

IOException - if an error occurs while reading

readVectored

default void readVectored(List<FileRange> ranges,
 IntFunction<ByteBuffer> allocate)
                   throws IOException

Read fully a list of file ranges asynchronously from this file. As a result of the call, each range will have FileRange.setData(CompletableFuture) called with a future that when complete will have a ByteBuffer with the data from the file's range.

The position returned by getPos() after readVectored() is undefined.

If a file is changed while the readVectored() operation is in progress, the output is undefined. Some ranges may have old data, some may have new and some may have both.

While a readVectored() operation is in progress, normal read api calls may block.

Parameters:

ranges - the byte ranges to read

allocate - the function to allocate ByteBuffer

Throws:

IOException - any IOE.

IllegalArgumentException - if any of ranges are invalid, or they overlap.

sortRanges

static List<FileRange> sortRanges(List<FileRange> input)