Introduce generator inheritance hierarchy

Author: atextor

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/JsonGenerator.java

@@ -33,7 +33,7 @@
  * @param <A> the corresponding artifact type
  */
 public abstract class JsonGenerator<C extends JsonGenerationConfig, R extends JsonNode, A extends JsonArtifact<R>>
-      extends Generator<String, R, C, A> {
+      extends AspectGenerator<String, R, C, A> {
    protected final ObjectMapper objectMapper;
 
    public JsonGenerator( final Aspect aspect, final C config ) {

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/asyncapi/AspectModelAsyncApiGenerator.java

@@ -57,27 +57,27 @@ public Stream<AsyncApiSchemaArtifact> generate() {
       AsyncApiSchemaArtifact result;
       try {
          final ObjectNode rootNode = getRootJsonNode();
-         final String apiVersion = getApiVersion( aspect, config.useSemanticVersion() );
+         final String apiVersion = getApiVersion( aspect(), config.useSemanticVersion() );
 
          if ( StringUtils.isNotBlank( config.applicationId() ) ) {
             rootNode.put( "id", config.applicationId() );
          }
 
          final ObjectNode info = (ObjectNode) rootNode.get( "info" );
-         info.put( TITLE_FIELD, aspect.getPreferredName( config.locale() ) + " MQTT API" );
+         info.put( TITLE_FIELD, aspect().getPreferredName( config.locale() ) + " MQTT API" );
          info.put( "version", apiVersion );
-         info.put( DESCRIPTION_FIELD, getDescription( aspect.getDescription( config.locale() ) ) );
-         info.put( AbstractGenerator.SAMM_EXTENSION, aspect.urn().toString() );
+         info.put( DESCRIPTION_FIELD, getDescription( aspect().getDescription( config.locale() ) ) );
+         info.put( AbstractGenerator.SAMM_EXTENSION, aspect().urn().toString() );
 
-         rootNode.set( "channels", getChannelNode( aspect, config ) );
-         if ( !aspect.getEvents().isEmpty() || !aspect.getOperations().isEmpty() ) {
-            setOperations( aspect, rootNode );
-            setComponents( aspect, rootNode, config.locale() );
+         rootNode.set( "channels", getChannelNode( aspect(), config ) );
+         if ( !aspect().getEvents().isEmpty() || !aspect().getOperations().isEmpty() ) {
+            setOperations( aspect(), rootNode );
+            setComponents( aspect(), rootNode, config.locale() );
          }
-         result = new AsyncApiSchemaArtifact( aspect.getName(), rootNode );
+         result = new AsyncApiSchemaArtifact( aspect().getName(), rootNode );
       } catch ( final Exception exception ) {
          LOG.error( "There was an exception during the read of the root or the validation.", exception );
-         result = new AsyncApiSchemaArtifact( aspect.getName(), FACTORY.objectNode() );
+         result = new AsyncApiSchemaArtifact( aspect().getName(), FACTORY.objectNode() );
       }
       return Stream.of( result );
    }

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/docu/AspectModelDocumentationGenerator.java

@@ -27,9 +27,9 @@
 import java.util.function.Function;
 import java.util.stream.Stream;
 
+import org.eclipse.esmf.aspectmodel.generator.AspectGenerator;
 import org.eclipse.esmf.aspectmodel.generator.AspectModelHelper;
 import org.eclipse.esmf.aspectmodel.generator.DocumentGenerationException;
-import org.eclipse.esmf.aspectmodel.generator.Generator;
 import org.eclipse.esmf.aspectmodel.generator.I18nLanguageBundle;
 import org.eclipse.esmf.aspectmodel.generator.LanguageCollector;
 import org.eclipse.esmf.aspectmodel.generator.TemplateEngine;
@@ -46,7 +46,8 @@
 /**
  * Asciidoc generator for a aspect model.
  */
-public class AspectModelDocumentationGenerator extends Generator<String, String, DocumentationGenerationConfig, DocumentationArtifact> {
+public class AspectModelDocumentationGenerator extends
+      AspectGenerator<String, String, DocumentationGenerationConfig, DocumentationArtifact> {
    public static final DocumentationGenerationConfig DEFAULT_CONFIG = DocumentationGenerationConfigBuilder.builder().build();
    private static final Logger LOG = LoggerFactory.getLogger( AspectModelDocumentationGenerator.class );
    private static final String DOCU_ROOT_DIR = "/docu";
@@ -86,18 +87,18 @@ public AspectModelDocumentationGenerator( final Aspect aspect, final Documentati
    @Override
    public Stream<DocumentationArtifact> generate() {
       final Map<String, Object> templateContext = new HashMap<>();
-      templateContext.put( "aspectModel", aspect );
+      templateContext.put( "aspectModel", aspect() );
       templateContext.put( "aspectModelHelper", new AspectModelHelper() );
       templateContext.put( "Scalar", Scalar.class );
 
       final Set<Locale> targetLanguages = config.locale() == null
-            ? LanguageCollector.collectUsedLanguages( aspect )
+            ? LanguageCollector.collectUsedLanguages( aspect() )
             : Set.of( Locale.ENGLISH );
       return targetLanguages.stream().map( language -> {
-         logMissingTranslations( aspect, language );
+         logMissingTranslations( aspect(), language );
          templateContext.put( "i18n", new I18nLanguageBundle( language ) );
          final TemplateEngine templateEngine = new TemplateEngine( templateContext, engineConfiguration );
-         final String artifactName = getArtifactName( aspect, language );
+         final String artifactName = getArtifactName( aspect(), language );
          String source = templateEngine.apply( DOCU_ROOT_DIR + "/templates/html/aspect-model-documentation" );
          source = insertAspectModelDiagram( source, language );
          source = insertStaticPlaceholders( source );
@@ -122,7 +123,7 @@ public void generate( final Function<String, OutputStream> nameMapper, final Map
       final DocumentationGenerationConfig config = DocumentationGenerationConfigBuilder.builder()
             .stylesheet( generationOptions.get( HtmlGenerationOption.STYLESHEET ) )
             .build();
-      new AspectModelDocumentationGenerator( aspect, config ).generate( nameMapper );
+      new AspectModelDocumentationGenerator( aspect(), config ).generate( nameMapper );
    }
 
    /**
@@ -144,15 +145,15 @@ public void generate( final Function<String, OutputStream> nameMapper, final Map
             .stylesheet( generationOptions.get( HtmlGenerationOption.STYLESHEET ) )
             .locale( language )
             .build();
-      new AspectModelDocumentationGenerator( aspect, config ).generate( nameMapper );
+      new AspectModelDocumentationGenerator( aspect(), config ).generate( nameMapper );
    }
 
    private String getArtifactName( final Aspect aspectModel, final Locale locale ) {
       return aspectModel.getName() + "_" + locale.toLanguageTag();
    }
 
    private String insertAspectModelDiagram( final String html, final Locale language ) {
-      final AspectModelDiagramGenerator diagramGenerator = new AspectModelDiagramGenerator( aspect );
+      final AspectModelDiagramGenerator diagramGenerator = new AspectModelDiagramGenerator( aspect() );
       final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
       diagramGenerator.generateDiagram( AspectModelDiagramGenerator.Format.SVG, language, buffer );
       final String encodedImage = "data:image/svg+xml;base64," + Base64.getEncoder().encodeToString( buffer.toByteArray() );

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/json/AspectModelJsonPayloadGenerator.java

@@ -104,7 +104,7 @@ public AspectModelJsonPayloadGenerator( final Aspect aspect, final Random random
 
    @Override
    public Stream<JsonPayloadArtifact> generate() {
-      return Stream.of( new PayloadGenerator( objectMapper ).apply( aspect, config ) );
+      return Stream.of( new PayloadGenerator( objectMapper ).apply( aspect(), config ) );
    }
 
    private static class PayloadGenerator

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/jsonld/AspectModelToJsonLdGenerator.java

@@ -43,12 +43,12 @@ public AspectModelToJsonLdGenerator( final Aspect aspect, final JsonLdGeneration
    @Override
    public Stream<JsonLdArtifact> generate() {
       final StringWriter stringWriter = new StringWriter();
-      aspect.getSourceFile().sourceModel().write( stringWriter, RDFLanguages.strLangJSONLD );
+      aspect().getSourceFile().sourceModel().write( stringWriter, RDFLanguages.strLangJSONLD );
       final String content = stringWriter.toString();
       try {
-         return Stream.of( new JsonLdArtifact( aspect.getName() + ".json", objectMapper.readTree( content ) ) );
+         return Stream.of( new JsonLdArtifact( aspect().getName() + ".json", objectMapper.readTree( content ) ) );
       } catch ( final JsonProcessingException exception ) {
-         LOG.error( "Could not parse JSON-LD for {}", aspect.getName() );
+         LOG.error( "Could not parse JSON-LD for {}", aspect().getName() );
       }
       return Stream.empty();
    }

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/jsonschema/AspectModelJsonSchemaGenerator.java

@@ -51,7 +51,7 @@ public JsonSchemaArtifact apply( final Aspect aspect, final JsonSchemaGeneration
    @Override
    public Stream<JsonSchemaArtifact> generate() {
       final AspectModelJsonSchemaVisitor visitor = new AspectModelJsonSchemaVisitor( config );
-      final JsonNode result = aspect.accept( visitor, null );
-      return Stream.of( new JsonSchemaArtifact( aspect.getName(), result ) );
+      final JsonNode result = aspect().accept( visitor, null );
+      return Stream.of( new JsonSchemaArtifact( aspect().getName(), result ) );
    }
 }

core/esmf-aspect-model-document-generators/src/main/java/org/eclipse/esmf/aspectmodel/generator/openapi/AspectModelOpenApiGenerator.java

@@ -48,7 +48,6 @@
 import org.eclipse.esmf.metamodel.Property;
 
 import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.JsonNodeFactory;
 import com.fasterxml.jackson.databind.node.ObjectNode;
@@ -133,23 +132,23 @@ public Stream<OpenApiSchemaArtifact> generate() {
       OpenApiSchemaArtifact artifact;
       try {
          final ObjectNode rootNode = getRootJsonNode( config.generateCommentForSeeAttributes() );
-         final String apiVersion = getApiVersion( aspect, config.useSemanticVersion() );
+         final String apiVersion = getApiVersion( aspect(), config.useSemanticVersion() );
 
          ( (ObjectNode) rootNode.get( "info" ) )
-               .put( "title", aspect.getPreferredName( config.locale() ) )
+               .put( "title", aspect().getPreferredName( config.locale() ) )
                .put( "version", apiVersion )
-               .put( AbstractGenerator.SAMM_EXTENSION, aspect.urn().toString() );
+               .put( AbstractGenerator.SAMM_EXTENSION, aspect().urn().toString() );
          setServers( rootNode, config.baseUrl(), apiVersion, READ_SERVER_PATH );
-         final boolean includePaging = includePaging( aspect, config.pagingOption() );
-         setOptionalSchemas( aspect, config, includePaging, rootNode );
-         setAspectSchemas( aspect, config, rootNode );
-         setRequestBodies( aspect, config, rootNode );
-         setResponseBodies( aspect, rootNode, includePaging );
-         rootNode.set( "paths", getPathsNode( aspect, config, apiVersion, config.properties(), config.queriesTemplate() ) );
-         artifact = new OpenApiSchemaArtifact( aspect.getName(), merge( rootNode, config.documentTemplate() ) );
+         final boolean includePaging = includePaging( aspect(), config.pagingOption() );
+         setOptionalSchemas( aspect(), config, includePaging, rootNode );
+         setAspectSchemas( aspect(), config, rootNode );
+         setRequestBodies( aspect(), config, rootNode );
+         setResponseBodies( aspect(), rootNode, includePaging );
+         rootNode.set( "paths", getPathsNode( aspect(), config, apiVersion, config.properties(), config.queriesTemplate() ) );
+         artifact = new OpenApiSchemaArtifact( aspect().getName(), merge( rootNode, config.documentTemplate() ) );
       } catch ( final Exception exception ) {
          LOG.error( "There was an exception during the read of the root or the validation.", exception );
-         artifact = new OpenApiSchemaArtifact( aspect.getName(), FACTORY.objectNode() );
+         artifact = new OpenApiSchemaArtifact( aspect().getName(), FACTORY.objectNode() );
       }
       return Stream.of( artifact );
    }

core/esmf-aspect-model-document-generators/src/test/java/org/eclipse/esmf/aspectmodel/generator/jsonld/AspectModelJsonLdGeneratorTest.java

@@ -20,18 +20,11 @@ void generateTest() {
    }
 
    private void assertJsonLdMeta( final String generatedJsonLd, final AspectModelUrn aspectModelUrn ) {
-      final String context = """
-            "@context": {
-                    "xsd": "http://www.w3.org/2001/XMLSchema#",
-                    "samm-c": "urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#",
-                    "samm": "urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#",
-                    "@vocab": "urn:samm:org.eclipse.esmf.test:1.0.0#"
-                }
-            """;
-
-      assertThat( generatedJsonLd ).contains( "\"@graph\": [" );
-      assertThat( generatedJsonLd ).contains( context );
-      assertThat( generatedJsonLd ).contains( "\"xsd\": \"http://www.w3.org/2001/XMLSchema#\"," );
-      assertThat( generatedJsonLd ).contains( String.format( "\"@id\": \"%s\"", aspectModelUrn.toString() ) );
+      assertThat( generatedJsonLd ).contains( "\"@graph\" : [" );
+      assertThat( generatedJsonLd ).contains( "\"xsd\" : \"http://www.w3.org/2001/XMLSchema#\"," );
+      assertThat( generatedJsonLd ).contains( "\"samm-c\" : \"urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#\"" );
+      assertThat( generatedJsonLd ).contains( "\"samm\" : \"urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#\"" );
+      assertThat( generatedJsonLd ).contains( "\"@vocab\" : \"urn:samm:org.eclipse.esmf.test:1.0.0#\"" );
+      assertThat( generatedJsonLd ).contains( String.format( "\"@id\" : \"%s\"", aspectModelUrn.toString() ) );
    }
 }

core/esmf-aspect-model-generator/src/main/java/org/eclipse/esmf/aspectmodel/generator/AspectGenerator.java

@@ -13,51 +13,33 @@
 
 package org.eclipse.esmf.aspectmodel.generator;
 
-import java.io.IOException;
-import java.io.OutputStream;
-import java.io.OutputStreamWriter;
-import java.io.Writer;
-import java.nio.charset.StandardCharsets;
-import java.util.Comparator;
-import java.util.function.Function;
 import java.util.stream.Stream;
 
 import org.eclipse.esmf.aspectmodel.visitor.AspectStreamTraversalVisitor;
 import org.eclipse.esmf.metamodel.Aspect;
 import org.eclipse.esmf.metamodel.ModelElement;
 
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 /**
- * Base class for the generation of {@link Artifact}s.
+ * Base class for the generation of {@link Artifact}s from a single {@link Aspect}.
  *
  * @param <I> the type that uniquely identifies the artifact in the scope of the generation process
  * @param <T> the artifact's content type, e.g. String or byte[]
  * @param <C> the config object for the genererator
  * @param <A> the type of the artifact that is generated
  */
-public abstract class Generator<I, T, C extends GenerationConfig, A extends Artifact<I, T>> {
-   private static final Logger LOG = LoggerFactory.getLogger( Generator.class );
-   protected final C config;
-   protected final Aspect aspect;
-   protected final Comparator<ModelElement> uniqueByModelElementIdentifier = ( modelElementOne, modelElementTwo ) -> {
-      final String modelElementOneIdentifier = modelElementOne.urn().toString();
-      final String modelElementTwoIdentifier = modelElementTwo.urn().toString();
-      return modelElementOneIdentifier.compareTo( modelElementTwoIdentifier );
-   };
+public abstract class AspectGenerator<I, T, C extends GenerationConfig, A extends Artifact<I, T>>
+      extends Generator<Aspect, I, T, C, A> {
 
-   protected Generator( final Aspect aspect, final C config ) {
-      this.aspect = aspect;
-      this.config = config;
+   protected AspectGenerator( final Aspect aspect, final C config ) {
+      super( aspect, config );
    }
 
-   public C getConfig() {
-      return config;
+   protected Aspect aspect() {
+      return focus;
    }
 
    protected <E extends ModelElement> Stream<E> elements( final Class<E> clazz ) {
-      return aspect.accept( new AspectStreamTraversalVisitor(), null )
+      return aspect().accept( new AspectStreamTraversalVisitor(), null )
             .filter( clazz::isInstance )
             .map( clazz::cast )
             .sorted( uniqueByModelElementIdentifier )
@@ -68,57 +50,4 @@ protected <E extends ModelElement> Stream<A> applyTemplate(
          final Class<E> clazz, final ArtifactGenerator<I, T, E, C, A> artifactGenerator, final C config ) {
       return elements( clazz ).map( element -> artifactGenerator.apply( element, config ) );
    }
-
-   /**
-    * Generates artifacts from the given Aspect model. As this generation may produce multiple artifacts, the generator
-    * provides the caller with the identifer of the respective artifact via the callback function. The caller needs to
-    * provide an {@link OutputStream} for the artifact, e.g. a suitable FileOutputStream.
-    *
-    * @param nameMapper the callback function that maps artifact identifiers to OutputStreams
-    */
-   public void generate( final Function<I, OutputStream> nameMapper ) {
-      generate().toList().forEach( generationResult -> write( generationResult, nameMapper ) );
-   }
-
-   /**
-    * Generates artifacts for the given Aspect model
-    *
-    * @return the stream of artifacts
-    */
-   public abstract Stream<A> generate();
-
-   /**
-    * Assumes that the generator returns exactly one artifact and returns this
-    *
-    * @return the generated artifact
-    */
-   public A singleResult() {
-      return generate()
-            .findFirst()
-            .orElseThrow( () -> new GenerationException( "Could not generate artifact for " + aspect.getName() ) );
-   }
-
-   /**
-    * Assumes that the generator returns exactly one artifact and returns its content
-    *
-    * @return the artifact's content
-    */
-   public T getContent() {
-      return singleResult().getContent();
-   }
-
-   /**
-    * Writes an artifact to the corresponding output stream
-    *
-    * @param artifact the artifact
-    * @param nameMapper the function that provides the output stream for the artifact
-    */
-   protected void write( final Artifact<I, T> artifact, final Function<I, OutputStream> nameMapper ) {
-      try ( final OutputStream output = nameMapper.apply( artifact.getId() ) ) {
-         output.write( artifact.serialize() );
-         output.flush();
-      } catch ( final IOException exception ) {
-         LOG.error( "Failure during writing of generated artifact", exception );
-      }
-   }
 }

core/esmf-aspect-model-generator/src/main/java/org/eclipse/esmf/aspectmodel/generator/BinaryArtifact.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2024 Bosch Software Innovations GmbH. All rights reserved.
+ */
+
+package org.eclipse.esmf.aspectmodel.generator;
+
+public abstract class BinaryArtifact implements Artifact<String, byte[]> {
+   private final String id;
+   private final byte[] content;
+
+   public BinaryArtifact( final String id, final byte[] content ) {
+      this.id = id;
+      this.content = content;
+   }
+
+   @Override
+   public String getId() {
+      return id;
+   }
+
+   @Override
+   public byte[] getContent() {
+      return content;
+   }
+
+   @Override
+   public byte[] serialize() {
+      return content;
+   }
+}