Include ModelJoin support in main development

This will merge the completed ModelJoin abstraction as well as an ANTLR based parser to our main development branch. Afterwards we can start with adding custom views for the Sync UI.

src/main/java/org/rosi_project/model_sync/model_join/representation/grammar/KeepReferenceExpression.java

@@ -5,25 +5,125 @@ import java.util.List;
 import java.util.Objects;
 import javax.annotation.Nonnull;
 import org.rosi_project.model_sync.model_join.representation.core.AttributePath;
+import org.rosi_project.model_sync.model_join.representation.util.Assert;
 
 // TODO the Xtext grammar also specifies an optional `as reference` part - what does that part do?
 
 /**
- * A {@code KeepReferenceExpression} retains links to other instances in the
- * original models. All objects that are referenced in the base models will also
- * be available in the resulting ModelJoin views.
+ * A {@code KeepReferenceExpression} retains links to other instances in the original models. All
+ * objects that are referenced in the base models will also be available in the resulting ModelJoin
+ * views.
  * <p>
- * TODO complete doc
+ * As references are directional, each expression also distinguishes between {@code outgoing} and
+ * {@code incoming} references - depending on whether the model class of {@code this} expression
+ * owns the reference ({@code outgoing}) or instances of this model class are being referenced
+ * ({@code incoming}).
+ * <p>
+ * The referenced instances will be made available according to a number of keep statements which
+ * specify the attributes to include. This boils down to the creation of a nested ModelJoin view for
+ * these instances.
  *
  * @author Rico Bergmann
  */
 public class KeepReferenceExpression extends KeepExpression {
 
+  /**
+   * The {@code ReferenceDirection} defines whether a reference is owned by the containing model
+   * class or whether it is the class being referenced.
+   */
   public enum ReferenceDirection {
+
+    /**
+     * Indicates that the containing model class owns the reference.
+     */
     OUTGOING,
+
+    /**
+     * Indicates that the containing model class is referenced by some other class.
+     */
     INCOMING
   }
 
+  /**
+   * The {@code KeepReferenceBuilder} enables the construction of new {@code
+   * KeepReferenceExpression} instances through a nice and fluent interface.
+   *
+   * @author Rico Bergmann
+   */
+  public static class KeepReferenceBuilder {
+
+    @Nonnull
+    private ReferenceDirection referenceDirection;
+
+    @Nonnull
+    private AttributePath attribute;
+
+    @Nonnull
+    private AttributePath target;
+
+    @Nonnull
+    private List<KeepExpression> keeps;
+
+    /**
+     * Default constructor.
+     */
+    private KeepReferenceBuilder() {
+      this.keeps = new ArrayList<>();
+    }
+
+    /**
+     * Creates an outgoing reference for the given attribute.
+     */
+    @Nonnull
+    public KeepReferenceBuilder outgoing(@Nonnull AttributePath attribute) {
+      this.referenceDirection = ReferenceDirection.OUTGOING;
+      this.attribute = attribute;
+      return this;
+    }
+
+    /**
+     * Creates an incoming reference for the given attribute.
+     */
+    @Nonnull
+    public KeepReferenceBuilder incoming(@Nonnull AttributePath attribute) {
+      this.referenceDirection = ReferenceDirection.INCOMING;
+      this.attribute = attribute;
+      return this;
+    }
+
+    /**
+     * Specifies the name of the attribute in the target join.
+     */
+    @Nonnull
+    public KeepReferenceBuilder as(@Nonnull AttributePath target) {
+      this.target = target;
+      return this;
+    }
+
+    /**
+     * Adds an attribute to the view for the referenced instances.
+     */
+    @Nonnull
+    public KeepReferenceBuilder keep(@Nonnull KeepExpression keepExpression) {
+      this.keeps.add(keepExpression);
+      return this;
+    }
+
+    /**
+     * Finishes the construction process.
+     */
+    @Nonnull
+    public KeepReferenceExpression buildExpression() {
+      Assert.noNullArguments("All components must be specified", attribute, referenceDirection, target, keeps);
+      return new KeepReferenceExpression(attribute, referenceDirection, target, keeps);
+    }
+  }
+
+  @Nonnull
+  public static KeepReferenceBuilder createNew() {
+    return new KeepReferenceBuilder();
+  }
+
   @Nonnull
   private final AttributePath attribute;
 
@@ -36,6 +136,16 @@ public class KeepReferenceExpression extends KeepExpression {
   @Nonnull
   private final List<KeepExpression> keeps;
 
+  /**
+   * Full constructor.
+   *
+   * @param attribute the attribute of the source model which contains the references
+   * @param referenceDirection whether the source model owns the reference or is being
+   *     referenced
+   * @param target the name of the attribute under which the resulting references should be made
+   *     available
+   * @param keeps the statements which should be build the "nested" view for the references
+   */
   public KeepReferenceExpression(
       @Nonnull AttributePath attribute,
       @Nonnull ReferenceDirection referenceDirection,
@@ -47,21 +157,36 @@ public class KeepReferenceExpression extends KeepExpression {
     this.keeps = keeps;
   }
 
+  /**
+   * Provides the attribute of the source model which contains the references.
+   */
   @Nonnull
   public AttributePath getAttribute() {
     return attribute;
   }
 
+  /**
+   * Provides the kind of reference, that is whether the containing Join owns the reference or is
+   * being referenced by another model class or Join.
+   */
   @Nonnull
   public ReferenceDirection getReferenceDirection() {
     return referenceDirection;
   }
 
+  /**
+   * Provides the name of the attribute under which the referenced instances should be made
+   * available.
+   */
   @Nonnull
   public AttributePath getTarget() {
     return target;
   }
 
+  /**
+   * Provides all {@code KeepExpression keep expressions} that should be used to build the Join for
+   * the referenced instances.
+   */
   @Nonnull
   public List<KeepExpression> getKeeps() {
     return new ArrayList<>(keeps);
@@ -76,8 +201,7 @@ public class KeepReferenceExpression extends KeepExpression {
       return false;
     }
     KeepReferenceExpression that = (KeepReferenceExpression) o;
-    return attribute.equals(that.attribute) &&
-        target.equals(that.target);
+    return attribute.equals(that.attribute) && target.equals(that.target);
   }
 
   @Override