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

Version 2.1.0

Author: Pfeil

.github/workflows/gradle.yml

@@ -18,9 +18,7 @@ env:
   COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
 
 jobs:
-  # avoid double CI runs on push and PR, from https://github.com/orgs/community/discussions/57827
   build:
-    if: github.event_name != 'push' || github.event.push.head.repo.full_name != github.event.push.base.repo.full_name
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
@@ -49,3 +47,6 @@ jobs:
     - name: Do one Coveralls test report
       if: matrix.os == 'ubuntu-latest' && matrix.jdk == 21
       run: ./gradlew -Dprofile=release jacocoTestReport coveralls
+    - name: Compile Javadoc
+      if: matrix.os == 'ubuntu-latest' && matrix.jdk == 21
+      run: ./gradlew javadoc

.gitignore

@@ -169,4 +169,7 @@ gradle-app.setting
 # gradle/wrapper/gradle-wrapper.properties
 
 ### Gradle Patch ###
+.DS_Store
 **/build/
+**/jte-classes
+**/temp

README.md

@@ -117,18 +117,24 @@ PersonEntity person = ORCIDProvider.getPerson("https://orcid.org/*")
 OrganizationEntity organization = RORProvider.getOrganization("https://ror.org/*");
 ```
 
-### Writing Crate to folder or zip file
+### Writing Crate to folder, zip file, or zip stream
 
 Writing to folder:
 ```java
 RoCrateWriter folderRoCrateWriter = new RoCrateWriter(new FolderWriter());
-folderRoCrateWriter.save(roCrate, "destination");
+folderRoCrateWriter.save(roCrate, "destinationFolder");
 ```
 
 Writing to zip file:
 ```java
 RoCrateWriter roCrateZipWriter = new RoCrateWriter(new ZipWriter());
-roCrateZipWriter.save(roCrate, "destination");
+roCrateZipWriter.save(roCrate, "destinationFolder");
+```
+
+Writing to zip stream:
+```java
+RoCrateWriter roCrateZipStreamWriter = new RoCrateWriter(new ZipStreamWriter());
+roCrateZipStreamWriter.save(roCrate, outputStream);
 ```
 
 More writing strategies can be implemented, if required.
@@ -138,25 +144,48 @@ More writing strategies can be implemented, if required.
 Reading from folder:
 ```java
 RoCrateReader roCrateFolderReader = new RoCrateReader(new FolderReader());
-RoCrate res = roCrateFolderReader.readCrate("source");
+RoCrate res = roCrateFolderReader.readCrate("destinationFolder");
 ```
 
 Reading from zip file:
 ```java
 RoCrateReader roCrateFolderReader = new RoCrateReader(new ZipReader());
-RoCrate crate = roCrateFolderReader.readCrate("source");
+RoCrate crate = roCrateFolderReader.readCrate("sourceZipFile");
+```
+
+Reading from zip stream:
+```java
+RoCrateReader roCrateFolderReader = new RoCrateReader(new ZipStreamReader());
+RoCrate crate = roCrateFolderReader.readCrate(inputStream);
 ```
 
 ### RO-Crate Website (HTML preview file)
-By setting the preview to an `AutomaticPreview`, the library will automatically create a preview using the [ro-crate-html-js](https://www.npmjs.com/package/ro-crate-html-js) tool.
-It has to be installed using `npm install --global ro-crate-html-js` in order to use it.
-If you want to use a custom-made preview, you can set it using the `CustomPreview` class. `AutomaticPreview` is currently **not** set by default.
+ro-crate-java offers tree different kinds of previews:
+
+* AutomaticPreview: Uses third-party library [ro-crate-html-js](https://www.npmjs.com/package/ro-crate-html-js), which must be installed separately. 
+* CustomPreview: Pure Java-based preview using an included template processed by the FreeMarker template engine. At the same time, CustomPreview is the fallback for AutomaticPreview if ro-crate-html-js is not installed.
+* StaticPreview: Allows to provide a static HTML page (including additional dependencies, e.g., CSS, JS) which is then shipped with the RO-Crate. 
+
+When creating a new RO-Crate using the builder, the default setting is to use CustomPreview. If you want to change this behaviour, thr preview method is set as follows: 
+
 ```java
 RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier")
     .setPreview(new AutomaticPreview())
     .build();
 ```
 
+Keep in mind that, if you want to use AutomaticPreview, you have to install ro-crate-html-js via `npm install --global ro-crate-html-js` first. 
+
+For StaticPreview, the constuctor is a bit different, such that it looks as follows: 
+
+```java
+File pathToMainPreviewHtml = new File("localPath");
+File pathToAdditionalFiles = new File("localFolder");
+RoCrate roCrate = new RoCrateBuilder("name", "description", "datePublished", "licenseIdentifier")
+    .setPreview(new StaticPreview(pathToMainPreviewHtml, pathToAdditionalFiles))
+    .build();
+```
+
 ### RO-Crate validation (machine-readable crate profiles)
 Right now, the only implemented way of validating a RO-crate is to use a [JSON-Schema](https://json-schema.org/) that the crates metadata JSON file should match. JSON-Schema is an established standard and therefore a good choice for a crate profile. Example:
 
@@ -395,8 +424,6 @@ The web resource does not use `.setSource()`, but uses the ID to indicate the fi
         {"@id": "data2.txt"}
       ]
     },
-
-
     {
       "@id": "data1.txt",
       "@type": "File",
@@ -637,7 +664,6 @@ If there is no special method for including relative entities (ID properties) on
         .addIdProperty("additionalType", nucSec)
         .addIdProperty("encodingFormat", fasta)
         .build();
-
     ContextualEntity clnParam = new ContextualEntity.ContextualEntityBuilder()
         .addType("FormalParameter")
         .setId("#6c703fee-6af7-4fdb-a57d-9e8bc4486044")
@@ -646,7 +672,6 @@ If there is no special method for including relative entities (ID properties) on
         .addIdProperty("additionalType", nucSec)
         .addIdProperty("encodingFormat", ban)
         .build();
-
     ContextualEntity alignParam = new ContextualEntity.ContextualEntityBuilder()
         .addType("FormalParameter")
         .setId("#2f32b861-e43c-401f-8c42-04fd84273bdf")

build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'java'
     id 'jvm-test-suite'
-
+    id 'application'
     id 'jacoco'
     // Adds coveralls task for CI to send results to the coveralls service.
     id "com.github.kt3k.coveralls" version "2.12.2"
@@ -13,7 +13,7 @@ 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"
+    id "io.freefair.maven-publish-java" version "8.13.1"
 }
 
 group 'edu.kit.datamanager'
@@ -24,6 +24,9 @@ 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
+
 if (JavaVersion.current() == JavaVersion.VERSION_17) {
     println "Setting encoding to UTF-8 manually"
     compileJava.options.encoding = "UTF-8"
@@ -40,7 +43,7 @@ ext {
 
 dependencies {
     // JUnit setup for testing
-    testImplementation(platform("org.junit:junit-bom:5.12.1"))
+    testImplementation(platform("org.junit:junit-bom:5.12.2"))
     testImplementation('org.junit.jupiter:junit-jupiter')
     testRuntimeOnly('org.junit.platform:junit-platform-launcher')
     // JSON object mapping / (de-)serialization
@@ -49,11 +52,11 @@ 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.18.0'
+    implementation group: 'commons-io', name: 'commons-io', version: '2.19.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:6.18'
+    implementation 'com.github.fslev:json-compare:7.0'
     // url validator
     implementation group: 'commons-validator', name: 'commons-validator', version: '1.9.0'
     // logging
@@ -63,8 +66,13 @@ dependencies {
     // metadata validation, profiles based on JSON schema
     implementation group: "com.networknt", name: "json-schema-validator", version: "1.5.6"
     implementation 'org.glassfish:jakarta.json:2.0.1'
+    //JTE for template processing
+    implementation('gg.jte:jte:3.2.0')
+    implementation("org.freemarker:freemarker:2.3.34")
 }
 
+logging.captureStandardOutput LogLevel.INFO
+
 def signingTasks = tasks.withType(Sign)
 tasks.withType(AbstractPublishToMaven).configureEach{
     mustRunAfter(signingTasks)
@@ -155,7 +163,7 @@ jacocoTestReport {
 }
 
 jacoco {
-    toolVersion = "0.8.12"
+    toolVersion = "0.8.13"
 }
 
 // maxParallelForks(2)

gradle.properties

@@ -1 +1,7 @@
-version=2.0.3
+version=2.0.3
+action.custom-1=install
+action.custom-1.args=--configure-on-demand -w -x check clean publishToMavenLocal
+action.custom-2=jacoco
+action.custom-2.args=--configure-on-demand -w clean check jacocoTestReport
+action.custom-3=releaseNewVersion
+action.custom-3.args=--configure-on-demand -w -x check -Prelease release

ro-crate-metadata.json

@@ -0,0 +1,22 @@
+{
+  "@context" : "https://w3id.org/ro/crate/1.1/context",
+  "@graph" : [ {
+    "name" : "name",
+    "description" : "description",
+    "@id" : "./",
+    "@type" : "Dataset",
+    "license" : {
+      "@id" : "https://creativecommons.org/licenses/by-nc-sa/3.0/au/"
+    },
+    "datePublished" : "2024"
+  }, {
+    "about" : {
+      "@id" : "./"
+    },
+    "conformsTo" : {
+      "@id" : "https://w3id.org/ro/crate/1.1"
+    },
+    "@id" : "ro-crate-metadata.json",
+    "@type" : "CreativeWork"
+  } ]
+}

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

@@ -2,6 +2,7 @@
 
 import java.io.File;
 import java.util.Collection;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 
@@ -51,6 +52,25 @@ public interface Crate {
 
   void setMetadataContext(CrateMetadataContext metadataContext);
 
+  /**
+   * Get the value of a key from the metadata context.
+   * @param key the key to be searched
+   * @return the value of the key, null if not found
+   */
+  String getMetadataContextValueOf(String key);
+
+  /**
+   * Get an immutable collection of the keys in the metadata context.
+   * @return the keys in the metadata context
+   */
+  Set<String> getMetadataContextKeys();
+
+  /**
+   * Get an immutable map of the context.
+   * @return an immutable map containing the context key-value pairs
+   */
+  Map<String, String> getMetadataContextPairs();
+
   RootDataEntity getRootDataEntity();
 
   void setRootDataEntity(RootDataEntity rootDataEntity);