Merge pull request #31 from DataONEorg/feature-29-delete-methods

Feature-29: Add 'deleteObject', 'deleteMetadata' and 'getHexDigest' Public API Methods

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

@@ -1,5 +1,6 @@
 package org.dataone.hashstore;
 
+import java.nio.file.Path;
 import java.util.Map;
 
 /**
@@ -10,11 +11,11 @@
  * know the underlying file system details.
  */
 public class HashAddress {
-    private String id;
-    private String relPath;
-    private String absPath;
-    private boolean isDuplicate;
-    private Map<String, String> hexDigests;
+    private final String id;
+    private final String relPath;
+    private final Path absPath;
+    private final boolean isDuplicate;
+    private final Map<String, String> hexDigests;
 
     /**
      * Creates a new instance of HashAddress with the given properties.
@@ -27,7 +28,7 @@ public class HashAddress {
      * @param hexDigests  a map of hash algorithm names to their hex-encoded
      *                    digest values for the file
      */
-    public HashAddress(String id, String relPath, String absPath, boolean isDuplicate,
+    public HashAddress(String id, String relPath, Path absPath, boolean isDuplicate,
             Map<String, String> hexDigests) {
         // Constructor implementation
         this.id = id;
@@ -60,7 +61,7 @@ public String getRelPath() {
      * 
      * @return absolute path
      */
-    public String getAbsPath() {
+    public Path getAbsPath() {
         return absPath;
     }
 

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

@@ -105,7 +105,7 @@ String storeMetadata(InputStream metadata, String pid, String formatId)
          * @throws FileNotFoundException    When requested pid has no associated object
          * @throws IOException              I/O error when creating InputStream to
          *                                  object
-         * @throws NoSuchAlgorithmException When algorithm used to calcualte object
+         * @throws NoSuchAlgorithmException When algorithm used to calculate object
          *                                  address is not supported
          */
         InputStream retrieveObject(String pid)
@@ -123,18 +123,22 @@ InputStream retrieveObject(String pid)
          *                                  associated object
          * @throws IOException              I/O error when creating InputStream to
          *                                  metadata
-         * @throws NoSuchAlgorithmException When algorithm used to calcualte metadata
+         * @throws NoSuchAlgorithmException When algorithm used to calculate metadata
          *                                  address is not supported
          */
         InputStream retrieveMetadata(String pid, String formatId) throws Exception;
 
         /**
          * The 'deleteObject' method deletes an object permanently from disk using a
-         * given persistent identifier.
+         * given persistent identifier and any empty subdirectories.
          * 
          * @param pid Authority-based identifier
-         * @return
-         * @throws Exception TODO: Add specific exceptions
+         * @return True if successful
+         * @throws IllegalArgumentException When pid is null or empty
+         * @throws FileNotFoundException    When requested pid has no associated object
+         * @throws IOException              I/O error when deleting empty directories
+         * @throws NoSuchAlgorithmException When algorithm used to calculate object
+         *                                  address is not supported
          */
         boolean deleteObject(String pid) throws Exception;
 
@@ -145,8 +149,12 @@ InputStream retrieveObject(String pid)
          * 
          * @param pid      Authority-based identifier
          * @param formatId Metadata namespace/format
-         * @return
-         * @throws Exception TODO: Add specific exceptions
+         * @return True if successfulÏ
+         * @throws IllegalArgumentException When pid or formatId is null or empty
+         * @throws FileNotFoundException    When requested pid has no metadata
+         * @throws IOException              I/O error when deleting empty directories
+         * @throws NoSuchAlgorithmException When algorithm used to calculate object
+         *                                  address is not supported
          */
         boolean deleteMetadata(String pid, String formatId) throws Exception;
 
@@ -156,8 +164,12 @@ InputStream retrieveObject(String pid)
          * 
          * @param pid       Authority-based identifier
          * @param algorithm Algorithm of desired hex digest
-         * @return
-         * @throws Exception TODO: Add specific exceptions
+         * @return String hex digest of requested pid
+         * @throws IllegalArgumentException When pid or formatId is null or empty
+         * @throws FileNotFoundException    When requested pid object does not exist
+         * @throws IOException              I/O error when calculating hex digests
+         * @throws NoSuchAlgorithmException When algorithm used to calculate object
+         *                                  address is not supported
          */
         String getHexDigest(String pid, String algorithm) throws Exception;
 }

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

@@ -26,8 +26,8 @@ public class HashStoreFactory {
      *                        (int)
      *                        storeAlgorithm
      * 
-     * @return
-     * @throws HashStoreFactoryException When HashStore fails to initialize due to
+     * @return HashStore instance ready to store objects and metadata
+     * @throws HashStoreFactoryException When HashStore failÏs to initialize due to
      *                                   permissions or class-related issues
      * @throws IOException               When there is an issue with properties
      */