Added streamReader, fixed an issue with zipReader adding crate metadata as plain content, set CustomPreview as default preview in builder, updated README

Author: ThomasJejkal

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")

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

@@ -17,6 +17,7 @@
 import edu.kit.datamanager.ro_crate.payload.CratePayload;
 import edu.kit.datamanager.ro_crate.payload.RoCratePayload;
 import edu.kit.datamanager.ro_crate.preview.CratePreview;
+import edu.kit.datamanager.ro_crate.preview.CustomPreview;
 import edu.kit.datamanager.ro_crate.special.CrateVersion;
 import edu.kit.datamanager.ro_crate.special.JsonUtilFunctions;
 import edu.kit.datamanager.ro_crate.validation.JsonSchemaValidation;
@@ -251,7 +252,7 @@ public static class RoCrateBuilder {
         private static final String PROPERTY_DESCRIPTION = "description";
 
         CratePayload payload;
-        CratePreview preview;
+        CratePreview preview = new CustomPreview();
         CrateMetadataContext metadataContext;
         ContextualEntity license;
         RootDataEntity rootDataEntity;

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

@@ -4,10 +4,14 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import edu.kit.datamanager.ro_crate.preview.model.ROCratePreviewModel;
 import edu.kit.datamanager.ro_crate.util.ZipUtil;
+import edu.kit.datamanager.ro_crate.writer.RoCrateWriter;
+import freemarker.core.ParseException;
 import freemarker.template.Configuration;
+import freemarker.template.MalformedTemplateNameException;
 import freemarker.template.Template;
 import freemarker.template.TemplateException;
 import freemarker.template.TemplateExceptionHandler;
+import freemarker.template.TemplateNotFoundException;
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.FileWriter;
@@ -24,6 +28,8 @@
 import net.lingala.zip4j.exception.ZipException;
 import net.lingala.zip4j.io.outputstream.ZipOutputStream;
 import org.apache.commons.io.FileUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * This class generates a custom preview without requiring external
@@ -34,17 +40,24 @@
  */
 public class CustomPreview implements CratePreview {
 
+    private final static Logger logger = LoggerFactory.getLogger(CustomPreview.class);
+
     private final Configuration cfg;
+    private Template template = null;
 
     public CustomPreview() {
         cfg = new Configuration(Configuration.VERSION_2_3_34);
         cfg.setClassForTemplateLoading(CustomPreview.class, "/");
         cfg.setDefaultEncoding("UTF-8");
         cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
-
+        try {
+            template = cfg.getTemplate("templates/custom_preview.ftl");
+        } catch (IOException ex) {
+            logger.error("Failed to read template for CustomPreview.", ex);
+        }
     }
 
-    public ROCratePreviewModel mapFromJson(String metadata) throws IOException {
+    private ROCratePreviewModel mapFromJson(String metadata) throws IOException {
         ObjectMapper mapper = new ObjectMapper();
         JsonNode root = (JsonNode) mapper.readValue(metadata, JsonNode.class);
         JsonNode graph = root.get("@graph");
@@ -126,6 +139,9 @@ public ROCratePreviewModel mapFromJson(String metadata) throws IOException {
 
     @Override
     public void saveAllToZip(ZipFile zipFile) throws IOException {
+        if (template == null) {
+            throw new IOException("Preview template did not load. Unable to proceed.");
+        }
         if (zipFile == null) {
             throw new IOException("Argument zipFile must not be null.");
         }
@@ -139,9 +155,9 @@ public void saveAllToZip(ZipFile zipFile) throws IOException {
         try {
             Map<String, Object> dataModel = new HashMap<>();
             dataModel.put("crateModel", mapFromJson(metadata));
-            Template temp = cfg.getTemplate("templates/custom_preview.ftl");
+
             try (Writer out = new OutputStreamWriter(new FileOutputStream("temp/ro-crate-preview.html"))) {
-                temp.process(dataModel, out);
+                template.process(dataModel, out);
                 out.flush();
             }
             zipFile.addFile("temp/ro-crate-preview.html");
@@ -158,16 +174,18 @@ public void saveAllToZip(ZipFile zipFile) throws IOException {
 
     @Override
     public void saveAllToFolder(File folder) throws IOException {
+        if (template == null) {
+            throw new IOException("Preview template did not load. Unable to proceed.");
+        }
         if (folder == null || !folder.exists()) {
             throw new IOException("Preview target folder " + folder + " does not exist.");
         }
         String metadata = FileUtils.readFileToString(new File(folder, "ro-crate-metadata.json"), "UTF-8");
         try {
             Map<String, Object> dataModel = new HashMap<>();
             dataModel.put("crateModel", mapFromJson(metadata));
-            Template temp = cfg.getTemplate("templates/custom_preview.ftl");
             try (Writer out = new OutputStreamWriter(new FileOutputStream(new File(folder, "ro-crate-preview.html")))) {
-                temp.process(dataModel, out);
+                template.process(dataModel, out);
                 out.flush();
             }
         } catch (TemplateException ex) {
@@ -177,6 +195,9 @@ public void saveAllToFolder(File folder) throws IOException {
 
     @Override
     public void saveAllToStream(String metadata, ZipOutputStream stream) throws IOException {
+        if (template == null) {
+            throw new IOException("Preview template did not load. Unable to proceed.");
+        }
         try {
             //prepare metadata for template
             Map<String, Object> dataModel = new HashMap<>();
@@ -187,8 +208,7 @@ public void saveAllToStream(String metadata, ZipOutputStream stream) throws IOEx
             //load and process template
             try (FileWriter writer = new FileWriter(new File("temp/ro-crate-preview.html"))) {
                 //load and process template
-                Template temp = cfg.getTemplate("templates/custom_preview.frm");
-                temp.process(dataModel, writer);
+                template.process(dataModel, writer);
                 writer.flush();
             }