adds javadoc

Author: normanrz

README.md

@@ -3,6 +3,7 @@
 This repository contains an early preview of a Java implementation of the Zarr specification. 
 It is intended for collecting feedback from the community and not for use. The API is subject to changes.
 
+Refer to [JZarr](https://github.com/zarr-developers/jzarr) for a stable implementation of Zarr version 2.
 
 ## Usage
 ```java
@@ -18,8 +19,8 @@ Group hierarchy = Group.open(
 );
 Array array = hierarchy.get("color").get("1");
 ucar.ma2.Array outArray = array.read(
-    new long[]{0, 3073, 3073, 513}, 
-    new int[]{1, 64, 64, 64}
+    new long[]{0, 3073, 3073, 513}, // offset
+    new int[]{1, 64, 64, 64} // shape
 );
 
 Array array = Array.create(
@@ -33,7 +34,7 @@ Array array = Array.create(
         .build();
 );
 array.write(
-    new long[]{0, 0, 0, 0}, 
+    new long[]{0, 0, 0, 0}, // offset
     ucar.ma2.Array.factory(ucar.ma2.DataType.UINT, new int[]{1, 1024, 1024, 1024})
 );
 ```

TODO

@@ -48,7 +48,7 @@ public static long[] toLongArray(int[] array) {
 
   public static int[] toIntArray(long[] array) {
     return Arrays.stream(array)
-        .mapToInt(i -> (int) i)
+        .mapToInt(Math::toIntExact)
         .toArray();
   }
 

src/main/java/com/scalableminds/zarrjava/utils/Utils.java

@@ -10,10 +10,12 @@
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import ucar.ma2.InvalidRangeException;
 
 public class Array extends Node {
@@ -28,6 +30,13 @@ protected Array(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
     this.codecPipeline = new CodecPipeline(arrayMetadata.codecs);
   }
 
+  /**
+   * Opens an existing Zarr array at a specified storage location.
+   *
+   * @param storeHandle
+   * @throws IOException
+   * @throws ZarrException
+   */
   public static Array open(StoreHandle storeHandle) throws IOException, ZarrException {
     return new Array(
         storeHandle,
@@ -39,11 +48,32 @@ public static Array open(StoreHandle storeHandle) throws IOException, ZarrExcept
     );
   }
 
+  /**
+   * Creates a new Zarr array with the provided metadata at a specified storage location. This
+   * method will raise an exception if a Zarr array already exists at the specified storage
+   * location.
+   *
+   * @param storeHandle
+   * @param arrayMetadata
+   * @throws IOException
+   * @throws ZarrException
+   */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
       throws IOException, ZarrException {
     return Array.create(storeHandle, arrayMetadata, false);
   }
 
+  /**
+   * Creates a new Zarr array with the provided metadata at a specified storage location. If
+   * `existsOk` is false, this method will raise an exception if a Zarr array already exists at the
+   * specified storage location.
+   *
+   * @param storeHandle
+   * @param arrayMetadata
+   * @param existsOk
+   * @throws IOException
+   * @throws ZarrException
+   */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata, boolean existsOk)
       throws IOException, ZarrException {
     StoreHandle metadataHandle = storeHandle.resolve(ZARR_JSON);
@@ -58,18 +88,53 @@ public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata,
     return new Array(storeHandle, arrayMetadata);
   }
 
+  /**
+   * Creates a new Zarr array at a specified storage location. This method provides a callback that
+   * gets an ArrayMetadataBuilder and needs to return such an ArrayMetadataBuilder. The callback can
+   * be used to construct the metadata of the Zarr array. If `existsOk` is false, this method will
+   * raise an exception if a Zarr array already exists at the specified storage location.
+   *
+   * @param storeHandle
+   * @param arrayMetadataBuilderMapper
+   * @param existsOk
+   * @throws IOException
+   * @throws ZarrException
+   */
+  public static Array create(StoreHandle storeHandle,
+      Function<ArrayMetadataBuilder, ArrayMetadataBuilder> arrayMetadataBuilderMapper,
+      boolean existsOk) throws IOException, ZarrException {
+    return Array.create(storeHandle,
+        arrayMetadataBuilderMapper.apply(new ArrayMetadataBuilder()).build(), existsOk);
+  }
+
+  @Nonnull
   public static ArrayMetadataBuilder metadataBuilder() {
     return new ArrayMetadataBuilder();
   }
 
+  @Nonnull
   public static ArrayMetadataBuilder metadataBuilder(ArrayMetadata existingMetadata) {
     return ArrayMetadataBuilder.fromArrayMetadata(existingMetadata);
   }
 
+  /**
+   * Reads the entire Zarr array into an ucar.ma2.Array.
+   *
+   * @throws ZarrException
+   */
+  @Nonnull
   public ucar.ma2.Array read() throws ZarrException {
     return read(new long[metadata.ndim()], Utils.toIntArray(metadata.shape));
   }
 
+  /**
+   * Reads a part of the Zarr array based on a requested offset and shape into an ucar.ma2.Array.
+   *
+   * @param offset
+   * @param shape
+   * @throws ZarrException
+   */
+  @Nonnull
   public ucar.ma2.Array read(final long[] offset, final int[] shape) throws ZarrException {
     if (offset.length != metadata.ndim()) {
       throw new IllegalArgumentException("'offset' needs to have rank '" + metadata.ndim() + "'.");
@@ -105,15 +170,13 @@ public ucar.ma2.Array read(final long[] offset, final int[] shape) throws ZarrEx
                 final StoreHandle chunkHandle = storeHandle.resolve(chunkKeys);
 
                 if (codecPipeline.supportsPartialDecode()) {
-                  System.out.println("decodePartial");
                   final ucar.ma2.Array chunkArray = codecPipeline.decodePartial(chunkHandle,
                       Utils.toLongArray(chunkProjection.chunkOffset), chunkProjection.shape,
                       metadata.coreArrayMetadata);
                   MultiArrayUtils.copyRegion(chunkArray, new int[metadata.ndim()], outputArray,
                       chunkProjection.outOffset, chunkProjection.shape
                   );
                 } else {
-                  System.out.println("decode");
                   MultiArrayUtils.copyRegion(readChunk(chunkCoords), chunkProjection.chunkOffset,
                       outputArray, chunkProjection.outOffset, chunkProjection.shape
                   );
@@ -137,6 +200,14 @@ boolean chunkIsInArray(long[] chunkCoords) {
     return true;
   }
 
+  /**
+   * Reads one chunk of the Zarr array as specified by the chunk coordinates into an
+   * ucar.ma2.Array.
+   *
+   * @param chunkCoords The coordinates of the chunk as computed by the offset of the chunk divided
+   *                    by the chunk shape.
+   * @throws ZarrException
+   */
   @Nonnull
   public ucar.ma2.Array readChunk(long[] chunkCoords)
       throws ZarrException {
@@ -155,10 +226,23 @@ public ucar.ma2.Array readChunk(long[] chunkCoords)
     return codecPipeline.decode(chunkBytes, metadata.coreArrayMetadata);
   }
 
+  /**
+   * Writes a ucar.ma2.Array into the Zarr array at the beginning of the Zarr array. The shape of
+   * the Zarr array needs be large enough for the write.
+   *
+   * @param array
+   */
   public void write(ucar.ma2.Array array) {
     write(new long[metadata.ndim()], array);
   }
 
+  /**
+   * Writes a ucar.ma2.Array into the Zarr array at a specified offset. The shape of the Zarr array
+   * needs be large enough for the write.
+   *
+   * @param offset
+   * @param array
+   */
   public void write(long[] offset, ucar.ma2.Array array) {
     if (offset.length != metadata.ndim()) {
       throw new IllegalArgumentException("'offset' needs to have rank '" + metadata.ndim() + "'.");
@@ -200,6 +284,14 @@ public void write(long[] offset, ucar.ma2.Array array) {
             });
   }
 
+  /**
+   * Writes one chunk into the Zarr array as specified by the chunk coordinates. The shape of the
+   * Zarr array needs be large enough for the write.
+   *
+   * @param chunkCoords
+   * @param chunkArray
+   * @throws ZarrException
+   */
   public void writeChunk(long[] chunkCoords, ucar.ma2.Array chunkArray) throws ZarrException {
     String[] chunkKeys = metadata.chunkKeyEncoding.encodeChunkKey(chunkCoords);
     StoreHandle chunkHandle = storeHandle.resolve(chunkKeys);
@@ -212,6 +304,10 @@ public void writeChunk(long[] chunkCoords, ucar.ma2.Array chunkArray) throws Zar
     }
   }
 
+  public ArrayAccessor access() {
+    return new ArrayAccessor(this);
+  }
+
   private Array writeMetadata(ArrayMetadata newArrayMetadata) throws ZarrException, IOException {
     ObjectMapper objectMapper = Node.makeObjectMapper();
     ByteBuffer metadataBytes = ByteBuffer.wrap(objectMapper.writeValueAsBytes(newArrayMetadata));
@@ -220,6 +316,15 @@ private Array writeMetadata(ArrayMetadata newArrayMetadata) throws ZarrException
     return new Array(storeHandle, newArrayMetadata);
   }
 
+  /**
+   * Sets a new shape for the Zarr array. It only changes the metadata, no array data is modified or
+   * deleted. This method returns a new instance of the Zarr array class and the old instance
+   * becomes invalid.
+   *
+   * @param newShape
+   * @throws ZarrException
+   * @throws IOException
+   */
   public Array resize(long[] newShape) throws ZarrException, IOException {
     if (newShape.length != metadata.ndim()) {
       throw new IllegalArgumentException(
@@ -232,6 +337,14 @@ public Array resize(long[] newShape) throws ZarrException, IOException {
     return writeMetadata(newArrayMetadata);
   }
 
+  /**
+   * Sets the attributes of the Zarr array. It overwrites and removes any existing attributes. This
+   * method returns a new instance of the Zarr array class and the old instance becomes invalid.
+   *
+   * @param newAttributes
+   * @throws ZarrException
+   * @throws IOException
+   */
   public Array setAttributes(Map<String, Object> newAttributes) throws ZarrException, IOException {
     ArrayMetadata newArrayMetadata =
         ArrayMetadataBuilder.fromArrayMetadata(metadata)
@@ -240,9 +353,20 @@ public Array setAttributes(Map<String, Object> newAttributes) throws ZarrExcepti
     return writeMetadata(newArrayMetadata);
   }
 
+  /**
+   * Updates the attributes of the Zarr array. It provides a callback that gets the current
+   * attributes as input and needs to return the new set of attributes. The attributes in the
+   * callback may be mutated. This method overwrites and removes any existing attributes. This
+   * method returns a new instance of the Zarr array class and the old instance becomes invalid.
+   *
+   * @param attributeMapper
+   * @throws ZarrException
+   * @throws IOException
+   */
   public Array updateAttributes(Function<Map<String, Object>, Map<String, Object>> attributeMapper)
       throws ZarrException, IOException {
-    return setAttributes(attributeMapper.apply(metadata.attributes));
+    return setAttributes(attributeMapper.apply(new HashMap<String, Object>(metadata.attributes) {
+    }));
   }
 
   @Override
@@ -254,4 +378,56 @@ public String toString() {
         metadata.dataType
     );
   }
+
+  public static final class ArrayAccessor {
+
+    @Nullable
+    long[] offset;
+    @Nullable
+    int[] shape;
+    @Nonnull
+    Array array;
+
+    private ArrayAccessor(@Nonnull Array array) {
+      this.array = array;
+    }
+
+    @Nonnull
+    public ArrayAccessor withOffset(@Nonnull long... offset) {
+      this.offset = offset;
+      return this;
+    }
+
+
+    @Nonnull
+    public ArrayAccessor withShape(@Nonnull int... shape) {
+      this.shape = shape;
+      return this;
+    }
+
+    @Nonnull
+    public ArrayAccessor withShape(@Nonnull long... shape) {
+      this.shape = Utils.toIntArray(shape);
+      return this;
+    }
+
+    @Nonnull
+    public ucar.ma2.Array read() throws ZarrException {
+      if (offset == null) {
+        throw new ZarrException("`offset` needs to be set.");
+      }
+      if (shape == null) {
+        throw new ZarrException("`shape` needs to be set.");
+      }
+      return array.read(offset, shape);
+    }
+
+    public void write(@Nonnull ucar.ma2.Array content) throws ZarrException {
+      if (offset == null) {
+        throw new ZarrException("`offset` needs to be set.");
+      }
+      array.write(offset, content);
+    }
+
+  }
 }

src/main/java/com/scalableminds/zarrjava/v3/Array.java

@@ -98,6 +98,12 @@ public Array createArray(String key, ArrayMetadata arrayMetadata)
     return Array.create(storeHandle.resolve(key), arrayMetadata);
   }
 
+  public Array createArray(String key,
+      Function<ArrayMetadataBuilder, ArrayMetadataBuilder> arrayMetadataBuilderMapper)
+      throws IOException, ZarrException {
+    return Array.create(storeHandle.resolve(key), arrayMetadataBuilderMapper, false);
+  }
+
   public Stream<Node> list() {
     return storeHandle.list()
         .map(key -> {