refactor!: block -> chunk, shard -> block

Author: bogovicj

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

@@ -94,7 +94,7 @@ default JsonElement getAttributes(final String pathName) throws N5Exception {
 	}
 
 	@Override
-	default <T> DataBlock<T> readBlock(
+	default <T> DataBlock<T> readChunk(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception {
@@ -103,26 +103,26 @@ default <T> DataBlock<T> readBlock(
 		try {
 			final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(pathName),
 					convertedDatasetAttributes);
-			return convertedDatasetAttributes.<T> getDatasetAccess().readBlock(posKva, gridPosition);
+			return convertedDatasetAttributes.<T> getDatasetAccess().readChunk(posKva, gridPosition);
 
 		} catch (N5Exception.N5NoSuchKeyException e) {
 			return null;
 		}
 	}
 
 	@Override
-	default <T> List<DataBlock<T>> readBlocks(
+	default <T> List<DataBlock<T>> readChunks(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final List<long[]> blockPositions) throws N5Exception {
 
 		DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(datasetAttributes);
 		final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(pathName), convertedDatasetAttributes);
-		return convertedDatasetAttributes.<T> getDatasetAccess().readBlocks(posKva, blockPositions);
+		return convertedDatasetAttributes.<T> getDatasetAccess().readChunks(posKva, blockPositions);
 	}
 
 	@Override
-	default <T> DataBlock<T> readShard(
+	default <T> DataBlock<T> readBlock(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception {
@@ -132,7 +132,7 @@ default <T> DataBlock<T> readShard(
 		try {
 			final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(pathName),
 					convertedDatasetAttributes);
-			return convertedDatasetAttributes.<T> getDatasetAccess().readShard(posKva, gridPosition, shardLevel);
+			return convertedDatasetAttributes.<T> getDatasetAccess().readBlock(posKva, gridPosition, shardLevel);
 
 		} catch (N5Exception.N5NoSuchKeyException e) {
 			return null;
@@ -172,7 +172,7 @@ default String absoluteAttributesPath(final String normalPath) {
 	}
 
 	@Override
-	default boolean shardExists(
+	default boolean blockExists(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception {

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

@@ -257,52 +257,52 @@ default <T> void writeRegion(
 	}
 
 	@Override
-	default <T> void writeBlocks(
+	default <T> void writeChunks(
 			final String datasetPath,
 			final DatasetAttributes datasetAttributes,
 			final DataBlock<T>... dataBlocks) throws N5Exception {
 
 		DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(datasetAttributes);
 		try {
 			final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(datasetPath), convertedDatasetAttributes);
-			convertedDatasetAttributes.<T>getDatasetAccess().writeBlocks(posKva, Arrays.asList(dataBlocks));
+			convertedDatasetAttributes.<T>getDatasetAccess().writeChunks(posKva, Arrays.asList(dataBlocks));
 		} catch (final UncheckedIOException e) {
 			throw new N5IOException(
-					"Failed to write blocks into dataset " + datasetPath, e);
+					"Failed to write chunks into dataset " + datasetPath, e);
 		}
 	}
 
 	@Override
-	default <T> void writeBlock(
+	default <T> void writeChunk(
 			final String path,
 			final DatasetAttributes datasetAttributes,
 			final DataBlock<T> dataBlock) throws N5Exception {
 
 		DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(datasetAttributes);
 		try {
 			final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(path), convertedDatasetAttributes);
-			convertedDatasetAttributes.<T> getDatasetAccess().writeBlock(posKva, dataBlock);
+			convertedDatasetAttributes.<T> getDatasetAccess().writeChunk(posKva, dataBlock);
 		} catch (final UncheckedIOException e) {
 			throw new N5IOException(
-					"Failed to write block " + Arrays.toString(dataBlock.getGridPosition()) + " into dataset " + path,
+					"Failed to write chunk " + Arrays.toString(dataBlock.getGridPosition()) + " into dataset " + path,
 					e);
 		}
 	}
 
 	@Override
-	default <T> void writeShard(
+	default <T> void writeBlock(
 			final String path,
 			final DatasetAttributes datasetAttributes,
-			final DataBlock<T> shard) throws N5Exception {
+			final DataBlock<T> dataBlock) throws N5Exception {
 
 		final DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(datasetAttributes);
 		final int shardLevel = convertedDatasetAttributes.getNestedBlockGrid().numLevels() - 1;
 		try {
 			final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(path), convertedDatasetAttributes);
-			convertedDatasetAttributes.<T> getDatasetAccess().writeShard(posKva, shard, shardLevel);
+			convertedDatasetAttributes.<T> getDatasetAccess().writeBlock(posKva, dataBlock, shardLevel);
 		} catch (final UncheckedIOException e) {
 			throw new N5IOException(
-					"Failed to write block " + Arrays.toString(shard.getGridPosition()) + " into dataset " + path,
+					"Failed to write block " + Arrays.toString(dataBlock.getGridPosition()) + " into dataset " + path,
 					e);
 		}
 	}
@@ -320,22 +320,22 @@ default boolean remove(final String path) throws N5Exception {
 	}
 
 	@Override
-	default boolean deleteBlock(
+	default boolean deleteChunk(
 			final String path,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception {
 
 		final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(path), datasetAttributes);
-		return datasetAttributes.getDatasetAccess().deleteBlock(posKva, gridPosition);
+		return datasetAttributes.getDatasetAccess().deleteChunk(posKva, gridPosition);
 	}
 
 	@Override
-	default boolean deleteBlocks(
+	default boolean deleteChunks(
 			final String path,
 			final DatasetAttributes datasetAttributes,
 			final List<long[]> gridPositions) throws N5Exception {
 
 		final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(path), datasetAttributes);
-		return datasetAttributes.getDatasetAccess().deleteBlocks(posKva, gridPositions);
+		return datasetAttributes.getDatasetAccess().deleteChunks(posKva, gridPositions);
 	}
 }

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

@@ -298,7 +298,7 @@ default DatasetAttributes getConvertedDatasetAttributes(final DatasetAttributes
 
 
 	/**
-	 * Reads a {@link DataBlock}.
+	 * Reads a chunk as a {@link DataBlock}.
 	 *
 	 * @param <T>
 	 *            the DataBlock data type
@@ -312,13 +312,13 @@ default DatasetAttributes getConvertedDatasetAttributes(final DatasetAttributes
 	 * @throws N5Exception
 	 *             the exception
 	 */
-	<T> DataBlock<T> readBlock(
+	<T> DataBlock<T> readChunk(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception;
 
 	/**
-	 * Reads multiple {@link DataBlock}s.
+	 * Reads multiple chunks as {@link DataBlock}s.
 	 * <p>
 	 * Implementations may optimize / batch read operations when possible, e.g.
 	 * in the case that the datasets are sharded.
@@ -335,24 +335,24 @@ <T> DataBlock<T> readBlock(
 	 * @throws N5Exception
 	 *             the exception
 	 */
-	default <T> List<DataBlock<T>> readBlocks(
+	default <T> List<DataBlock<T>> readChunks(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final List<long[]> gridPositions) throws N5Exception {
 
 		DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(datasetAttributes);
 		final ArrayList<DataBlock<T>> blocks = new ArrayList<>();
 		for( final long[] p : gridPositions )
-			blocks.add(readBlock(pathName, convertedDatasetAttributes, p));
+			blocks.add(readChunk(pathName, convertedDatasetAttributes, p));
 
 		return blocks;
 	}
 
 	/**
-	 * Reads a shard as a {@link DataBlock}.
+	 * Reads a block, returning a {@link DataBlock}. Will be a chunk or shard (if the dataset is sharded).
 	 * <p>
-	 * A "shard" is the largest level of the datasets {@link org.janelia.saalfeldlab.n5.shard.Nesting.NestedGrid}
-	 * This method's behavior is identical to readBlock for un-sharded datasets.
+	 * A block is the highest (coarsest) level of the dataset's {@link org.janelia.saalfeldlab.n5.shard.Nesting.NestedGrid}
+	 * This method's behavior is identical to {@link #readChunk} for un-sharded datasets.
 	 *
 	 * @param <T>
 	 *            the DataBlock data type
@@ -361,39 +361,40 @@ default <T> List<DataBlock<T>> readBlocks(
 	 * @param datasetAttributes
 	 *            the dataset attributes
 	 * @param gridPosition
-	 *            the position in the shard grid
+	 *            the position in the block grid
 	 * @return the data block
 	 * @throws N5Exception
 	 *             the exception
 	 *
 	 * @see DatasetAttributes#getNestedBlockGrid()
 	 */
-	<T> DataBlock<T> readShard(
+	<T> DataBlock<T> readBlock(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception;
 
 	/**
-	 * Checks if a shard (or block for non-sharded datasets) exists at the
-	 * given grid position without reading the data.
+	 * Checks if a block exists at the given grid position without reading the data.
 	 * <p>
 	 * This method only checks for the presence of the key value for the gridPosition, it does not
-	 * read or validate the contents.
+	 * read or validate the contents. As a result, this method refers to chunks in un-sharded datasets
+	 * or shards in sharded datasets.
 	 *
 	 * @param pathName
 	 *            dataset path
 	 * @param datasetAttributes
 	 *            the dataset attributes
 	 * @param gridPosition
-	 *            the shard grid position (or block position for non-sharded datasets)
-	 * @return true if the shard (or block) file exists
+	 *            the block grid position
+	 * @return true if the block file exists
 	 * @throws N5Exception
 	 *             the exception
 	 */
-	boolean shardExists(
+	boolean blockExists(
 			final String pathName,
 			final DatasetAttributes datasetAttributes,
 			final long... gridPosition) throws N5Exception;
+
 	/**
 	 * Load a {@link DataBlock} as a {@link Serializable}. The offset is given
 	 * in
@@ -419,7 +420,7 @@ default <T> T readSerializedBlock(
 			final long... gridPosition) throws N5Exception, ClassNotFoundException {
 
 		DatasetAttributes convertedDatasetAttributes = getConvertedDatasetAttributes(attributes);
-		final DataBlock<byte[]> block = readBlock(dataset, convertedDatasetAttributes, gridPosition);
+		final DataBlock<byte[]> block = readChunk(dataset, convertedDatasetAttributes, gridPosition);
 		if (block == null)
 			return null;