Add Java API documentation section on modifying Aspect Models

Author: atextor

documentation/developer-guide/modules/tooling-guide/examples/EditAspectModel.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
+ *
+ * See the AUTHORS file(s) distributed with this work for additional
+ * information regarding authorship.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+package examples;
+
+// tag::imports[]
+import java.io.File;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.List;
+import java.util.Optional;
+
+import org.eclipse.esmf.aspectmodel.edit.AspectChangeManager;
+import org.eclipse.esmf.aspectmodel.edit.AspectChangeManagerConfig;
+import org.eclipse.esmf.aspectmodel.edit.AspectChangeManagerConfigBuilder;
+import org.eclipse.esmf.aspectmodel.edit.Change;
+import org.eclipse.esmf.aspectmodel.edit.ChangeGroup;
+import org.eclipse.esmf.aspectmodel.edit.ChangeReport;
+import org.eclipse.esmf.aspectmodel.edit.ChangeReportFormatter;
+import org.eclipse.esmf.aspectmodel.edit.change.MoveElementToNewFile;
+import org.eclipse.esmf.aspectmodel.edit.change.RenameElement;
+import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
+import org.eclipse.esmf.metamodel.AspectModel;
+// end::imports[]
+
+import org.junit.jupiter.api.Test;
+
+public class EditAspectModel {
+   @Test
+   void testEditAspectModel() {
+      // tag::editModel[]
+      final AspectModel aspectModel = new AspectModelLoader().load(
+            // a File, InputStream or AspectModelUrn
+            // end::editModel[]
+            new File( "aspect-models/org.eclipse.esmf.examples.movement/1.0.0/Movement.ttl" )
+            // tag::editModel[]
+      );
+
+      // All changes to an Aspect Model are done using an AspectChangeManager.
+      // Optionally, you can pass a config object as first constructor argument:
+      final AspectChangeManagerConfig config = AspectChangeManagerConfigBuilder.builder()
+            .detailedChangeReport( true )
+            .defaultFileHeader( List.of( "Generated on "
+                  + new SimpleDateFormat( "dd-MM-yyyy" ).format( new Date() ) ) )
+            .build();
+      final AspectChangeManager changeManager = new AspectChangeManager( config, aspectModel );
+
+      // You can create a single change, or you can combine multiple changes into a group.
+      // For all possible refactoring operations, see classes implementing the Change interface.
+      final Change refactorModel = new ChangeGroup( List.of(
+            // Rename an element. This works with with samm:Aspect and all other model elements.
+            new RenameElement( aspectModel.aspect(), "MyAspect" ),
+            // Move an element to a new Aspect Model file in the same namespace.
+            new MoveElementToNewFile(
+                  // The element to move.
+                  aspectModel.aspect().getProperties().get( 0 ),
+                  // If you intend writing the model to the file system, set the location
+                  // for the newly created file here.
+                  Optional.empty() )
+      ) );
+
+      // Apply the changes and get a report that summerizes the changes.
+      final ChangeReport changeReport = changeManager.applyChange( refactorModel );
+
+      // If you want to display the change report, you can serialize it to a string:
+      ChangeReportFormatter.INSTANCE.apply( changeReport, config );
+
+      // Alternatively, you can also get views on collections containing modified/
+      // added/removed files for the last applied change.
+      changeManager.createdFiles().forEach( file -> System.out.println( "Created: " + file ) );
+      changeManager.modifiedFiles().forEach( file -> System.out.println( "Modified: " + file ) );
+      changeManager.removedFiles().forEach( file -> System.out.println( "Removed: " + file ) );
+
+      // At this point, you could use the AspectChangeManager's undo() method to revert
+      // the last change (refactorModel in this case); afterwards you can also redo().
+      // This functionality is mainly interesting when refactoring the Aspect Model
+      // interactively.
+
+      // If you want to write the model changes to the file system, use the AspectSerializer.
+      // Each AspectModelFile will be written to its respective source location.
+      // Alternatively, the AspectSerializer also provides a method to write an AspectModelFile
+      // into a String.
+      // end::editModel[]
+      /*
+      // tag::editModel[]
+      AspectSerializer.INSTANCE.write( aspectModel );
+      // end::editModel[]
+      */
+   }
+}

documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

@@ -712,6 +712,32 @@ Example:
 include::example$sample-file-header.vm[]
 ----
 
+[[modifying-and-creating-aspect-models]]
+== Modifying and creating Aspect Models
+
+You can use the `AspectChangeManager` to modify an Aspect Model. Each modifying operation performed
+on an Aspect Model is called a _change_. Instances of classes that implement the `Change` interface
+can be passed to the `AspectChangeManager` `applyChange()` method. Available `Change`​s
+include renaming Aspect Model files or Model elements, adding and removing Aspect Model files and
+moving Aspect Model elements to other or new files in the same or another namespace.
+
+++++
+<details>
+<summary>Show used imports</summary>
+++++
+[source,java,indent=0,subs="+macros,+quotes"]
+----
+include::example$EditAspectModel.java[tags=imports]
+----
+++++
+</details>
+++++
+
+[source,java,indent=0,subs="+macros,+quotes"]
+----
+include::example$EditAspectModel.java[tags=editModel]
+----
+
 [[accessing-samm-programmatically]]
 == Accessing the SAMM programmatically