Merge pull request #27 from DataONEorg/feature-11-store-metadata

Feature-11: storeMetadata Public API method

src/main/java/org/dataone/hashstore/HashStore.java

@@ -1,6 +1,7 @@
 package org.dataone.hashstore;
 
 import java.io.BufferedReader;
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.security.NoSuchAlgorithmException;
@@ -62,24 +63,37 @@ HashAddress storeObject(InputStream object, String pid, String additionalAlgorit
             throws NoSuchAlgorithmException, IOException, PidObjectExistsException, RuntimeException;
 
     /**
-     * The `storeSysmeta` method is responsible for adding and/or updating metadata
-     * (`sysmeta`) to disk using a given InputStream and a persistent identifier
-     * (pid). The metadata object consists of a header and body portion. The header
-     * is formed by writing the namespace/format (utf-8) of the metadata document
-     * followed by a null character `\x00` and the body follows immediately after.
+     * The `storeMetadata` method is responsible for adding/updating metadata
+     * (ex. `sysmeta`) to disk using a given InputStream, a persistent identifier
+     * (pid) and metadata format (formatId). The metadata object consists of a
+     * header and body portion. The header is formed by writing the namespace/format
+     * (utf-8) of the metadata document followed by a null character `\u0000` and
+     * the body (metadata content) follows immediately after.
      * 
-     * Upon successful storage of sysmeta, the method returns a String that
-     * represents the file's permanent address, and similarly to storeObject, this
-     * permanent address is determined by calculating the SHA-256 hex digest of the
-     * provided pid. Finally, sysmeta are stored in parallel to objects in the
-     * `/[...storeDirectory]/sysmeta/` directory.
+     * The permanent address of the metadata document is determined by calculating
+     * the SHA-256 hex digest of the provided `pid` + `format_id`; and the body
+     * contains the metadata content (ex. `sysmeta`).
      * 
-     * @param sysmeta Input stream to metadata document
-     * @param pid     Authority-based identifier
-     * @return String representing metadata address
-     * @throws Exception TODO: Add specific exceptions
+     * Upon successful storage of metadata, `store_metadata` returns a string that
+     * represents the file's permanent address. Lastly, the metadata objects are
+     * stored in parallel to objects in the `/store_directory/metadata/` directory.
+     * 
+     * @param metadata Input stream to metadata document
+     * @param pid      Authority-based identifier
+     * @param formatId Metadata namespace/format
+     * @return Metadata content identifier (string representing metadata address)
+     * @throws IOException              When there is an error writing the metadata
+     *                                  document
+     * @throws IllegalArgumentException Invalid values like null for metadata, or
+     *                                  empty pids and formatIds
+     * @throws FileNotFoundException    When temp metadata file is not found
+     * @throws InterruptedException     metadataLockedIds synchronization issue
+     * @throws NoSuchAlgorithmException Algorithm used to calculate permanent
+     *                                  address is not supported
      */
-    String storeSysmeta(InputStream sysmeta, String pid) throws Exception;
+    String storeMetadata(InputStream metadata, String pid, String formatId)
+            throws IOException, IllegalArgumentException, FileNotFoundException, InterruptedException,
+            NoSuchAlgorithmException;
 
     /**
      * The `retrieveObject` method retrieves an object from disk using a given
@@ -94,14 +108,15 @@ HashAddress storeObject(InputStream object, String pid, String additionalAlgorit
     BufferedReader retrieveObject(String pid) throws Exception;
 
     /**
-     * The 'retrieveSysmeta' method retrieves the metadata content from disk and
-     * returns it in the form of a String using a given persistent identifier.
+     * The 'retrieveMetadata' method retrieves the metadata content of a given pid
+     * and metadata namespace from disk and returns it in the form of a String.
      * 
-     * @param pid Authority-based identifier
+     * @param pid      Authority-based identifier
+     * @param formatId Metadata namespace/format
      * @return Sysmeta (metadata) document of given pid
      * @throws Exception TODO: Add specific exceptions
      */
-    String retrieveSysmeta(String pid) throws Exception;
+    String retrieveMetadata(String pid, String formatId) throws Exception;
 
     /**
      * The 'deleteObject' method deletes an object permanently from disk using a
@@ -114,14 +129,16 @@ HashAddress storeObject(InputStream object, String pid, String additionalAlgorit
     boolean deleteObject(String pid) throws Exception;
 
     /**
-     * The 'deleteSysmeta' method deletes an metadata document (sysmeta) permanently
-     * from disk using a given persistent identifier.
+     * The 'deleteMetadata' method deletes a metadata document (ex. `sysmeta`)
+     * permanently from disk using a given persistent identifier and its respective
+     * metadata namespace.
      * 
-     * @param pid Authority-based identifier
+     * @param pid      Authority-based identifier
+     * @param formatId Metadata namespace/format
      * @return
      * @throws Exception TODO: Add specific exceptions
      */
-    boolean deleteSysmeta(String pid) throws Exception;
+    boolean deleteMetadata(String pid, String formatId) throws Exception;
 
     /**
      * The 'getHexDigest' method calculates the hex digest of an object that exists