fix: return empty document for non-existent file when parsing from pa…

…th (#1197)

### Motivation
The document api rewrite introduced a breaking change (which affects
internals as well) as the `DocumentFactory#read(Path)` (prior
`Document#read(Path)`) now throws an exception in case the file does not
exist rather than returing a new, empty document.

### Modification
Let `DocumentFactory#read(Path)` return a new, empty document in case
the file does not exist or is not a file and change the specification of
the method to reflect the change.

### Result
The `DocumentFactory#read(Path)` method now returns an empty document in
case the file does either not exist or is not a regular file.

driver/src/main/java/eu/cloudnetservice/driver/document/DocumentFactory.java

@@ -62,7 +62,10 @@ public interface DocumentFactory {
 
  /**
  * Parses a document of the factory supported document type from the file at the given path. The given data must be
- * the root object of a document in order to work.
+ * the root object of a document in order to work. Note: if the file at the given does not exist or the given path is
+ * a directory, this method returns a new, empty document from this factory (as specified by {@link #newDocument()}).
+ * However, this method invocation will fail in case the current jvm does not have the appropriate privileges that
+ * would allow it open the file for reading.
  *
  * @param path the path to the file to parse.
  * @return a parsed document from the file at the given path.

driver/src/main/java/eu/cloudnetservice/driver/document/gson/GsonDocumentFactory.java

@@ -80,11 +80,16 @@ private GsonDocumentFactory() {
  */
  @Override
  public @NonNull Document.Mutable parse(@NonNull Path path) {
- try (var stream = Files.newInputStream(path)) {
- return this.parse(stream);
- } catch (IOException exception) {
- throw new DocumentParseException("Unable to parse document from path " + path, exception);
+ if (Files.exists(path) && Files.isRegularFile(path)) {
+ try (var stream = Files.newInputStream(path)) {
+ return this.parse(stream);
+ } catch (IOException exception) {
+ throw new DocumentParseException("Unable to parse document from path " + path, exception);
+ }
  }
+
+ // in case that the file does not exist just return an empty document
+ return this.newDocument();
  }
 
  /**

driver/src/test/java/eu/cloudnetservice/driver/document/DocumentSerialisationTest.java

@@ -23,8 +23,10 @@
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 import java.util.stream.Stream;
 import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.CleanupMode;
 import org.junit.jupiter.api.io.TempDir;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -67,6 +69,16 @@ static Stream<Arguments> serialisationInputSource() {
  StandardSerialisationStyle.COMPACT));
  }
 
+ @Test
+ void testFileReadReturnsNewDocumentIfMissing() {
+ var targetFile = Path.of("random_test_file_data_" + UUID.randomUUID());
+ Assertions.assertFalse(Files.exists(targetFile));
+ Assertions.assertFalse(Files.isRegularFile(targetFile));
+
+ var deserialized = Assertions.assertDoesNotThrow(() -> DocumentFactory.json().parse(targetFile));
+ Assertions.assertTrue(deserialized.empty());
+ }
+
  @ParameterizedTest
  @MethodSource("serialisationInputSource")
  void testFileSerialisation(Document input, SerialisationStyle style) {