Merge branch 'cache-attributes' into wip/KeyValueInterface

# Conflicts:
#	src/main/java/org/janelia/saalfeldlab/n5/N5KeyValueWriter.java

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

@@ -28,7 +28,7 @@
 /**
  * Abstract base class for {@link DataBlock} implementations.
  *
- * @param <T>
+ * @param <T> the block data type
  *
  * @author Stephan Saalfeld
  */

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

@@ -51,7 +51,7 @@ public abstract class AbstractGsonReader implements GsonAttributesParser, N5Read
 	 * Constructs an {@link AbstractGsonReader} with a custom
 	 * {@link GsonBuilder} to support custom attributes.
 	 *
-	 * @param gsonBuilder
+	 * @param gsonBuilder the gson builder
 	 */
 	@Deprecated
 	public AbstractGsonReader(final GsonBuilder gsonBuilder) {

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

@@ -39,9 +39,11 @@ public interface BlockReader {
 	/**
 	 * Reads a {@link DataBlock} from an {@link InputStream}.
 	 *
-	 * @param dataBlock
-	 * @param in
-	 * @throws IOException
+	 * @param dataBlock the data block
+	 * @param in        the input stream
+	 * @param <T>       the block data type
+	 * @param <B>       the block type
+	 * @throws IOException the exception
 	 */
 	public <T, B extends DataBlock<T>> void read(final B dataBlock, final InputStream in) throws IOException;
 }

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

@@ -39,9 +39,10 @@ public interface BlockWriter {
 	/**
 	 * Writes a {@link DataBlock} into an {@link OutputStream}.
 	 *
-	 * @param dataBlock
-	 * @param out
-	 * @throws IOException
+	 * @param dataBlock the data block
+	 * @param out       the output stream
+	 * @param <T>       the block data type
+	 * @throws IOException the exception
 	 */
 	public <T> void write(final DataBlock<T> dataBlock, final OutputStream out) throws IOException;
 }

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

@@ -89,7 +89,7 @@ public interface DataBlock<T> {
 	 * modifying the data object of this data block after calling this method
 	 * may or may not change the content of the {@link ByteBuffer}.
 	 *
-	 * @param buffer
+	 * @param buffer the byte buffer
 	 */
 	public void readData(final ByteBuffer buffer);
 
@@ -98,15 +98,15 @@ public interface DataBlock<T> {
 	 * not necessarily equal {@link #getNumElements(int[])
 	 * getNumElements(getSize())}.
 	 *
-	 * @return
+	 * @return the number of elements
 	 */
 	public int getNumElements();
 
 	/**
 	 * Returns the number of elements in a box of given size.
 	 *
-	 * @param size
-	 * @return
+	 * @param size the size
+	 * @return the number of elements
 	 */
 	public static int getNumElements(final int[] size) {
 		int n = size[0];

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

@@ -81,10 +81,10 @@ public static DataType fromString(final String string) {
 	/**
 	 * Factory for {@link DataBlock DataBlocks}.
 	 *
-	 * @param blockSize
-	 * @param gridPosition
-	 * @param numElements not necessarily one element per block element
-	 * @return
+	 * @param blockSize the block size
+	 * @param gridPosition the grid position
+	 * @param numElements the number of elements (not necessarily one element per block element)
+	 * @return the data block
 	 */
 	public DataBlock<?> createDataBlock(final int[] blockSize, final long[] gridPosition, final int numElements) {
 
@@ -95,9 +95,9 @@ public DataBlock<?> createDataBlock(final int[] blockSize, final long[] gridPosi
 	 * Factory for {@link DataBlock DataBlocks} with one data element for each
 	 * block element (e.g. pixel image).
 	 *
-	 * @param blockSize
-	 * @param gridPosition
-	 * @return
+	 * @param blockSize the block size
+	 * @param gridPosition the grid position
+	 * @return the data block
 	 */
 	public DataBlock<?> createDataBlock(final int[] blockSize, final long[] gridPosition) {
 

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

@@ -56,11 +56,11 @@ public default <T, B extends DataBlock<T>> void read(
 	/**
 	 * Reads a {@link DataBlock} from an {@link InputStream}.
 	 *
-	 * @param in
-	 * @param datasetAttributes
-	 * @param gridPosition
-	 * @return
-	 * @throws IOException
+	 * @param in the input stream
+	 * @param datasetAttributes the dataset attributes
+	 * @param gridPosition the grid position
+	 * @return the block
+	 * @throws IOException the exception
 	 */
 	public static DataBlock<?> readBlock(
 			final InputStream in,

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

@@ -55,10 +55,11 @@ public default <T> void write(
 	/**
 	 * Writes a {@link DataBlock} into an {@link OutputStream}.
 	 *
-	 * @param out
-	 * @param datasetAttributes
-	 * @param dataBlock
-	 * @throws IOException
+	 * @param out               the output stream
+	 * @param datasetAttributes the dataset attributes
+	 * @param dataBlock         the data block
+	 * @param <T>               the block data type
+	 * @throws IOException the exception
 	 */
 	public static <T> void writeBlock(
 			final OutputStream out,

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

@@ -55,20 +55,22 @@ public interface GsonAttributesParser extends N5Reader {
 	 * Reads or creates the attributes map of a group or dataset.
 	 *
 	 * @param pathName group path
-	 * @return
-	 * @throws IOException
+	 * @return the attributes
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public HashMap<String, JsonElement> getAttributes(final String pathName) throws IOException;
 
 	/**
 	 * Parses an attribute from the given attributes map.
 	 *
-	 * @param map
-	 * @param key
-	 * @param clazz
-	 * @return
-	 * @throws IOException
+	 * @param map the attributes map
+	 * @param key the key
+	 * @param clazz the class
+	 * @param gson the gson
+	 * @param <T> the attribute type
+	 * @return the attribute
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public static <T> T parseAttribute(
@@ -87,11 +89,13 @@ public static <T> T parseAttribute(
 	/**
 	 * Parses an attribute from the given attributes map.
 	 *
-	 * @param map
-	 * @param key
-	 * @param type
-	 * @return
-	 * @throws IOException
+	 * @param map the attributes map
+	 * @param key the key
+	 * @param type the type 
+	 * @param gson the gson
+	 * @param <T> the attribute type
+	 * @return the attribute
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public static <T> T parseAttribute(
@@ -110,9 +114,10 @@ public static <T> T parseAttribute(
 	/**
 	 * Reads the attributes map from a given {@link Reader}.
 	 *
-	 * @param reader
-	 * @return
-	 * @throws IOException
+	 * @param reader the reader
+	 * @param gson the gson
+	 * @return the attributes map
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public static HashMap<String, JsonElement> readAttributes(final Reader reader, final Gson gson) throws IOException {
@@ -125,10 +130,10 @@ public static HashMap<String, JsonElement> readAttributes(final Reader reader, f
 	/**
 	 * Inserts new the JSON export of attributes into the given attributes map.
 	 *
-	 * @param map
-	 * @param attributes
-	 * @param gson
-	 * @throws IOException
+	 * @param map the target attributes map to be edited
+	 * @param attributes the source attributes map
+	 * @param gson the gson
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public static void insertAttributes(
@@ -143,9 +148,10 @@ public static void insertAttributes(
 	/**
 	 * Writes the attributes map to a given {@link Writer}.
 	 *
-	 * @param writer
-	 * @param map
-	 * @throws IOException
+	 * @param writer the writer
+	 * @param map the attributes map
+	 * @param gson the gson
+	 * @throws IOException the exception
 	 */
 	@Deprecated
 	public static void writeAttributes(
@@ -168,8 +174,8 @@ public static void writeAttributes(
 	 * <li>Object</li>
 	 * </ul>
 	 *
-	 * @param jsonPrimitive
-	 * @return
+	 * @param jsonPrimitive the json
+	 * @return the class
 	 */
 	@Deprecated
 	public static Class<?> classForJsonPrimitive(final JsonPrimitive jsonPrimitive) {
@@ -201,6 +207,9 @@ else if (jsonPrimitive.isNumber()) {
 	 * <li>String[]</li>
 	 * <li>Object[]</li>
 	 * </ul>
+	 * 
+	 * @param pathName the path
+	 * @return the attributes map
 	 */
 	@Override
 	@Deprecated

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

@@ -61,9 +61,9 @@ static Gson registerGson(final GsonBuilder gsonBuilder) {
 	/**
 	 * Reads the attributes json from a given {@link Reader}.
 	 *
-	 * @param reader
+	 * @param reader the reader
 	 * @return the root {@link JsonObject} of the attributes
-	 * @throws IOException
+	 * @throws IOException the exception
 	 */
 	static JsonElement readAttributes(final Reader reader, final Gson gson) throws IOException {
 
@@ -83,13 +83,13 @@ static <T> T readAttribute(final JsonElement root, final String normalizedAttrib
 	}
 
 	/**
-	 * Deserialize the {@code attribute} as {@link Type type} {@link T}.
+	 * Deserialize the {@code attribute} as {@link Type type} {@code T}.
 	 *
 	 * @param attribute to deserialize as {@link Type type}
 	 * @param gson      used to deserialize {@code attribute}
 	 * @param type      to desrialize {@code attribute} as
 	 * @param <T>       return type represented by {@link Type type}
-	 * @return the deserialized attribute object, or {@code null} if {@code attribute} cannot deserialize to {@link T}
+	 * @return the deserialized attribute object, or {@code null} if {@code attribute} cannot deserialize to {@code T}
 	 */
 	static <T> T parseAttributeElement(final JsonElement attribute, final Gson gson, final Type type) {
 
@@ -131,10 +131,11 @@ static <T> T parseAttributeElement(final JsonElement attribute, final Gson gson,
 	}
 
 	/**
-	 * Return the attribute at {@code normalizedAttributePath} as a {@link JsonElement}.
-	 * Does not attempt to parse the attribute.
+	 * Return the attribute at {@code normalizedAttributePath} as a
+	 * {@link JsonElement}. Does not attempt to parse the attribute.
 	 *
-	 * @param root                    to search for the {@link JsonElement} at location {@code normalizedAttributePath}
+	 * @param root                    to search for the {@link JsonElement} at
+	 *                                location {@code normalizedAttributePath}
 	 * @param normalizedAttributePath to the attribute
 	 * @return the attribute as a {@link JsonElement}.
 	 */
@@ -182,6 +183,9 @@ static JsonElement getAttribute(JsonElement root, final String normalizedAttribu
 	 * <li>String[]</li>
 	 * <li>Object[]</li>
 	 * </ul>
+	 * 
+	 * @param root the json element
+	 * @return the attribute map
 	 */
 	static Map<String, Class<?>> listAttributes(final JsonElement root) throws N5Exception.N5IOException {
 
@@ -319,8 +323,8 @@ static <T> T getJsonAsArray(final Gson gson, final JsonArray array, final Type t
 	 * <li>Object</li>
 	 * </ul>
 	 *
-	 * @param jsonPrimitive
-	 * @return
+	 * @param jsonPrimitive the json primitive
+	 * @return the class
 	 */
 	static Class<?> classForJsonPrimitive(final JsonPrimitive jsonPrimitive) {
 
@@ -339,12 +343,12 @@ else if (jsonPrimitive.isNumber()) {
 	}
 
 	/**
-	 * If there is an attribute in {@code root} such that it can be parsed and desrialized as {@link T},
+	 * If there is an attribute in {@code root} such that it can be parsed and deserialized as {@code T},
 	 * then remove it from {@code root}, write {@code root} to the {@code writer}, and return the removed attribute.
 	 * <p>
-	 * If there is an attribute at the location specified by {@code normalizedAttributePath} but it cannot be deserialized to {@link T}, then it is not removed.
+	 * If there is an attribute at the location specified by {@code normalizedAttributePath} but it cannot be deserialized to {@code T}, then it is not removed.
 	 * <p>
-	 * If nothing is removed, then {@code root} is not writen to the {@code writer}.
+	 * If nothing is removed, then {@code root} is not written to the {@code writer}.
 	 *
 	 * @param writer                  to write the modified {@code root} to after removal of the attribute
 	 * @param root                    to remove the attribute from
@@ -353,7 +357,7 @@ else if (jsonPrimitive.isNumber()) {
 	 * @param gson                    to deserialize the attribute with
 	 * @param <T>                     of the removed attribute
 	 * @return the removed attribute, or null if nothing removed
-	 * @throws IOException
+	 * @throws IOException the exception
 	 */
 	static <T> T removeAttribute(
 			final Writer writer,
@@ -393,10 +397,10 @@ static boolean removeAttribute(
 	}
 
 	/**
-	 * If there is an attribute in {@code root} such that it can be parsed and desrialized as {@link T},
+	 * If there is an attribute in {@code root} such that it can be parsed and desrialized as {@code T},
 	 * then remove it from {@code root} and return the removed attribute.
 	 * <p>
-	 * If there is an attribute at the location specified by {@code normalizedAttributePath} but it cannot be deserialized to {@link T}, then it is not removed.
+	 * If there is an attribute at the location specified by {@code normalizedAttributePath} but it cannot be deserialized to {@code T}, then it is not removed.
 	 *
 	 * @param root                    to remove the attribute from
 	 * @param normalizedAttributePath to the attribute location
@@ -463,12 +467,13 @@ static JsonElement removeAttribute(JsonElement root, final String normalizedAttr
 	 * <p>
 	 * If {@code root} is not a {@link JsonObject}, then it is overwritten with an object containing {@code "normalizedAttributePath": attribute }
 	 *
-	 * @param writer
-	 * @param root
-	 * @param normalizedAttributePath
-	 * @param attribute
-	 * @param gson
-	 * @throws IOException
+	 * @param writer the writer
+	 * @param root the root json element
+	 * @param normalizedAttributePath the attribute path
+	 * @param attribute the attribute
+	 * @param gson the gson
+	 * @param <T> the attribute type
+	 * @throws IOException the exception
 	 */
 	static <T> void writeAttribute(
 			final Writer writer,
@@ -485,9 +490,11 @@ static <T> void writeAttribute(
 	 * Writes the attributes JsonElemnt to a given {@link Writer}.
 	 * This will overwrite any existing attributes.
 	 *
-	 * @param writer
-	 * @param root
-	 * @throws IOException
+	 * @param writer the writer
+	 * @param root the root json element
+	 * @param gson the gson
+	 * @param <T> the attribute type
+	 * @throws IOException the exception
 	 */
 	static <T> void writeAttributes(
 			final Writer writer,