Merge pull request #279 from kit-data-manager/development

Next Version (2.1.0-rc4)

Author: Pfeil

.github/workflows/codeql-analysis.yml

@@ -38,11 +38,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -56,7 +56,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      uses: github/codeql-action/autobuild@v4
 
     # Command-line programs to run using the OS shell.
     # See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -69,4 +69,4 @@ jobs:
     #   ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4

.github/workflows/gradle.yml

@@ -25,21 +25,21 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Set up openJDK version
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: ${{ matrix.jdk }}
         distribution: 'zulu'
     - name: Install Dependencies
       run: npm install -g ro-crate-html-js
     - name: Setup Gradle
-      uses: gradle/actions/setup-gradle@v4
+      uses: gradle/actions/setup-gradle@v5
     - name: Build and Test with Gradle
       run: ./gradlew -Dprofile=release build
     - name: Upload (test) reports as artifact on GitHub on manual runs
       if: github.event_name == 'workflow_dispatch'
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: test-report ${{ matrix.os }} JDK ${{ matrix.jdk }}
         path: build/reports

.github/workflows/publishRelease.yml

@@ -8,9 +8,9 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           java-version: 21
           distribution: 'zulu' # openjdk

.gitignore

@@ -1,3 +1,8 @@
+.classpath
+.project
+.settings
+.tmp
+
 ### VSCode ###
 .vscode/*
 #!.vscode/settings.json

build.gradle

@@ -13,19 +13,21 @@ plugins {
     // Publishing of JAR to Nexus instances (e.g., OSSRH)
     // https://github.com/gradle-nexus/publish-plugin
     id "io.github.gradle-nexus.publish-plugin" version "2.0.0"
-    id "io.freefair.maven-publish-java" version "8.13.1"
+    id "io.freefair.maven-publish-java" version "9.0.0"
 }
 
-group 'edu.kit.datamanager'
+group = 'edu.kit.datamanager'
 description = "A library for easy creation and modification of valid RO-Crates."
 
 println "Running gradle version: $gradle.gradleVersion"
 println "Building ${name} version: ${version}"
 println "JDK version: ${JavaVersion.current()}"
 println "Profile (system property): ${System.getProperty('profile')}"
 
-sourceCompatibility = JavaVersion.VERSION_17
-targetCompatibility = JavaVersion.VERSION_17
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
 
 if (JavaVersion.current() == JavaVersion.VERSION_17) {
     println "Setting encoding to UTF-8 manually"
@@ -38,12 +40,12 @@ repositories {
 }
 
 ext {
-    jacksonVersion  = '2.19.0'
+    jacksonVersion  = '2.20.1'
 }
 
 dependencies {
     // JUnit setup for testing
-    testImplementation(platform("org.junit:junit-bom:5.13.0"))
+    testImplementation(platform("org.junit:junit-bom:6.0.1"))
     testImplementation('org.junit.jupiter:junit-jupiter')
     testRuntimeOnly('org.junit.platform:junit-platform-launcher')
     // JSON object mapping / (de-)serialization
@@ -52,19 +54,19 @@ dependencies {
     // http client
     implementation group: 'org.apache.httpcomponents', name: 'httpclient', version: '4.5.14'
     // common file system operations
-    implementation group: 'commons-io', name: 'commons-io', version: '2.19.0'
+    implementation group: 'commons-io', name: 'commons-io', version: '2.21.0'
     // read from and write to zip files
     implementation group: 'net.lingala.zip4j', name: 'zip4j', version: '2.11.5'
     // compare json documents in tests
-    implementation 'com.github.fslev:json-compare:7.0'
+    implementation 'com.github.fslev:json-compare:7.1'
     // url validator
-    implementation group: 'commons-validator', name: 'commons-validator', version: '1.9.0'
+    implementation group: 'commons-validator', name: 'commons-validator', version: '1.10.0'
     // logging
     implementation group: 'org.slf4j', name: 'slf4j-jdk14', version: '2.0.17'
     // JSON-LD, Zenodo mapping
-    implementation group: 'com.apicatalog', name: 'titanium-json-ld', version: '1.6.0'
+    implementation group: 'com.apicatalog', name: 'titanium-json-ld', version: '1.7.0'
     // metadata validation, profiles based on JSON schema
-    implementation group: "com.networknt", name: "json-schema-validator", version: "1.5.7"
+    implementation group: "com.networknt", name: "json-schema-validator", version: "1.5.9"
     implementation 'org.glassfish:jakarta.json:2.0.1'
     //JTE for template processing
     implementation('gg.jte:jte:3.2.1')
@@ -189,7 +191,7 @@ jacocoTestReport {
 }
 
 jacoco {
-    toolVersion = "0.8.13"
+    toolVersion = "0.8.14"
 }
 
 // maxParallelForks(2)

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

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

@@ -7,9 +7,12 @@
 import java.util.Set;
 
 import edu.kit.datamanager.ro_crate.context.CrateMetadataContext;
+import edu.kit.datamanager.ro_crate.hierarchy.HierarchyRecognitionConfig;
+import edu.kit.datamanager.ro_crate.hierarchy.HierarchyRecognitionResult;
 import edu.kit.datamanager.ro_crate.entities.AbstractEntity;
 import edu.kit.datamanager.ro_crate.entities.contextual.ContextualEntity;
 import edu.kit.datamanager.ro_crate.entities.data.DataEntity;
+import edu.kit.datamanager.ro_crate.entities.data.DataSetEntity;
 import edu.kit.datamanager.ro_crate.entities.data.RootDataEntity;
 import edu.kit.datamanager.ro_crate.preview.CratePreview;
 import edu.kit.datamanager.ro_crate.special.CrateVersion;
@@ -103,15 +106,27 @@ public interface Crate {
 
   String getJsonMetadata();
 
-  DataEntity getDataEntityById(java.lang.String id);
+  /**
+   * Gets a data entity by its ID.
+   * @param id the ID of the data entity
+   * @return the DataEntity with the specified ID or null if not found
+   */
+  DataEntity getDataEntityById(String id);
+
+  /**
+   * Gets a data set entity by its ID.
+   * @param id the ID of the data set entity
+   * @return the DataSetEntity with the specified ID or empty if not found
+   */
+  Optional<DataSetEntity> getDataSetById(String id);
 
   Set<DataEntity> getAllDataEntities();
 
-  ContextualEntity getContextualEntityById(java.lang.String id);
+  ContextualEntity getContextualEntityById(String id);
 
   Set<ContextualEntity> getAllContextualEntities();
 
-  AbstractEntity getEntityById(java.lang.String id);
+  AbstractEntity getEntityById(String id);
 
   /**
    * Adds a data entity to the crate.
@@ -120,12 +135,31 @@ public interface Crate {
    */
   void addDataEntity(DataEntity entity);
 
+  /**
+   * Adds a data entity to the crate with a specified parent ID.
+   * <p>
+   * Consider using
+   * @param entity the DataEntity to add to this crate.
+   * @param parentId the ID of the parent entity. Must not be null.
+   * @throws IllegalArgumentException if parentId is null or not found, or not a DataEntity.
+   */
+  void addDataEntity(DataEntity entity, String parentId) throws IllegalArgumentException;
+
   void addContextualEntity(ContextualEntity entity);
 
   void deleteEntityById(String entityId);
 
   void setUntrackedFiles(Collection<File> files);
 
+  /**
+   * Unsafely adds a collection of entities to the crate.
+   * <p>
+   * WARNING: This method does not perform any checks and may lead to an inconsistent crate state.
+   *
+   * @param entities the collection of entities to add
+   * @deprecated use individual add methods to ensure crate consistency. If you really need an unchecked method, consider creating a subclass or contact us at our issue tracker so we can discuss replacements before removal.
+   */
+  @Deprecated(forRemoval = true)
   void addFromCollection(Collection<? extends AbstractEntity> entities);
 
   void addItemFromDataCite(String locationUrl);
@@ -135,4 +169,26 @@ public interface Crate {
   void deleteUrlFromContext(String url);
 
   Collection<File> getUntrackedFiles();
+
+  /**
+   * Automatically recognizes hierarchical file structure from DataEntity IDs
+   * and connects them using hasPart relationships.
+   * <p>
+   * WARNING: This will not change existing hasPart relationships.
+   *
+   * @param addInverseRelationships if true, also adds isPartOf relationships from child to parent
+   * @return result object containing information about what was processed, as well as potential errors.
+   */
+  HierarchyRecognitionResult createDataEntityFileStructure(boolean addInverseRelationships);
+
+  /**
+   * Automatically recognizes hierarchical file structure from DataEntity IDs
+   * and connects them using hasPart relationships with fine-grained configuration.
+   * <p>
+   * Note: Only processes IDs that appear to be relative file paths.
+   *
+   * @param config configuration object specifying how the recognition should behave
+   * @return result object containing information about what was processed, as well as potential errors.
+   */
+  HierarchyRecognitionResult createDataEntityFileStructure(HierarchyRecognitionConfig config);
 }