refactor!: implementation of KVA.createReadData

* add LazyRead interface,
* add HttpLazyRead, FileLazyRead
* add KeyValueAccessReadData using LazyRead

Author: bogovicj

src/main/java/org/janelia/saalfeldlab/n5/FileSystemKeyValueAccess.java

@@ -86,6 +86,8 @@
 import java.util.Iterator;
 import java.util.stream.Stream;
 
+import org.janelia.saalfeldlab.n5.readdata.KeyValueAccessReadData;
+import org.janelia.saalfeldlab.n5.readdata.LazyRead;
 import org.janelia.saalfeldlab.n5.readdata.ReadData;
 
 /**
@@ -210,7 +212,7 @@ public FileSystemKeyValueAccess(final FileSystem fileSystem) {
 
 	@Override
 	public ReadData createReadData(final String normalPath) {
-		return new FileLazyReadData(this, normalPath, 0, -1);
+		return new KeyValueAccessReadData(new FileLazyRead(normalPath));
 	}
 
 	@Override
@@ -620,39 +622,45 @@ protected static void createAndCheckIsDirectory(
 		}
 	}
 
-	private static class FileLazyReadData extends KeyValueAccessLazyReadData<FileSystemKeyValueAccess> {
+	private class FileLazyRead implements LazyRead {
 
-		public FileLazyReadData(FileSystemKeyValueAccess kva, String normalKey, long offset, long length) {
-			super(kva, normalKey, offset, length);
-		}
+		private final String normalKey;
 
-		@Override
-		void read() throws N5IOException {
+	    FileLazyRead(String normalKey) {
+	        this.normalKey = normalKey;
+	    }
 
-			try (FileChannel channel = kva.lockForReading(normalKey).getFileChannel()) {
-				channel.position(offset);
-				if (length > Integer.MAX_VALUE)
-					throw new IOException("Attempt to materialize too large data");
+	    @Override
+	    public long size() {
+	        return FileSystemKeyValueAccess.this.size(normalKey);
+	    }
 
-				final long channelSize = channel.size();
-				if( !validBounds(channelSize, offset, length))
-					throw new IndexOutOfBoundsException();
+	    @Override
+	    public ReadData materialize(final long offset, final long length) {
 
-				final int sz = (int)(length < 0 ? channelSize : length);
-				final byte[] data = new byte[sz];
-				final ByteBuffer buf = ByteBuffer.wrap(data);
-				channel.read(buf);
-				materialized = ReadData.from(data);
+	        try (final LockedFileChannel lfs = new LockedFileChannel(normalKey, true)) {
+	            final FileChannel channel = lfs.getFileChannel();
+	            channel.position(offset);
+	            if (length > Integer.MAX_VALUE)
+	                throw new IOException("Attempt to materialize too large data");
 
-			} catch (final IOException e) {
-				throw new N5Exception.N5IOException(e);
-			}
-		}
+	            final long channelSize = channel.size();
+	            if (!validBounds(channelSize, offset, length))
+	                throw new IndexOutOfBoundsException();
+
+	            final int sz = (int) (length < 0 ? channelSize : length);
+	            final byte[] data = new byte[sz];
+	            final ByteBuffer buf = ByteBuffer.wrap(data);
+	            channel.read(buf);
+	            return ReadData.from(data);
+
+	        } catch (final NoSuchFileException e) {
+	            throw new N5NoSuchKeyException("No such file", e);
+	        } catch (IOException | UncheckedIOException e) {
+	            throw new N5Exception.N5IOException(e);
+	        }
+	    }
 
-		@Override
-		KeyValueAccessLazyReadData<FileSystemKeyValueAccess> lazySlice(long offset, long length) {
-			return new FileLazyReadData(kva, normalKey, offset, length);
-		}
 	}
 
 	private static boolean validBounds(long channelSize, long offset, long length) {

src/main/java/org/janelia/saalfeldlab/n5/HttpKeyValueAccess.java

@@ -33,6 +33,8 @@
 import org.apache.commons.lang3.function.TriFunction;
 import org.janelia.saalfeldlab.n5.N5Exception.N5IOException;
 import org.janelia.saalfeldlab.n5.http.ListResponseParser;
+import org.janelia.saalfeldlab.n5.readdata.KeyValueAccessReadData;
+import org.janelia.saalfeldlab.n5.readdata.LazyRead;
 import org.janelia.saalfeldlab.n5.readdata.ReadData;
 
 import java.io.Closeable;
@@ -231,8 +233,8 @@ private HttpURLConnection httpRequest(String normalPath, String method) throws I
 	}
 
 	@Override
-	public HttpLazyReadData createReadData(final String normalPath) {
-		return new HttpLazyReadData(this, normalPath, 0, -1);
+	public ReadData createReadData(final String normalPath) {
+		return new KeyValueAccessReadData(new HttpLazyRead(normalPath));
 	}
 
 	public LockedChannel lockForReading(final String normalPath) throws N5IOException {
@@ -427,28 +429,29 @@ public void close() throws IOException {
 		}
 	}
 
-	private class HttpLazyReadData extends KeyValueAccessLazyReadData<HttpKeyValueAccess> {
+	private class HttpLazyRead implements LazyRead {
 
-		public HttpLazyReadData(HttpKeyValueAccess kva, String normalKey, long offset, long length) {
-			super(kva, normalKey, offset, length);
+		private final String normalKey;
+
+		HttpLazyRead(String normalKey) {
+			this.normalKey = normalKey;
+		}
+
+		@Override
+		public long size() {
+			return HttpKeyValueAccess.this.size(normalKey);
 		}
 
 		@Override
-		void read() throws N5IOException {
-			// TODO does this throw out-of-bounds when it should
-			try( final HttpObjectChannel ch = new HttpObjectChannel(kva.uri(normalKey), offset, length) ) {
-				materialized = ReadData.from(ch.newInputStream()).materialize();
+		public ReadData materialize(long offset, long length) {
+			try (final HttpObjectChannel ch = new HttpObjectChannel(uri(normalKey), offset, length)) {
+				return ReadData.from(ch.newInputStream()).materialize();
 			} catch (IOException e) {
-				throw new N5Exception.N5IOException(e);
+				throw new N5IOException(e);
 			} catch (URISyntaxException e) {
 				throw new N5Exception(e);
 			}
 		}
-
-		@Override
-		KeyValueAccessLazyReadData<HttpKeyValueAccess> lazySlice(long offset, long length) {
-			return new HttpLazyReadData(kva, normalKey, offset, length);
-		}
 	}
 
 }

src/main/java/org/janelia/saalfeldlab/n5/readdata/KeyValueAccessReadData.java

@@ -0,0 +1,70 @@
+package org.janelia.saalfeldlab.n5.readdata;
+
+import java.io.InputStream;
+
+import org.janelia.saalfeldlab.n5.N5Exception.N5IOException;
+
+public class KeyValueAccessReadData implements ReadData {
+
+    private final LazyRead lazyRead;
+    private ReadData materialized;
+    private final long offset;
+    private long length;
+
+    public KeyValueAccessReadData(LazyRead lazyRead) {
+        this(lazyRead, 0, -1);
+    }
+
+    public KeyValueAccessReadData(final LazyRead lazyRead, final long offset, final long length) {
+        this.lazyRead = lazyRead;
+        this.offset = offset;
+        this.length = length;
+    }
+
+    @Override
+    public ReadData materialize() throws N5IOException {
+        if (materialized == null)
+            materialized = lazyRead.materialize(offset, length);
+        return materialized;
+    }
+
+    @Override
+    public ReadData slice(final long offset, final long length) throws N5IOException {
+        if (offset < 0)
+            throw new IndexOutOfBoundsException("Negative offset: " + offset);
+            
+        if (materialized != null)
+            return materialized.slice(offset, length);
+
+        // if a slice of indeterminate length is requested, but the
+        // length is already known, use the known length;
+        final int lengthArg;
+        if (this.length > 0 && length < 0)
+            lengthArg = (int)(this.length - offset);
+        else
+            lengthArg = (int)length;
+
+        return new KeyValueAccessReadData(lazyRead, this.offset + offset, lengthArg);
+    }
+
+    @Override
+    public InputStream inputStream() throws N5IOException, IllegalStateException {
+        return materialize().inputStream();
+    }
+
+    @Override
+    public byte[] allBytes() throws N5IOException, IllegalStateException {
+        return materialize().allBytes();
+    }
+
+    @Override
+    public long length() throws N5IOException {
+        if (materialized != null)
+            return materialized.length();
+        if (length < 0) {
+            length = lazyRead.size() - offset;
+        }
+        return length;
+    }
+
+}

src/main/java/org/janelia/saalfeldlab/n5/readdata/LazyRead.java

@@ -0,0 +1,34 @@
+package org.janelia.saalfeldlab.n5.readdata;
+
+/**
+ * A lazy reading strategy for lazy, partial reading of data from some source.
+ * <p>
+ * Implementations of this interface handle the specifics of accessing data from
+ * their respective sources.
+ * 
+ * @see ReadData
+ * @see KeyValueAccessReadData
+ */
+public interface LazyRead {
+
+    /**
+     * Materializes a portion of the data into a concrete {@link ReadData} instance.
+     * <p>
+     * This method performs the actual read operation from the underlying source,
+     * loading only the requested portion of data. The implementation should handle
+     * bounds checking and throw appropriate exceptions for invalid ranges.
+     *
+     * @param offset the starting position in the data source
+     * @param length the number of bytes to read, or -1 to read from offset to end
+     * @return a materialized {@link ReadData} instance containing the requested data
+     */
+    ReadData materialize(long offset, long length);
+
+    /**
+     * Returns the total size of the data source in bytes.
+     * 
+     * @return the size of the data source in bytes
+     */
+    long size();
+
+}