Add unversioned files

Signed-off-by: Dominik Voigt <[email protected]>

Author: DominikVoigt

docs/adr/0018-use-Jackson-to-parse-study-yml.md

@@ -0,0 +1,51 @@
+# Use Jackson to parse study.yml
+
+## Context and Problem Statement
+
+The study definition file is formulated as a YAML document.
+To accessed the definition within JabRef this document has to be parsed.
+What parser should be used to parse YAML files?
+
+## Considered Options
+
+* Jackson
+* SnakeYAML Engine
+* yamlbeans
+* eo-yaml
+* Own parser
+
+## Decision Outcome
+
+Chosen option: Jackson, because as it is a dedicated library for parsing YAML. yamlbeans also seem to be viable. They all offer similar functionality
+
+## Pros and Cons of the Options
+
+### Jackson
+
+* Good, because established YAML parser library
+* Good, because supports YAML 1.2
+* Good, because it can parse LocalDate
+
+### SnakeYAML Engine
+
+* Good, because established YAML parser library
+* Good, because supports YAML 1.2
+* Bad, because cannot parse YAML into Java DTOs
+
+### yamlbeans
+
+* Good, because established YAML parser library
+* Good, because [nice getting started page](https://github.com/EsotericSoftware/yamlbeans)
+* Bad, because objects need to be annotated in the yaml file to be parsed into Java objects
+
+### eo-yaml
+
+* Good, because established YAML parser library
+* Good, because supports YAML 1.2
+* Bad, because cannot parse YAML into Java DTOs?
+
+### Own parser
+
+* Good, because easily customizable
+* Bad, because high effort
+* Bad, because has to be tested extensively

src/main/java/org/jabref/logic/crawler/StudyYAMLParser.java

@@ -0,0 +1,38 @@
+package org.jabref.logic.crawler;
+
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Path;
+
+import org.jabref.model.study.Study;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+public class StudyYAMLParser {
+
+    /**
+     * Parses the given yaml study definition file into a study instance
+     */
+    public Study parseStudyYAMLFile(Path studyYAMLFile) throws IOException {
+        ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory());
+        yamlMapper.registerModule(new JavaTimeModule());
+        try (InputStream fileInputStream = new FileInputStream(studyYAMLFile.toFile())) {
+            return yamlMapper.readValue(fileInputStream, Study.class);
+        }
+    }
+
+    /**
+     * Writes the given study instance into a yaml file to the given path
+     */
+    public void writeStudyYAMLFile(Study study, Path studyYAMLFile) throws IOException {
+        ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory().disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER).enable(YAMLGenerator.Feature.MINIMIZE_QUOTES));
+        yamlMapper.registerModule(new JavaTimeModule());
+        yamlMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+        yamlMapper.writeValue(studyYAMLFile.toFile(), study);
+    }
+}

src/main/java/org/jabref/model/study/LibraryEntry.java

@@ -0,0 +1,67 @@
+package org.jabref.model.study;
+
+public class LibraryEntry {
+    private String name;
+    private boolean enabled;
+
+    public LibraryEntry(String name, boolean enabled) {
+        this.name = name;
+        this.enabled = enabled;
+    }
+
+    /**
+     * Used for Jackson deserialization
+     */
+    public LibraryEntry() {
+        // Per default fetcher is activated
+        this.enabled = true;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public boolean isEnabled() {
+        return enabled;
+    }
+
+    public void setEnabled(boolean enabled) {
+        this.enabled = enabled;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        LibraryEntry that = (LibraryEntry) o;
+
+        if (isEnabled() != that.isEnabled()) {
+            return false;
+        }
+        return getName() != null ? getName().equals(that.getName()) : that.getName() == null;
+    }
+
+    @Override
+    public int hashCode() {
+        int result = getName() != null ? getName().hashCode() : 0;
+        result = 31 * result + (isEnabled() ? 1 : 0);
+        return result;
+    }
+
+    @Override
+    public String toString() {
+        return "LibraryEntry{" +
+                "name='" + name + '\'' +
+                ", enabled=" + enabled +
+                '}';
+    }
+}

src/main/java/org/jabref/model/study/QueryEntry.java

@@ -0,0 +1,50 @@
+package org.jabref.model.study;
+
+public class QueryEntry {
+    private String query;
+
+    public QueryEntry(String query) {
+        this.query = query;
+    }
+
+    /**
+     * Used for Jackson deserialization
+     */
+    public QueryEntry() {
+
+    }
+
+    public String getQuery() {
+        return query;
+    }
+
+    public void setQuery(String query) {
+        this.query = query;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+
+        QueryEntry that = (QueryEntry) o;
+
+        return getQuery() != null ? getQuery().equals(that.getQuery()) : that.getQuery() == null;
+    }
+
+    @Override
+    public int hashCode() {
+        return getQuery() != null ? getQuery().hashCode() : 0;
+    }
+
+    @Override
+    public String toString() {
+        return "QueryEntry{" +
+                "query='" + query + '\'' +
+                '}';
+    }
+}

src/test/java/org/jabref/logic/crawler/StudyYAMLParserTest.java

@@ -0,0 +1,59 @@
+package org.jabref.logic.crawler;
+
+import java.net.URL;
+import java.nio.file.Path;
+import java.time.LocalDate;
+import java.util.List;
+
+import org.jabref.logic.util.io.FileUtil;
+import org.jabref.model.study.LibraryEntry;
+import org.jabref.model.study.QueryEntry;
+import org.jabref.model.study.Study;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class StudyYAMLParserTest {
+    @TempDir
+    static Path testDirectory;
+    Study expectedStudy;
+
+    @BeforeAll
+    static void copyStudyYAMLIntoTestDirectory() throws Exception {
+        Path destination = testDirectory.resolve("study.yml");
+        URL studyDefinition = StudyYAMLParser.class.getResource("study.yml");
+        FileUtil.copyFile(Path.of(studyDefinition.toURI()), destination, false);
+    }
+
+    @BeforeEach
+    void setupStudy() {
+        List<String> authors = List.of("Jab Ref");
+        String studyName = "TestStudyName";
+        List<String> researchQuestions = List.of("Question1", "Question2");
+        List<QueryEntry> queryEntries = List.of(new QueryEntry("Quantum"), new QueryEntry("Cloud Computing"), new QueryEntry("\"Software Engineering\""));
+        List<LibraryEntry> libraryEntries = List.of(new LibraryEntry("Springer", true), new LibraryEntry("ArXiv", true));
+
+        expectedStudy = new Study(authors, studyName, researchQuestions, queryEntries, libraryEntries);
+        expectedStudy.setLastSearchDate(LocalDate.parse("2020-11-26"));
+    }
+
+    @Test
+    public void parseStudyFileSuccessfully() throws Exception {
+        Study study = new StudyYAMLParser().parseStudyYAMLFile(testDirectory.resolve("study.yml"));
+
+        assertEquals(expectedStudy, study);
+    }
+
+    @Test
+    public void writeStudyFileSuccessfully() throws Exception {
+        new StudyYAMLParser().writeStudyYAMLFile(expectedStudy, testDirectory.resolve("study.yml"));
+
+        Study study = new StudyYAMLParser().parseStudyYAMLFile(testDirectory.resolve("study.yml"));
+
+        assertEquals(expectedStudy, study);
+    }
+}

src/test/resources/org/jabref/logic/crawler/study.yml

@@ -0,0 +1,18 @@
+authors:
+  - Jab Ref
+studyName: TestStudyName
+lastSearchDate: 2020-11-26
+researchQuestions:
+  - Question1
+  - Question2
+queries:
+  - query: Quantum
+  - query: Cloud Computing
+  - query: '"Software Engineering"'
+libraries:
+  - name: Springer
+    enabled: true
+  - name: ArXiv
+    enabled: true
+  - name: IEEEXplore
+    enabled: false