Merge pull request #256 from kit-data-manager/make-spec-examples-executable

Make specification examples (from readme) executable

Author: Pfeil

.github/workflows/gradle.yml

@@ -11,7 +11,6 @@ on:
   push:
     branches: [ main, development ]
   pull_request:
-    branches: [ main, development ]
   workflow_dispatch:
 
 env:

README.md

@@ -10,13 +10,10 @@
 import edu.kit.datamanager.ro_crate.entities.AbstractEntity;
 import edu.kit.datamanager.ro_crate.entities.contextual.ContextualEntity;
 import edu.kit.datamanager.ro_crate.entities.contextual.JsonDescriptor;
-import edu.kit.datamanager.ro_crate.entities.contextual.OrganizationEntity;
 import edu.kit.datamanager.ro_crate.entities.data.DataEntity;
-import edu.kit.datamanager.ro_crate.entities.data.DataEntity.DataEntityBuilder;
-import edu.kit.datamanager.ro_crate.entities.data.FileEntity;
+
 import edu.kit.datamanager.ro_crate.entities.data.RootDataEntity;
 import edu.kit.datamanager.ro_crate.externalproviders.dataentities.ImportFromDataCite;
-import edu.kit.datamanager.ro_crate.externalproviders.organizationprovider.RorProvider;
 import edu.kit.datamanager.ro_crate.objectmapper.MyObjectMapper;
 import edu.kit.datamanager.ro_crate.payload.CratePayload;
 import edu.kit.datamanager.ro_crate.payload.RoCratePayload;
@@ -26,12 +23,9 @@
 import edu.kit.datamanager.ro_crate.special.JsonUtilFunctions;
 import edu.kit.datamanager.ro_crate.validation.JsonSchemaValidation;
 import edu.kit.datamanager.ro_crate.validation.Validator;
-import edu.kit.datamanager.ro_crate.writer.FolderWriter;
-import edu.kit.datamanager.ro_crate.writer.RoCrateWriter;
 
 import java.io.File;
 import java.net.URI;
-import java.nio.file.Paths;
 import java.util.*;
 import java.util.stream.Collectors;
 import java.util.stream.StreamSupport;
@@ -354,6 +348,18 @@ public RoCrateBuilder addName(String name) {
             return this;
         }
 
+        /**
+         * Adds an "identifier" property to the root data entity.
+         * <p>
+         * This is useful e.g. to assign e.g. a DOI to this crate.
+         * @param identifier the identifier to add.
+         * @return this builder.
+         */
+        public RoCrateBuilder addIdentifier(String identifier) {
+            this.rootDataEntity.addProperty("identifier", identifier.strip());
+            return this;
+        }
+
         public RoCrateBuilder addDescription(String description) {
             this.rootDataEntity.addProperty(PROPERTY_DESCRIPTION, description);
             return this;

src/main/java/edu/kit/datamanager/ro_crate/RoCrate.java

@@ -239,33 +239,60 @@ private static boolean addProperty(ObjectNode whereToAdd, String key, JsonNode v
      * @param id the "id" of the property.
      */
     public void addIdProperty(String name, String id) {
-        JsonNode jsonNode = addToIdProperty(name, id, this.properties.get(name));
-        if (jsonNode != null) {
-            this.linkedTo.add(id);
-            this.properties.set(name, jsonNode);
-            this.notifyObservers();
-        }
+        mergeIdIntoValue(id, this.properties.get(name))
+                .ifPresent(newValue -> {
+                    this.linkedTo.add(id);
+                    this.properties.set(name, newValue);
+                    this.notifyObservers();
+                });
     }
 
-    private static JsonNode addToIdProperty(String name, String id, JsonNode property) {
-        ObjectMapper objectMapper = MyObjectMapper.getMapper();
-        if (name != null && id != null) {
-            if (property == null) {
-                return objectMapper.createObjectNode().put("@id", id);
-            } else {
-                if (property.isArray()) {
-                    ArrayNode ns = (ArrayNode) property;
-                    ns.add(objectMapper.createObjectNode().put("@id", id));
-                    return ns;
-                } else {
-                    ArrayNode newNodes = objectMapper.createArrayNode();
-                    newNodes.add(property);
-                    newNodes.add(objectMapper.createObjectNode().put("@id", id));
-                    return newNodes;
-                }
-            }
+    /**
+     * Merges the given id into the current value,
+     * using this representation: {"@id" : "id"}.
+     * <p>
+     * The current value can be null without errors.
+     * Only the id will be considered in this case.
+     * <p>
+     * If the id is null-ish, it will not be added, similar to a null-ish value.
+     * If the id is already present, nothing will be done.
+     * If it is not an array and the id is not present, an array will be applied.
+     *
+     * @param id the id to add.
+     * @param currentValue the current value of the property.
+     * @return The updated value of the property.
+     *               Empty if value does not change!
+     */
+    private static Optional<JsonNode> mergeIdIntoValue(String id, JsonNode currentValue) {
+        if (id == null || id.isBlank()) { return Optional.empty(); }
+
+        ObjectMapper jsonBuilder = MyObjectMapper.getMapper();
+        ObjectNode newIdObject = jsonBuilder.createObjectNode().put("@id", id);
+        if (currentValue == null || currentValue.isNull() || currentValue.isMissingNode()) {
+            return Optional.ofNullable(newIdObject);
+        }
+
+        boolean isIdAlready = currentValue.asText().equals(id);
+        boolean isIdObjectAlready = currentValue.path("@id").asText().equals(id);
+        boolean isArrayWithIdPresent = currentValue.valueStream()
+                .anyMatch(node -> node
+                        .path("@id")
+                        .asText()
+                        .equals(id));
+        if (isIdAlready || isIdObjectAlready || isArrayWithIdPresent) {
+            return Optional.empty();
+        }
+
+        if (currentValue.isArray() && currentValue instanceof ArrayNode currentValueAsArray) {
+            currentValueAsArray.add(newIdObject);
+            return Optional.of(currentValueAsArray);
+        } else {
+            // property is not an array, so we make it an array
+            ArrayNode newNodes = jsonBuilder.createArrayNode();
+            newNodes.add(currentValue);
+            newNodes.add(newIdObject);
+            return Optional.of(newNodes);
         }
-        return null;
     }
 
     /**
@@ -369,6 +396,11 @@ protected String getId() {
         /**
          * Setting the id property of the entity, if the given value is not
          * null. If the id is not encoded, the encoding will be done.
+         * <p>
+         * <b>NOTE: IDs are not just names!</b> The ID may have effects
+         * on parts of your crate! For example: If the entity represents a
+         * file which will be copied into the crate, writers must use the
+         * ID as filename.
          *
          * @param id the String representing the id.
          * @return the generic builder.
@@ -486,11 +518,11 @@ public T addProperty(String key, boolean value) {
          * @return the generic builder
          */
         public T addIdProperty(String name, String id) {
-            JsonNode jsonNode = AbstractEntity.addToIdProperty(name, id, this.properties.get(name));
-            if (jsonNode != null) {
-                this.properties.set(name, jsonNode);
-                this.relatedItems.add(id);
-            }
+            AbstractEntity.mergeIdIntoValue(id, this.properties.get(name))
+                    .ifPresent(newValue -> {
+                        this.properties.set(name, newValue);
+                        this.relatedItems.add(id);
+                    });
             return self();
         }
 

src/main/java/edu/kit/datamanager/ro_crate/entities/AbstractEntity.java

@@ -3,7 +3,6 @@
 import edu.kit.datamanager.ro_crate.util.ZipUtil;
 import java.io.File;
 import java.io.IOException;
-import java.util.Optional;
 
 import net.lingala.zip4j.ZipFile;
 import net.lingala.zip4j.io.outputstream.ZipOutputStream;
@@ -13,7 +12,7 @@
 /**
  * This class adds a static preview to the crate, which consists of a
  * metadataHtml file and a folder containing other files required to render
- * metadataHtml. If will be put unchanged to the writer output, i.e., a zip
+ * metadataHtml. It will be put unchanged to the writer output, i.e., a zip
  * file, folder, or stream.
  *
  * @author jejkal

src/main/java/edu/kit/datamanager/ro_crate/preview/StaticPreview.java

@@ -4,13 +4,15 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+import com.fasterxml.jackson.databind.SerializationFeature;
 import edu.kit.datamanager.ro_crate.entities.AbstractEntity;
 import edu.kit.datamanager.ro_crate.objectmapper.MyObjectMapper;
 import edu.kit.datamanager.ro_crate.special.JsonUtilFunctions;
 
 import org.apache.commons.io.FileUtils;
 import io.json.compare.JSONCompare;
 import io.json.compare.JsonComparator;
+import org.opentest4j.AssertionFailedError;
 
 import java.io.File;
 import java.io.IOException;
@@ -34,15 +36,15 @@ public static void compareEntityWithFile(AbstractEntity entity, String string) t
 
     public static void compare(JsonNode node1, JsonNode node2, Boolean equals) {
         var comparator = new JsonComparator() {
-        public boolean compareValues(Object expected, Object actual) {
-
+            public boolean compareValues(Object expected, Object actual) {
                 return expected.equals(actual);
             }
 
             public boolean compareFields(String expected, String actual) {
                 return expected.equals(actual);
             }
         };
+
         if (equals) {
             JSONCompare.assertMatches(node1, node2, comparator);
         } else {
@@ -73,13 +75,46 @@ public static void compareTwoCrateJson(Crate crate1, Crate crate2) throws JsonPr
         compare(node1, node2, true);
     }
 
+    public static void prettyPrintJsonString(String minimalJsonMetadata) {
+        try {
+            ObjectMapper objectMapper = new ObjectMapper();
+            JsonNode jsonNode = objectMapper.readTree(minimalJsonMetadata);
+            // Enable pretty printing
+            String prettyJson = objectMapper
+                    .enable(SerializationFeature.INDENT_OUTPUT)
+                    .writeValueAsString(jsonNode);
+            // Print the pretty JSON
+            System.out.println(prettyJson);
+        } catch (JsonProcessingException e) {
+            throw new AssertionFailedError("Not able to process string as JSON!", e);
+        }
+    }
+
+    public static void printAndAssertEquals(RoCrate crate, String pathToResource) {
+        // So you get something to see
+        prettyPrintJsonString(crate.getJsonMetadata());
+        // Compare with the example from the specification
+        try {
+            HelpFunctions.compareCrateJsonToFileInResources(crate, pathToResource);
+        } catch (IOException e) {
+            throw new AssertionFailedError("Missing resources file!", e);
+        }
+    }
+
     public static void compareCrateJsonToFileInResources(File file1, File file2) throws IOException {
         ObjectMapper objectMapper = MyObjectMapper.getMapper();
         JsonNode node1 = JsonUtilFunctions.unwrapSingleArray(objectMapper.readTree(file1));
         JsonNode node2 = JsonUtilFunctions.unwrapSingleArray(objectMapper.readTree(file2));
         compare(node1, node2, true);
     }
 
+    /**
+     * Compares the JSON metadata of a Crate object with a JSON file in the resources directory.
+     *
+     * @param crate1        The Crate object to compare.
+     * @param jsonFileString The path to the JSON file in the resources directory.
+     * @throws IOException If an error occurs while reading the JSON file.
+     */
     public static void compareCrateJsonToFileInResources(Crate crate1, String jsonFileString) throws IOException {
         InputStream inputStream = HelpFunctions.class.getResourceAsStream(
                 jsonFileString);