feat: introduce ZARR3 StorageFormat, repurpose ZARR3

ZARR storage previously referred to zarr 2. given the update to support zarr 3, ZARR3 was introduced. However, ZARR should still exists as a "generic zarr" format that prefers the newest zarr version. The behavior of ZARR is as follows

For readers in order:
- return a Zarr3 reader
- else return a Zarr2 reader

For Writers, in order of attempt:
- if the location contains a zarr3 container, try to open a zarr3 writer
- else if the location contains a zarr2 container, try to open a zarr2 writer
- else if there is no existing zarr container, attempt to create a Zarr3 container.
- if a Zarr3 container could not be created, create a zarr2 container.

Signed-off-by: Caleb Hulbert <cmhulbert@gmail.com>

Author: cmhulbert

src/main/java/org/janelia/saalfeldlab/n5/universe/N5Factory.java

@@ -244,7 +244,7 @@ public N5Reader openFSReader(final String path) {
 	@Deprecated
 	public N5Reader openZarrReader(final String path) {
 
-		return openN5ContainerWithStorageFormat(StorageFormat.ZARR2, path, this::openReader);
+		return openN5ContainerWithStorageFormat(StorageFormat.ZARR, path, this::openReader);
 	}
 
 	/**
@@ -430,17 +430,37 @@ public N5Reader openReader(@Nullable final StorageFormat storage, @Nullable fina
 			switch (storage) {
 			case N5:
 				return new N5KeyValueReader(access, containerPath, gsonBuilder, cacheAttributes);
-			case ZARR:
+			case ZARR3:
 				return new ZarrV3KeyValueReader(access,containerPath, gsonBuilder, cacheAttributes);
 			case ZARR2:
 				return new ZarrKeyValueReader(access, containerPath, gsonBuilder, zarrMapN5DatasetAttributes, zarrMergeAttributes, cacheAttributes);
+			case ZARR:
+				return newGenericZarrReader(access, location);
 			case HDF5:
 				return new N5HDF5Reader(containerPath, hdf5OverrideBlockSize, gsonBuilder, hdf5DefaultBlockSize);
 			}
 			return null;
 		}
 	}
 
+    /**
+	 * Open a zarr as N5Reader at the given {@code access} and {@code location}.
+	 * Will prefer returning the newest version of zarr that is found at the location.
+	 *
+     * @param access to the key-value access backend
+     * @param location of the zarr container
+     * @return an N5Reader
+     */
+	private N5Reader newGenericZarrReader(final KeyValueAccess access, final URI location) {
+		for (StorageFormat zarrFormat : List.of(ZARR3, ZARR2)) {
+			try {
+				return openReader(zarrFormat, access, location);
+			} catch (Exception ignored) {
+			}
+		}
+		throw new N5Exception("Unable to open Zarr reader at " + location.toString() + " as N5Reader");
+	}
+
 	/**
 	 * Open an {@link N5Writer} for N5 Container.
 	 * <p>
@@ -473,7 +493,7 @@ public N5Writer openFSWriter(final String path) {
 	@Deprecated
 	public N5Writer openZarrWriter(final String path) {
 
-		return openN5ContainerWithStorageFormat(StorageFormat.ZARR2, path, this::openWriter);
+		return openN5ContainerWithStorageFormat(StorageFormat.ZARR, path, this::openWriter);
 	}
 
 	/**
@@ -636,12 +656,14 @@ public N5Writer openWriter(@Nullable final StorageFormat storage, @Nullable fina
 
 			final String containerLocation = location.toString();
 			switch (storage) {
-			case ZARR:
+			case ZARR3:
 				final ZarrV3KeyValueWriter writer = new ZarrV3KeyValueWriter(access, containerLocation, gsonBuilder, cacheAttributes);
 				writer.setDimensionSeparator(zarrDimensionSeparator);
 				return writer;
 			case ZARR2:
 				return new ZarrKeyValueWriter(access, containerLocation, gsonBuilder, zarrMapN5DatasetAttributes, zarrMergeAttributes, zarrDimensionSeparator, cacheAttributes);
+			case ZARR:
+				return newGenericZarrWriter(access, location);
 			case N5:
 				return new N5KeyValueWriter(access, containerLocation, gsonBuilder, cacheAttributes);
 			case HDF5:
@@ -651,6 +673,37 @@ public N5Writer openWriter(@Nullable final StorageFormat storage, @Nullable fina
 		return null;
 	}
 
+    /**
+	 * Try to get a zarr writer at the given location and access.
+	 * If a container exists at the location, load that version as a writer if possible.
+	 * If no container exists, create a new writer with the newest zarr version.
+	 *
+     * @param access to the key-value backend
+     * @param location of the zarr writer
+     * @return the zarr writer
+     */
+	private N5Writer newGenericZarrWriter(final KeyValueAccess access, final URI location) {
+		List<StorageFormat> zarrFormats = List.of(ZARR3, ZARR2);
+		for (StorageFormat zarrFormat : zarrFormats) {
+			 /* we dont care about the read, but we do want to prefer a writer over a container that
+			 * exists, rather than creating a new writer; the only way to check is to see if
+			 * we can get a valid reader. If we can, try the writer. */
+            try (N5Reader ignore = openReader(zarrFormat, access, location)) {
+                return openWriter(zarrFormat, access, location);
+            } catch (Exception ignored) {
+            }
+		}
+		/* However, if we have no valid readers, then try and return the first valid (created) writer */
+		for (StorageFormat zarrFormat : zarrFormats) {
+			try {
+				return openWriter(zarrFormat, access, location);
+			} catch (Exception ignored) {
+			}
+		}
+
+		throw new N5Exception("Unable to open Zarr writer at " + location.toString() + " as N5Reader");
+	}
+
 	private <T extends N5Reader> T openN5ContainerWithStorageFormat(
 			final StorageFormat format,
 			final String uri,

src/main/java/org/janelia/saalfeldlab/n5/universe/StorageFormat.java

@@ -18,7 +18,8 @@
 import java.util.regex.Pattern;
 
 public enum StorageFormat {
-	ZARR(Pattern.compile("zarr(3)?", Pattern.CASE_INSENSITIVE), uri -> Pattern.compile("\\.zarr$", Pattern.CASE_INSENSITIVE).matcher(new File(uri.getPath()).toString()).find()),
+	ZARR(Pattern.compile("zarr", Pattern.CASE_INSENSITIVE), uri -> Pattern.compile("\\.zarr$", Pattern.CASE_INSENSITIVE).matcher(new File(uri.getPath()).toString()).find()),
+	ZARR3(Pattern.compile("zarr3", Pattern.CASE_INSENSITIVE), uri -> Pattern.compile("\\.zarr$", Pattern.CASE_INSENSITIVE).matcher(new File(uri.getPath()).toString()).find()),
 	ZARR2(Pattern.compile("zarr2", Pattern.CASE_INSENSITIVE), uri -> Pattern.compile("\\.zarr$", Pattern.CASE_INSENSITIVE).matcher(new File(uri.getPath()).toString()).find()),
 	N5(Pattern.compile("n5", Pattern.CASE_INSENSITIVE), uri -> Pattern.compile("\\.n5$", Pattern.CASE_INSENSITIVE).matcher(new File(uri.getPath()).toString()).find()),
 	HDF5(Pattern.compile("h(df)?5", Pattern.CASE_INSENSITIVE), uri -> {
@@ -93,7 +94,7 @@ public static Pair<StorageFormat, String> getStorageFromNestedScheme(String uri)
 				return StorageFormat.HDF5;
 		} catch (final Exception ignore) {}
 		if (kva.exists(kva.compose(uri, ZARR3_ATTRIBUTES)))
-			return StorageFormat.ZARR;
+			return StorageFormat.ZARR3;
 		if (Arrays.stream(ZARR2_KEYS).anyMatch(it -> kva.exists(kva.compose(uri, it))))
 			return StorageFormat.ZARR2;
 		if (kva.exists(kva.compose(uri, N5_ATTRIBUTES)))