HashStore-java 1.1.0 Release

README.md

@@ -24,6 +24,45 @@ and then install or build the package with `mvn install` or `mvn package`, respe
 
 We also maintain a parallel [Python-based version of HashStore](https://github.com/DataONEorg/hashstore).
 
+## HashStore CommandLineTool Usage
+
+```sh
+
+# Step 1: Get HashStore Jar file
+$ mvn clean package -Dmaven.test.skip=true
+
+# Get help
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -h
+
+# Step 2:
+## Create a HashStore (long option)
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool --createhashstore --storepath=/path/to/store --storedepth=3 --storewidth=2 --storealgo=SHA-256 --storenamespace=http://ns.dataone.org/service/types/v2.0
+
+## Create a HashStore (short option)
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -chs -store /path/to/store -dp 3 -wp 2 -ap SHA-256 -nsp http://ns.dataone.org/service/types/v2
+
+# Get the checksum of a data object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -getchecksum -pid testpid1 -algo SHA-256
+
+# Store a data object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -storeobject -path /path/to/data.ext -pid testpid1
+
+# Store a metadata object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -storemetadata -path /path/to/metadata.ext -pid testpid1 -format_id http://ns.dataone.org/service/types/v2
+
+# Retrieve a data object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -retrieveobject -pid testpid1
+
+# Retrieve a metadata object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -retrievemetadata -pid testpid1 -format_id http://ns.dataone.org/service/types/v2
+
+# Delete a data object
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -deleteobject -pid testpid1
+
+# Delete a metadata file
+$ java -cp ./target/hashstore-1.0-SNAPSHOT.jar org.dataone.hashstore.CommandLineTool -store /path/to/store -deletemetadata -pid testpid1 -format_id http://ns.dataone.org/service/types/v2
+```
+
 ## License
 
 ```txt

pom.xml

@@ -10,8 +10,7 @@
   <version>1.0-SNAPSHOT</version>
 
   <name>hashstore</name>
-  <!-- FIXME change it to the project's website -->
-  <url>http://www.example.com</url>
+  <url>https://github.com/DataONEorg/hashstore-java</url>
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@@ -26,9 +25,20 @@
       <version>1.2</version>
     </dependency>
     <dependency>
-      <groupId>junit</groupId>
-      <artifactId>junit</artifactId>
-      <version>4.13.2</version>
+      <groupId>commons-cli</groupId>
+      <artifactId>commons-cli</artifactId>
+      <version>1.5.0</version>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <version>5.8.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>5.8.2</version>
       <scope>test</scope>
     </dependency>
     <dependency>
@@ -39,19 +49,88 @@
     <dependency>
       <groupId>com.fasterxml.jackson.dataformat</groupId>
       <artifactId>jackson-dataformat-yaml</artifactId>
-      <version>2.12.2</version>
+      <version>2.15.2</version>
     </dependency>
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.15.2</version>
     </dependency>
+    <dependency>
+      <groupId>org.postgresql</groupId>
+      <artifactId>postgresql</artifactId>
+      <version>42.4.3</version>
+    </dependency>
   </dependencies>
 
   <build>
-    <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to
-      parent pom) -->
+    <!-- <pluginManagement> -->
       <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>3.8.1</version>
+          <configuration>
+              <source>8</source>
+              <target>8</target>
+          </configuration>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-shade-plugin</artifactId>
+          <version>3.2.1</version>
+          <executions>
+            <execution>
+              <phase>package</phase>
+              <goals>
+                  <goal>shade</goal>
+              </goals>
+              <configuration>
+                <transformers>
+                  <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                    <manifestEntries>
+                        <Main-Class>org.dataone.hashstore.Client</Main-Class>
+                        <Build-Number>${project.version}</Build-Number>
+                    </manifestEntries>
+                  </transformer>
+                </transformers>
+                <!--
+                See https://issues.apache.org/jira/browse/LOG4J2-673
+                and https://stackoverflow.com/questions/48033792/log4j2-error-statuslogger-unrecognized-conversion-specifier
+                -->
+                <filters>
+                  <filter>
+                    <artifact>*:*</artifact>
+                    <excludes>
+                        <exclude>**/Log4j2Plugins.dat</exclude>
+                    </excludes>
+                  </filter>
+                  <filter>
+                      <artifact>*:*</artifact>
+                      <excludes>
+                        <exclude>META-INF/*.SF</exclude>
+                        <exclude>META-INF/*.DSA</exclude>
+                        <exclude>META-INF/*.RSA</exclude>
+                      </excludes>
+                  </filter>
+                </filters>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
+        <plugin>
+            <artifactId>maven-jar-plugin</artifactId>
+            <version>3.3.0</version>
+            <executions>
+                <execution>
+                    <id>default-jar</id>
+                    <phase>package</phase>
+                    <goals>
+                        <goal>jar</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
         <!-- clean lifecycle, see
         https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
         <plugin>
@@ -64,17 +143,14 @@
           <artifactId>maven-resources-plugin</artifactId>
           <version>3.3.0</version>
         </plugin>
-        <plugin>
-          <artifactId>maven-compiler-plugin</artifactId>
-          <version>3.11.0</version>
-        </plugin>
         <plugin>
           <artifactId>maven-surefire-plugin</artifactId>
-          <version>2.22.1</version>
-        </plugin>
-        <plugin>
-          <artifactId>maven-jar-plugin</artifactId>
-          <version>3.3.0</version>
+          <version>3.1.2</version>
+          <!-- Adjust forkCount to speed up tests if desired -->
+          <!-- <configuration>
+            <forkCount>1</forkCount>
+            <reuseForks>false</reuseForks>
+          </configuration> -->
         </plugin>
         <plugin>
           <artifactId>maven-install-plugin</artifactId>
@@ -95,6 +171,6 @@
           <version>3.4.2</version>
         </plugin>
       </plugins>
-    </pluginManagement>
+    <!-- </pluginManagement> -->
   </build>
 </project>

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

@@ -16,12 +16,12 @@
  */
 public interface HashStore {
         /**
-         * The `storeObject` method is responsible for the atomic storage of objects to HashStore
-         * using a given InputStream and a persistent identifier (pid). Upon successful storage, the
-         * method returns an 'ObjectInfo' object containing the object's file information, such
-         * as the id, file size, and hex digest map of algorithms and hex digests/checksums. An
-         * object is stored once and only once - and `storeObject` also enforces this rule by
-         * synchronizing multiple calls and rejecting calls to store duplicate objects.
+         * Atomically stores objects to HashStore using a given InputStream and a persistent
+         * identifier (pid). Upon successful storage, the method returns an 'ObjectInfo' object
+         * containing the object's file information, such as the id, file size, and hex digest map
+         * of algorithms and hex digests/checksums. An object is stored once and only once - and
+         * `storeObject` also enforces this rule by synchronizing multiple calls and rejecting calls
+         * to store duplicate objects.
          * 
          * The file's id is determined by calculating the SHA-256 hex digest of the provided pid,
          * which is also used as the permanent address of the file. The file's identifier is then
@@ -60,10 +60,31 @@ ObjectInfo storeObject(
         ) throws NoSuchAlgorithmException, IOException, PidObjectExistsException, RuntimeException;
 
         /**
-         * The `storeMetadata` method is responsible for adding/updating metadata (ex. `sysmeta`) to
-         * the HashStore by using a given InputStream, a persistent identifier (`pid`) and metadata
-         * format (`formatId`). The permanent address of the stored metadata document is determined
-         * by calculating the SHA-256 hex digest of the provided `pid` + `formatId`.
+         * @see #storeObject(InputStream, String, String, String, String, long)
+         */
+        ObjectInfo storeObject(
+                InputStream object, String pid, String checksum, String checksumAlgorithm
+        ) throws NoSuchAlgorithmException, IOException, PidObjectExistsException, RuntimeException;
+
+        /**
+         * @see #storeObject(InputStream, String, String, String, String, long)
+         */
+        ObjectInfo storeObject(InputStream object, String pid, String additionalAlgorithm)
+                throws NoSuchAlgorithmException, IOException, PidObjectExistsException,
+                RuntimeException;
+
+        /**
+         * @see #storeObject(InputStream, String, String, String, String, long)
+         */
+        ObjectInfo storeObject(InputStream object, String pid, long objSize)
+                throws NoSuchAlgorithmException, IOException, PidObjectExistsException,
+                RuntimeException;
+
+        /**
+         * Adds/updates metadata (ex. `sysmeta`) to the HashStore by using a given InputStream, a
+         * persistent identifier (`pid`) and metadata format (`formatId`). The permanent address of
+         * the stored metadata document is determined by calculating the SHA-256 hex digest of the
+         * provided `pid` + `formatId`.
          * 
          * Note, multiple calls to store the same metadata content will all be accepted, but is not
          * guaranteed to execute sequentially.
@@ -85,8 +106,14 @@ String storeMetadata(InputStream metadata, String pid, String formatId) throws I
                 NoSuchAlgorithmException;
 
         /**
-         * The `retrieveObject` method retrieves an object from HashStore using a given persistent
-         * identifier (pid).
+         * @see #storeMetadata(InputStream, String, String)
+         */
+        String storeMetadata(InputStream metadata, String pid) throws IOException,
+                IllegalArgumentException, FileNotFoundException, InterruptedException,
+                NoSuchAlgorithmException;
+
+        /**
+         * Returns an InputStream to an object from HashStore using a given persistent identifier.
          * 
          * @param pid Authority-based identifier
          * @return Object InputStream
@@ -100,8 +127,8 @@ InputStream retrieveObject(String pid) throws IllegalArgumentException,
                 FileNotFoundException, IOException, NoSuchAlgorithmException;
 
         /**
-         * The 'retrieveMetadata' method retrieves the metadata content of a given pid and metadata
-         * namespace from HashStore.
+         * Returns an InputStream to the metadata content of a given pid and metadata namespace from
+         * HashStore.
          * 
          * @param pid      Authority-based identifier
          * @param formatId Metadata namespace/format
@@ -112,40 +139,41 @@ InputStream retrieveObject(String pid) throws IllegalArgumentException,
          * @throws NoSuchAlgorithmException When algorithm used to calculate metadata address is not
          *                                  supported
          */
-        InputStream retrieveMetadata(String pid, String formatId) throws Exception;
+        InputStream retrieveMetadata(String pid, String formatId) throws IllegalArgumentException,
+                FileNotFoundException, IOException, NoSuchAlgorithmException;
 
         /**
-         * The 'deleteObject' method deletes an object (and its empty subdirectories) permanently
-         * from HashStore using a given persistent identifier.
+         * Deletes an object (and its empty subdirectories) permanently from HashStore using a given
+         * persistent identifier.
          * 
          * @param pid Authority-based identifier
-         * @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
          */
-        void deleteObject(String pid) throws Exception;
+        void deleteObject(String pid) throws IllegalArgumentException, FileNotFoundException,
+                IOException, NoSuchAlgorithmException;
 
         /**
-         * The 'deleteMetadata' method deletes a metadata document (ex. `sysmeta`) permanently from
-         * HashStore using a given persistent identifier and its respective metadata namespace.
+         * Deletes a metadata document (ex. `sysmeta`) permanently from HashStore using a given
+         * persistent identifier and its respective metadata namespace.
          * 
          * @param pid      Authority-based identifier
          * @param formatId Metadata namespace/format
-         * @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
          */
-        void deleteMetadata(String pid, String formatId) throws Exception;
+        void deleteMetadata(String pid, String formatId) throws IllegalArgumentException,
+                FileNotFoundException, IOException, NoSuchAlgorithmException;
 
         /**
-         * The 'getHexDigest' method calculates the hex digest of an object that exists in HashStore
-         * using a given persistent identifier and hash algorithm.
+         * Calculates the hex digest of an object that exists in HashStore using a given persistent
+         * identifier and hash algorithm.
          * 
          * @param pid       Authority-based identifier
          * @param algorithm Algorithm of desired hex digest
@@ -156,5 +184,6 @@ InputStream retrieveObject(String pid) throws IllegalArgumentException,
          * @throws NoSuchAlgorithmException When algorithm used to calculate object address is not
          *                                  supported
          */
-        String getHexDigest(String pid, String algorithm) throws Exception;
+        String getHexDigest(String pid, String algorithm) throws IllegalArgumentException,
+                FileNotFoundException, IOException, NoSuchAlgorithmException;
 }