Add RangeReadable interface for range base FileIO reads

api/src/main/java/org/apache/iceberg/io/RangeReadable.java

@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.iceberg.io;
+
+/**
+ * {@code RangeReadable} is an interface that allows for implementations
+ * of {@link 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 {@link SeekableInputStream}, the position
+ * of the stream is not required to be updated based on the positional reads
+ * performed by this interface.  Usage of {@link SeekableInputStream} should
+ * always seek to the appropriate position for {@link java.io.InputStream}
+ * based reads.
+ *
+ */
+public interface RangeReadable extends AutoCloseable {
+
+  /**
+   * Fill the provided buffer with the contents of the input source starting
+   * at {@code position} for the given {@code offset} and {@code length}.
+   *
+   * @param position start position of the read
+   * @param buffer target buffer to copy data
+   * @param offset offset in the buffer to copy the data
+   * @param length size of the read
+   */
+  void readFully(long position, byte[] buffer, int offset, int length);
+
+  /**
+   * Fill the entire buffer with the contents of the input source starting
+   * at {@code position}.
+   *
+   * @param position start position of the read
+   * @param buffer target buffer to copy data
+   */
+  default void readFully(long position, byte[] buffer) {
+    readFully(position, buffer, 0, buffer.length);
+  }
+}

aws/src/main/java/org/apache/iceberg/aws/s3/S3InputStream.java

@@ -24,6 +24,7 @@
 import java.util.Arrays;
 import org.apache.iceberg.aws.AwsProperties;
 import org.apache.iceberg.io.FileIOMetricsContext;
+import org.apache.iceberg.io.RangeReadable;
 import org.apache.iceberg.io.SeekableInputStream;
 import org.apache.iceberg.metrics.MetricsContext;
 import org.apache.iceberg.metrics.MetricsContext.Counter;
@@ -33,11 +34,13 @@
 import org.apache.iceberg.relocated.com.google.common.io.ByteStreams;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import software.amazon.awssdk.core.ResponseBytes;
 import software.amazon.awssdk.core.sync.ResponseTransformer;
 import software.amazon.awssdk.services.s3.S3Client;
 import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
 
-class S3InputStream extends SeekableInputStream {
+class S3InputStream extends SeekableInputStream implements RangeReadable {
   private static final Logger LOG = LoggerFactory.getLogger(S3InputStream.class);
 
   private final StackTraceElement[] createStack;
@@ -111,6 +114,19 @@ public int read(byte[] b, int off, int len) throws IOException {
     return bytesRead;
   }
 
+  @Override
+  public void readFully(long position, byte[] buffer, int offset, int length) {
+    GetObjectRequest.Builder requestBuilder = GetObjectRequest.builder()
+        .bucket(location.bucket())
+        .key(location.key())
+        .range(String.format("bytes=%s-%s", position, position + length));
+
+    S3RequestUtil.configureEncryption(awsProperties, requestBuilder);
+
+    ResponseBytes<GetObjectResponse> response = s3.getObject(requestBuilder.build(), ResponseTransformer.toBytes());
+    System.arraycopy(response.asByteArrayUnsafe(), 0, buffer, offset, length);
+  }
+
   @Override
   public void close() throws IOException {
     super.close();

aws/src/test/java/org/apache/iceberg/aws/s3/TestS3InputStream.java

@@ -24,6 +24,7 @@
 import java.util.Arrays;
 import java.util.Random;
 import org.apache.commons.io.IOUtils;
+import org.apache.iceberg.io.RangeReadable;
 import org.apache.iceberg.io.SeekableInputStream;
 import org.junit.Before;
 import org.junit.ClassRule;
@@ -105,6 +106,50 @@ private void readAndCheck(SeekableInputStream in, long rangeStart, int size, byt
     assertArrayEquals(Arrays.copyOfRange(original, (int) rangeStart, (int) rangeEnd), actual);
   }
 
+  @Test
+  public void testRangeRead() throws Exception {
+    S3URI uri = new S3URI("s3://bucket/path/to/range-read.dat");
+    int dataSize = 1024 * 1024 * 10;
+    byte[] expected = randomData(dataSize);
+    byte[] actual = new byte[dataSize];
+
+    long position;
+    int offset;
+    int length;
+
+    writeS3Data(uri, expected);
+
+    try (RangeReadable in = new S3InputStream(s3, uri)) {
+      // first 1k
+      position = 0;
+      offset = 0;
+      length = 1024;
+      readAndCheckRanges(in, expected, position, actual, offset, length);
+
+      // last 1k
+      position = dataSize - 1024;
+      offset = dataSize - 1024;
+      length = 1024;
+      readAndCheckRanges(in, expected, position, actual, offset, length);
+
+      // middle 2k
+      position = dataSize / 2 - 1024;
+      offset = dataSize / 2 - 1024;
+      length = 1024 * 2;
+      readAndCheckRanges(in, expected, position, actual, offset, length);
+    }
+  }
+
+  private void readAndCheckRanges(
+      RangeReadable in, byte [] original, long position, byte [] buffer, int offset,
+      int length) {
+    in.readFully(position, buffer, offset, length);
+
+    assertArrayEquals(
+        Arrays.copyOfRange(original, offset, offset + length),
+        Arrays.copyOfRange(buffer, offset, offset + length));
+  }
+
   @Test
   public void testClose() throws Exception {
     S3URI uri = new S3URI("s3://bucket/path/to/closed.dat");