refactor!: "block" → "chunk" and "shard" → "block"

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

@@ -89,13 +89,13 @@ public class DatasetAttributes implements Serializable {
 
 	private final long[] dimensions;
 
+	// number of samples per chunk per dimension
+	private final int[] chunkSize;
+
 	// number of samples per block per dimension
+	// identical to chunkSize for non-sharded datasets
 	private final int[] blockSize;
 
-	// TODO add a getter?
-	// the shard size
-	private final int[] outerBlockSize;
-
 	private final DataType dataType;
 
 	private final JsonElement defaultValue;
@@ -108,7 +108,7 @@ public class DatasetAttributes implements Serializable {
 
 	public DatasetAttributes(
 			final long[] dimensions,
-			final int[] outerBlockSize,
+			final int[] blockSize,
 			final DataType dataType,
 			final JsonElement defaultValue,
 			final BlockCodecInfo blockCodecInfo,
@@ -117,7 +117,7 @@ public DatasetAttributes(
 
 		this.dimensions = dimensions;
 		this.dataType = dataType;
-		this.outerBlockSize = outerBlockSize;
+		this.blockSize = blockSize;
 		this.defaultValue = defaultValue == null ? JsonNull.INSTANCE : defaultValue;
 
 		this.blockCodecInfo = blockCodecInfo == null ? defaultBlockCodecInfo() : blockCodecInfo;
@@ -131,7 +131,7 @@ public DatasetAttributes(
 					.toArray(DataCodecInfo[]::new);
 
 		access = createDatasetAccess();
-		blockSize = access.getGrid().getBlockSize(0);
+		chunkSize = access.getGrid().getBlockSize(0);
 	}
 
 	public DatasetAttributes(
@@ -200,7 +200,7 @@ protected DatasetAccess<?> createDatasetAccess() {
 		// NestedGrid validates block sizes, so instantiate it before creating the blockCodecs
 		// blockCodecInfo.create below could fail unexpecedly with invalid
 		// blockSizes so validate first
-		blockSizes[m - 1] = outerBlockSize;
+		blockSizes[m - 1] = blockSize;
 		BlockCodecInfo tmpInfo = blockCodecInfo;
 		for (int l = m - 1; l > 0; --l) {
 			final ShardCodecInfo info = (ShardCodecInfo)tmpInfo;
@@ -274,6 +274,11 @@ public int getNumDimensions() {
 		return dimensions.length;
 	}
 
+	public int[] getChunkSize() {
+
+		return chunkSize;
+	}
+
 	public int[] getBlockSize() {
 
 		return blockSize;
@@ -334,7 +339,6 @@ public NestedGrid getNestedBlockGrid() {
 		return getDatasetAccess().getGrid();
 	}
 
-
 	public BlockCodecInfo getBlockCodecInfo() {
 
 		return blockCodecInfo;
@@ -359,7 +363,7 @@ public HashMap<String, Object> asMap() {
 
 		final HashMap<String, Object> map = new HashMap<>();
 		map.put(DIMENSIONS_KEY, dimensions);
-		map.put(BLOCK_SIZE_KEY, blockSize);
+		map.put(BLOCK_SIZE_KEY, chunkSize);
 		map.put(DATA_TYPE_KEY, dataType);
 		map.put(COMPRESSION_KEY, getCompression());
 		return map;
@@ -425,7 +429,7 @@ public static class DatasetAttributesAdapter implements JsonSerializer<DatasetAt
 
 			final JsonObject obj = new JsonObject();
 			obj.add(DIMENSIONS_KEY, context.serialize(src.dimensions));
-			obj.add(BLOCK_SIZE_KEY, context.serialize(src.blockSize));
+			obj.add(BLOCK_SIZE_KEY, context.serialize(src.chunkSize));
 			obj.add(DATA_TYPE_KEY, context.serialize(src.dataType));
 
 			final DataCodecInfo[] codecs = src.dataCodecInfos;

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);
 		}
 	}
@@ -326,16 +326,26 @@ default boolean deleteBlock(
 			final long... gridPosition) throws N5Exception {
 
 		final PositionValueAccess posKva = PositionValueAccess.fromKva(getKeyValueAccess(), getURI(), N5URI.normalizeGroupPath(path), datasetAttributes);
-		return datasetAttributes.getDatasetAccess().deleteBlock(posKva, gridPosition);
+		return posKva.remove(gridPosition);
+	}
+
+	@Override
+	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().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;