[WIP] Document and refine model join writer

src/main/java/org/rosi_project/model_sync/model_join/representation/writer/FileBasedModelJoinWriter.java

@@ -5,20 +5,37 @@ import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.StandardOpenOption;
+import javax.annotation.Nonnull;
 import org.rosi_project.model_sync.model_join.representation.grammar.ModelJoinExpression;
 
-class FileBasedModelJoinWriter implements ModelJoinWriter<Boolean> {
+/**
+ * The {@code FileBasedModelJoinWriter} outputs a {@link ModelJoinExpression model join description}
+ * onto the File System.
+ *
+ * @author Rico Bergmann
+ */
+class FileBasedModelJoinWriter implements ModelJoinWritingService<Boolean> {
 
   private final File outputFile;
   private final StringBasedModelJoinWriter toStringWriter;
 
-  FileBasedModelJoinWriter(File outputFile) {
+  /**
+   * Full constructor.
+   *
+   * @param outputFile the file to write to
+   */
+  FileBasedModelJoinWriter(@Nonnull File outputFile) {
     this.outputFile = outputFile;
     this.toStringWriter = StringBasedModelJoinWriter.withNewlines();
   }
 
+  /**
+   * Writes the given description to the {@code outputFile}.
+   *
+   * @return whether the file was successfully written
+   */
   @Override
-  public Boolean write(ModelJoinExpression modelJoin) {
+  public Boolean write(@Nonnull ModelJoinExpression modelJoin) {
     try (BufferedWriter writer = Files.newBufferedWriter(
         outputFile.toPath(),
         StandardOpenOption.CREATE, StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING)) {

src/main/java/org/rosi_project/model_sync/model_join/representation/writer/ModelJoinWriter.java

 package org.rosi_project.model_sync.model_join.representation.writer;
 
+import java.io.File;
+import javax.annotation.Nonnull;
 import org.rosi_project.model_sync.model_join.representation.grammar.ModelJoinExpression;
 
-public interface ModelJoinWriter<T> {
+/**
+ * The {@code ModelJoinWriter} acts as an entry point to write and or transform {@link
+ * ModelJoinExpression model join descriptions} to various representations.
+ *
+ * @author Rico Bergmann
+ */
+public class ModelJoinWriter {
 
-  T write(ModelJoinExpression modelJoin);
+  private static final StringBasedModelJoinWriter stringWriter = StringBasedModelJoinWriter
+      .createDefault();
+
+  /**
+   * Converts a whole model join description to a single {@code String}.
+   * <p>
+   * This {@code String} is primarily intended to be human-readable and does not focus in being easy
+   * to reuse for further purposes.
+   */
+  public static String writeToString(@Nonnull ModelJoinExpression modelJoin) {
+    return stringWriter.write(modelJoin);
+  }
+
+  /**
+   * Outputs a whole model join description to a single file.
+   * <p>
+   * The resulting file is intended to be both human-readable as well as to be parsed by further
+   * applications.
+   *
+   * @return whether the expression was written successfully.
+   */
+  public static boolean writeToFile(
+      @Nonnull File outputFile,
+      @Nonnull ModelJoinExpression modelJoin) {
+    return new FileBasedModelJoinWriter(outputFile).write(modelJoin);
+  }
 
 }

src/main/java/org/rosi_project/model_sync/model_join/representation/writer/ModelJoinWriterFactory.java

-package org.rosi_project.model_sync.model_join.representation.writer;
-
-import java.io.File;
-import org.rosi_project.model_sync.model_join.representation.grammar.ModelJoinExpression;
-
-public class ModelJoinWriterFactory {
-
-  public static String writeToString(ModelJoinExpression modelJoin) {
-    return StringBasedModelJoinWriter.createDefault().write(modelJoin);
-  }
-
-  public static boolean writeToFile(File outputFile, ModelJoinExpression modelJoin) {
-    return new FileBasedModelJoinWriter(outputFile).write(modelJoin);
-  }
-
-}

src/main/java/org/rosi_project/model_sync/model_join/representation/writer/ModelJoinWritingService.java

+package org.rosi_project.model_sync.model_join.representation.writer;
+
+import javax.annotation.Nonnull;
+import org.rosi_project.model_sync.model_join.representation.grammar.ModelJoinExpression;
+
+/**
+ * A {@code ModelJoinWritingService} transforms a {@link ModelJoinExpression model join description}
+ * into some different representation.
+ *
+ * @author Rico Bergmann
+ */
+public interface ModelJoinWritingService<T> {
+
+  /**
+   * Performs the transformation. The result of this method depends on the actual details of the
+   * writing service and should be documented there.
+   */
+  T write(@Nonnull ModelJoinExpression modelJoin);
+
+}

src/main/java/org/rosi_project/model_sync/model_join/representation/writer/StringBasedModelJoinWriter.java

@@ -18,17 +18,23 @@ import org.rosi_project.model_sync.model_join.representation.grammar.ThetaJoinEx
 import org.rosi_project.model_sync.model_join.representation.util.Functional;
 import org.rosi_project.model_sync.model_join.representation.util.Nothing;
 
-class StringBasedModelJoinWriter implements ModelJoinWriter<String> {
+/**
+ * The {@code StringBasedModelJoinWriter} transforms a {@link ModelJoinExpression model join description}
+ * to a single {@code String}.
+ *
+ * @author Rico Bergmann
+ */
+class StringBasedModelJoinWriter implements ModelJoinWritingService<String> {
 
   private static final String NEWLINE_DELIM = "\n";
   private static final String EMPTY_DELIM = " ";
   private static final String DEFAULT_INDENTATION = "  ";
 
-  public static StringBasedModelJoinWriter createDefault() {
+  static StringBasedModelJoinWriter createDefault() {
     return new StringBasedModelJoinWriter(false);
   }
 
-  public static StringBasedModelJoinWriter withNewlines() {
+  static StringBasedModelJoinWriter withNewlines() {
     return new StringBasedModelJoinWriter(true);
   }
 

src/main/java/org/rosi_project/model_sync/util/NeedsCleanup.java

-package org.rosi_project.model_sync.util;
-
-public @interface NeedsCleanup {
-
-}