Add JavaDoc to Change classes

Author: atextor

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/AspectChangeManager.java

@@ -29,6 +29,22 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * The AspectChangeManager is the central place to to changes/edits/refactorings of an {@link AspectModel}. The AspectChangeManager
+ * wraps an AspectModel and allows applying instances of the {@link Change} class using the {@link #applyChange(Change)} method.
+ * Calling this method returns a {@link ChangeReport} that describes the performed changes in a structured way. Use the
+ * {@link ChangeReportFormatter} to render the ChangeReport to a structured string representation.
+ * <br/>
+ * Note the following points:
+ * <ul>
+ *    <li>Only one AspectChangeManager must wrap a given AspectModel at any time</li>
+ *    <li>All changes are done <i>in-memory</i>. In order to write them to the file system, use the
+ *    {@link org.eclipse.esmf.aspectmodel.serializer.AspectSerializer}</li>
+ *    <li>After performing an {@link #applyChange(Change)}, {@link #undoChange()} or {@link #redoChange()} operation, and until the
+ *    next call of one of them, the methods {@link #modifiedFiles()}, {@link #createdFiles()} and {@link #removedFiles()} indicate
+ *    corresponding changes in the AspectModel's files.
+ * </ul>
+ */
 public class AspectChangeManager implements ChangeContext {
    private static final Logger LOG = LoggerFactory.getLogger( AspectChangeManager.class );
 
@@ -37,7 +53,6 @@ public class AspectChangeManager implements ChangeContext {
    private final DefaultAspectModel aspectModel;
    private final AspectChangeManagerConfig config;
    private final Map<AspectModelFile, FileState> fileState = new HashMap<>();
-   private boolean isUndoOperation = false;
 
    private enum FileState {
       CREATED, CHANGED, REMOVED
@@ -59,7 +74,6 @@ public AspectChangeManager( final AspectModel aspectModel ) {
 
    public synchronized ChangeReport applyChange( final Change change ) {
       resetFileStates();
-      isUndoOperation = false;
       final ChangeReport result = change.fire( this );
       updateAspectModelAfterChange();
       undoStack.offerLast( change.reverse() );
@@ -70,7 +84,6 @@ public synchronized void undoChange() {
       if ( undoStack.isEmpty() ) {
          return;
       }
-      isUndoOperation = true;
       resetFileStates();
       final Change change = undoStack.pollLast();
       change.fire( this );
@@ -84,7 +97,6 @@ public synchronized void redoChange() {
       }
       resetFileStates();
       final Change change = redoStack.pollLast();
-      isUndoOperation = false;
       change.fire( this );
       updateAspectModelAfterChange();
       undoStack.offerLast( change.reverse() );

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/AspectChangeManagerConfig.java

@@ -22,8 +22,6 @@ public record AspectChangeManagerConfig(
       List<String> defaultFileHeader,
       boolean detailedChangeReport
 ) {
-   public static AspectChangeManagerConfig DEFAULT = AspectChangeManagerConfigBuilder.builder().build();
-
    public AspectChangeManagerConfig {
       if ( defaultFileHeader == null ) {
          defaultFileHeader = List.of();

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/Change.java

@@ -13,8 +13,26 @@
 
 package org.eclipse.esmf.aspectmodel.edit;
 
+/**
+ * This interface represents a single modification to an Aspect Model. Instances of Change should be applied to an Aspect Model
+ * using {@link AspectChangeManager}; see the description about the change mechanism there. Instances of Change <b>must not</b>
+ * perform file system operations; synching "adding", "removing" and "modifying" files with the file system is a separate step.
+ */
 public interface Change {
+   /**
+    * "Run" this change. This method should not be directly called on a Change object, but will be executed by the AspectChangeManager.
+    * The passed {@link ChangeContext} provides information to the Change implementation about the current state of the AspectModel.
+    *
+    * @param changeContext the change context
+    * @return the report describing what has been changed
+    */
    ChangeReport fire( ChangeContext changeContext );
 
+   /**
+    * Returns a Change that is the reverse operation of this one, i.e., running this change and the reverse change after another
+    * effectively cancels out any changes.
+    *
+    * @return the Change representing the reverse operation
+    */
    Change reverse();
 }

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/ChangeContext.java

@@ -17,6 +17,10 @@
 
 import org.eclipse.esmf.aspectmodel.AspectModelFile;
 
+/**
+ * The ChangeContext encapsulates the functionality provided to {@link Change} implementations to access the current set of
+ * Aspect Model Files and indicate changes.
+ */
 public interface ChangeContext {
    Stream<AspectModelFile> aspectModelFiles();
 

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/ChangeGroup.java

@@ -17,6 +17,9 @@
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * A Change that groups other changes
+ */
 public class ChangeGroup implements Change {
    private final String summary;
    private final List<Change> changes;

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/ChangeReport.java

@@ -16,6 +16,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * A structured representation of a number of {@link Change}s
+ */
 public interface ChangeReport {
    ChangeReport NoChanges = new ChangeReport() {
    };

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/ChangeReportFormatter.java

@@ -23,6 +23,9 @@
 import org.apache.jena.rdf.model.Model;
 import org.apache.jena.rdf.model.ModelFactory;
 
+/**
+ * Takes a {@link ChangeReport} as an input and renders it as a string
+ */
 public class ChangeReportFormatter implements BiFunction<ChangeReport, AspectChangeManagerConfig, String> {
    public static final ChangeReportFormatter INSTANCE = new ChangeReportFormatter();
 

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/change/AddAspectModelFile.java

@@ -24,6 +24,9 @@
 import org.apache.jena.rdf.model.Model;
 import org.apache.jena.rdf.model.ModelFactory;
 
+/**
+ * Represents the operation of adding an {@link AspectModelFile} to an AspectModel
+ */
 public class AddAspectModelFile extends AbstractChange {
    private final AspectModelFile newFile;
 

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/change/AddElementDefinition.java

@@ -20,6 +20,9 @@
 import org.apache.jena.rdf.model.Model;
 import org.apache.jena.rdf.model.ModelFactory;
 
+/**
+ * Adds the definition of a model element to an AspectModelFile. The definition is given as a set of RDF statements (a {@link Model}).
+ */
 public class AddElementDefinition extends EditAspectModel {
    private final AspectModelUrn elementUrn;
    private final Model definition;

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/edit/change/EditAspectModel.java

@@ -13,7 +13,6 @@
 
 package org.eclipse.esmf.aspectmodel.edit.change;
 
-import java.util.AbstractMap;
 import java.util.Map;
 import java.util.stream.Collectors;
 
@@ -23,11 +22,27 @@
 
 import org.apache.jena.rdf.model.Model;
 
+/**
+ * Abstract base class for all Changes that change the content (i.e., the underlying RDF) of an Aspect Model file.
+ */
 public abstract class EditAspectModel extends AbstractChange {
+   /**
+    * Represents the changes to perform on the RDF model
+    *
+    * @param add the set of statements to add
+    * @param remove the set of statements to remove
+    * @param description the description of this change set (used in the {@link ChangeReport})
+    */
    protected record ModelChanges( Model add, Model remove, String description ) {
       public static final ModelChanges NONE = new ModelChanges( null, null, "" );
    }
 
+   /**
+    * Each AspectModelFile is changed separately, so extending classes need to calculate changes for a given file.
+    *
+    * @param aspectModelFile the AspectModelFile to change
+    * @return the set of changes
+    */
    abstract protected ModelChanges calculateChangesForFile( AspectModelFile aspectModelFile );
 
    @Override