Handle models with any number of Aspects in artifact generators

This adjusts the constructors of the document and code generators so that the
Aspect they intend to work on must be passed as an explicit argument. For that
the `AspectContext` is introduced which wraps a `VersionedModel` and a single
`Aspect` that is contained in the model. The task to determine the Aspect from
the loaded model is delegated to the caller (here bamm-cli and Maven plugin).

Author: atextor

core/sds-aspect-meta-model-interface/src/main/java/io/openmanufacturing/sds/aspectmodel/resolver/AspectMetaModelResourceResolver.java

@@ -43,20 +43,6 @@ public interface AspectMetaModelResourceResolver {
     */
    Try<VersionedModel> mergeMetaModelIntoRawModel( final Model rawModel, final VersionNumber version );
 
-   /**
-    * Parses an Aspect (meta) model URN into an {@link AspectModelUrn}
-    *
-    * @param uri The Aspect (meta) model URN
-    * @return The {@link AspectModelUrn} if parsing succeeds, an {@link UrnSyntaxException} otherwise
-    */
-   default Try<AspectModelUrn> getAspectModelUrn( final String uri ) {
-      try {
-         return Try.success( AspectModelUrn.fromUrn( uri ) );
-      } catch ( final UrnSyntaxException exception ) {
-         return Try.failure( exception );
-      }
-   }
-
    /**
     * Retrieves the meta model version an Aspect model uses
     *

core/sds-aspect-meta-model-java/src/main/java/io/openmanufacturing/sds/metamodel/AspectContext.java

@@ -15,5 +15,11 @@
 
 import io.openmanufacturing.sds.aspectmodel.resolver.services.VersionedModel;
 
+/**
+ * The AspectContext wraps a loaded/resolved Aspect Model and a single Aspect that was instantiated from this model, i.e.,
+ * which must be defined in the RDF model.
+ * @param rdfModel the RDF model
+ * @param aspect the Aspect
+ */
 public record AspectContext(VersionedModel rdfModel, Aspect aspect) {
 }

core/sds-aspect-meta-model-java/src/main/java/io/openmanufacturing/sds/metamodel/loader/AspectModelLoader.java

@@ -13,11 +13,13 @@
 
 package io.openmanufacturing.sds.metamodel.loader;
 
+import java.io.File;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
 import org.apache.jena.rdf.model.Model;
@@ -41,6 +43,7 @@
 import io.openmanufacturing.sds.aspectmodel.versionupdate.MigratorService;
 import io.openmanufacturing.sds.aspectmodel.vocabulary.BAMM;
 import io.openmanufacturing.sds.metamodel.Aspect;
+import io.openmanufacturing.sds.metamodel.AspectContext;
 import io.openmanufacturing.sds.metamodel.ModelElement;
 import io.openmanufacturing.sds.metamodel.ModelNamespace;
 import io.openmanufacturing.sds.metamodel.NamedElement;
@@ -79,7 +82,7 @@ private AspectModelLoader() {
     *
     * @see AspectModelResolver
     */
-   @Deprecated
+   @Deprecated( forRemoval = true )
    public static Try<Aspect> fromVersionedModel( final VersionedModel versionedModel ) {
       return getSingleAspect( versionedModel );
    }
@@ -103,12 +106,12 @@ private static void validateNamespaceOfCustomUnits( final BAMM bamm, final Model
     * Creates an {@link Aspect} instance from a Turtle input model.
     *
     * @param versionedModel The RDF model representation of the Aspect model
-    * @return The Aspect *
+    * @return The Aspect
     * @deprecated use {@link #getSingleAspectUnchecked(VersionedModel)} instead to retain the same semantics, but better use
     * {@link #getElementsUnchecked(VersionedModel)} instead to also properly handle models that contain not exactly one Aspect
     * @see #fromVersionedModel(VersionedModel)
     */
-   @Deprecated
+   @Deprecated( forRemoval = true )
    public static Aspect fromVersionedModelUnchecked( final VersionedModel versionedModel ) {
       return fromVersionedModel( versionedModel ).getOrElseThrow( cause -> {
          LOG.error( "Could not load Aspect", cause );
@@ -228,12 +231,7 @@ public static List<Aspect> getAspectsUnchecked( final VersionedModel versionedMo
     * @return the single Aspect contained in the model
     */
    public static Try<Aspect> getSingleAspect( final VersionedModel versionedModel ) {
-      return getAspects( versionedModel ).flatMap( aspects -> {
-         if ( aspects.size() != 1 ) {
-            return Try.failure( new InvalidRootElementCountException( "Aspect model does not contain exactly one Aspect" ) );
-         }
-         return Try.success( aspects.get( 0 ) );
-      } );
+      return getSingleAspect( versionedModel, aspect -> true );
    }
 
    /**
@@ -252,4 +250,40 @@ public static Aspect getSingleAspectUnchecked( final VersionedModel versionedMod
          throw new AspectLoadingException( cause );
       } );
    }
+
+   /**
+    * Similar to {@link #getSingleAspect(VersionedModel)}, except that a predicate can be provided to select which of potentially
+    * multiple aspects should be selected
+    * @param versionedModel the RDF model reprensentation of the Aspect model
+    * @param selector the predicate to select an Aspect
+    * @return the selected Aspect, or a failure if 0 or more than 1 matching Aspects were found
+    */
+   public static Try<Aspect> getSingleAspect( final VersionedModel versionedModel, final Predicate<Aspect> selector ) {
+      return getAspects( versionedModel ).flatMap( allAspects -> {
+         final List<Aspect> aspects = allAspects.stream().filter( selector::test ).toList();
+         return switch ( aspects.size() ) {
+            case 1 -> Try.success( aspects.iterator().next() );
+            case 0 -> Try.failure( new InvalidRootElementCountException( "No Aspects were found in the model" ) );
+            default -> Try.failure( new AspectLoadingException( "Multiple Aspects were found in the resolved model" ) );
+         };
+      } );
+   }
+
+   /**
+    * Convenience method to create an {@link AspectContext} directly from a model file. This method makes the following assumptions:
+    * <ul>
+    *    <li>The model file is located in a directory structure as required by the {@link io.openmanufacturing.sds.aspectmodel.resolver.FileSystemStrategy}</li>
+    *    <li>The closure of the loaded model contains exactly one Aspect</li>
+    *    <li>The Aspect has the same name as the file's basename</li>
+    * </ul>
+    * The method is intended for use in tests and comparable use cases, not as a general replacement for loading Aspect Models, since it does not
+    * handle model files with less or more than one Aspect.
+    * @param input the model file
+    * @return the loaded Aspect Context
+    */
+   public static Try<AspectContext> getAspectContext( final File input ) {
+      return AspectModelResolver.loadAndResolveModel( input ).flatMap( versionedModel ->
+            getSingleAspect( versionedModel, aspect -> aspect.getName().equals( input.getName() ) )
+                  .map( aspect -> new AspectContext( versionedModel, aspect ) ) );
+   }
 }

core/sds-aspect-meta-model-java/src/main/java/io/openmanufacturing/sds/metamodel/loader/MetaModelBaseAttributes.java

@@ -203,15 +203,15 @@ private static String getSyntheticName( final Resource modelElement, final Model
          throw new AspectLoadingException( "At least one anonymous node in the model does not have a parent with a regular name." );
       }
       final String parentModelElementUri = namedParent.getURI();
-      final String parentModelElementName = metaModelResourceResolver.getAspectModelUrn( parentModelElementUri )
+      final String parentModelElementName = AspectModelUrn.from( parentModelElementUri )
             .toJavaOptional()
             .map( AspectModelUrn::getName )
             .map( StringUtils::capitalize )
             .orElse( "" );
 
       final Resource modelElementType = getModelElementType( modelElement, bamm );
       final String modelElementTypeUri = modelElementType.getURI();
-      final String modelElementTypeName = metaModelResourceResolver.getAspectModelUrn( modelElementTypeUri )
+      final String modelElementTypeName = AspectModelUrn.from( modelElementTypeUri )
             .toJavaOptional()
             .map( AspectModelUrn::getName )
             .orElse( "" );

core/sds-aspect-meta-model-resolver/src/main/java/io/openmanufacturing/sds/aspectmodel/resolver/services/SdsAspectMetaModelResourceResolver.java

@@ -220,7 +220,7 @@ public Set<VersionNumber> getUsedMetaModelVersions( final Model model ) {
             .map( RDFNode::asResource )
             .map( Resource::getURI )
             .filter( uri -> uri.startsWith( bammUrnStart ) )
-            .flatMap( uri -> getAspectModelUrn( uri ).toJavaStream() )
+            .flatMap( uri -> AspectModelUrn.from( uri ).toJavaStream() )
             .filter( urn -> (urn.getElementType().equals( ElementType.META_MODEL ) || urn.getElementType().equals( ElementType.CHARACTERISTIC )) )
             .map( AspectModelUrn::getVersion )
             .map( VersionNumber::parse )

core/sds-aspect-meta-model-resolver/src/test/java/io/openmanufacturing/sds/aspectmodel/resolver/services/SdsAspectMetaModelResourceResolverTest.java

@@ -27,8 +27,8 @@
 import org.junit.jupiter.params.provider.MethodSource;
 
 import io.openmanufacturing.sds.aspectmetamodel.KnownVersion;
-import io.openmanufacturing.sds.aspectmodel.VersionNumber;
 import io.openmanufacturing.sds.aspectmodel.MissingMetaModelVersionException;
+import io.openmanufacturing.sds.aspectmodel.VersionNumber;
 import io.openmanufacturing.sds.aspectmodel.urn.AspectModelUrn;
 import io.openmanufacturing.sds.test.MetaModelVersions;
 import io.vavr.control.Try;
@@ -82,20 +82,18 @@ public void testGetBammVersionInvalidMetaModelUrnElementExpectFailure( final Kno
    @ParameterizedTest
    @MethodSource( "allVersions" )
    public void testGetAspectModelUrnExpectSuccess( final KnownVersion metaModelVersion ) {
-      final Try<AspectModelUrn> aspectModelUrn = aspectMetaModelResourceResolver.getAspectModelUrn(
+      final Try<AspectModelUrn> aspectModelUrn = AspectModelUrn.from(
             "urn:bamm:io.openmanufacturing:meta-model:" + metaModelVersion.toVersionString() + "#Aspect" );
       assertThat( aspectModelUrn ).isSuccess();
       org.assertj.core.api.Assertions.assertThat( aspectModelUrn.get().getUrn().toString() )
-                                     .isEqualTo( "urn:bamm:io.openmanufacturing:meta-model:" + metaModelVersion
-                                           .toVersionString() + "#Aspect" );
+            .isEqualTo( "urn:bamm:io.openmanufacturing:meta-model:" + metaModelVersion
+                  .toVersionString() + "#Aspect" );
    }
 
    @ParameterizedTest
    @MethodSource( "allVersions" )
    public void testGetAspectModelUrnInvalidUrnExpectFailure( final KnownVersion metaModelVersion ) {
-      final Try<AspectModelUrn> aspectModelUrn = aspectMetaModelResourceResolver
-            .getAspectModelUrn(
-                  "urn:foo:io.openmanufacturing:meta-model:" + metaModelVersion.toVersionString() );
+      final Try<AspectModelUrn> aspectModelUrn = AspectModelUrn.from( "urn:foo:io.openmanufacturing:meta-model:" + metaModelVersion.toVersionString() );
       assertThat( aspectModelUrn ).isFailure();
    }
 
@@ -120,7 +118,7 @@ public void testLoadMetaModelExpectSuccess( final KnownVersion metaModelVersion
       final Model model = aspectMetaModelResourceResolver.loadMetaModel( metaModelVersion ).get();
 
       org.assertj.core.api.Assertions.assertThat( model.contains( ResourceFactory.createResource(
-            "urn:bamm:io.openmanufacturing:meta-model:" + metaModelVersion.toVersionString() + "#value" ),
+                  "urn:bamm:io.openmanufacturing:meta-model:" + metaModelVersion.toVersionString() + "#value" ),
             RDF.type, (RDFNode) null ) ).isTrue();
    }
 }

core/sds-aspect-model-aas-generator/src/test/java/io/openmanufacturing/sds/aspectmodel/aas/AspectModelAASGeneratorTest.java

@@ -264,7 +264,7 @@ private AssetAdministrationShellEnvironment getAssetAdministrationShellFromAspec
 
    private Aspect loadAspect( final TestAspect testAspect ) {
       final VersionedModel model = TestResources.getModel( testAspect, KnownVersion.getLatest() ).get();
-      return AspectModelLoader.fromVersionedModelUnchecked( model );
+      return AspectModelLoader.getSingleAspectUnchecked( model );
    }
 
    private AssetAdministrationShellEnvironment loadAASX( final ByteArrayOutputStream byteStream ) throws DeserializationException {

core/sds-aspect-model-document-generators/src/main/java/io/openmanufacturing/sds/aspectmodel/generator/AspectModelHelper.java

@@ -21,7 +21,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
-import io.openmanufacturing.sds.aspectmodel.resolver.services.VersionedModel;
+import io.openmanufacturing.sds.aspectmetamodel.KnownVersion;
 import io.openmanufacturing.sds.metamodel.Aspect;
 import io.openmanufacturing.sds.metamodel.ModelElement;
 import io.openmanufacturing.sds.metamodel.ComplexType;
@@ -35,14 +35,14 @@
 import io.openmanufacturing.sds.metamodel.visitor.AspectStreamTraversalVisitor;
 
 public class AspectModelHelper {
-   private final VersionedModel modelVersion;
+   private final KnownVersion metaModelVersion;
 
-   public AspectModelHelper( final VersionedModel modelVersion ) {
-      this.modelVersion = modelVersion;
+   public AspectModelHelper( final KnownVersion metaModelVersion ) {
+      this.metaModelVersion = metaModelVersion;
    }
 
-   public VersionedModel getModelVersion() {
-      return modelVersion;
+   public KnownVersion getMetaModelVersion() {
+      return metaModelVersion;
    }
 
    public static List<Property> sortPropertiesByPreferredName( final List<Property> properties, final Locale locale ) {

core/sds-aspect-model-document-generators/src/main/java/io/openmanufacturing/sds/aspectmodel/generator/docu/AspectModelDocumentationGenerator.java

@@ -40,11 +40,10 @@
 import io.openmanufacturing.sds.aspectmodel.generator.LanguageCollector;
 import io.openmanufacturing.sds.aspectmodel.generator.TemplateEngine;
 import io.openmanufacturing.sds.aspectmodel.generator.diagram.AspectModelDiagramGenerator;
-import io.openmanufacturing.sds.aspectmodel.resolver.services.VersionedModel;
 import io.openmanufacturing.sds.metamodel.Aspect;
+import io.openmanufacturing.sds.metamodel.AspectContext;
 import io.openmanufacturing.sds.metamodel.NamedElement;
 import io.openmanufacturing.sds.metamodel.Scalar;
-import io.openmanufacturing.sds.metamodel.loader.AspectModelLoader;
 import io.openmanufacturing.sds.metamodel.visitor.AspectStreamTraversalVisitor;
 
 /**
@@ -76,17 +75,15 @@ public String getArtifactFilename( final String artifactName ) {
       }
    }
 
-   private final Aspect aspect;
-   private final VersionedModel versionedModel;
+   private final AspectContext context;
    private Locale selectedLanguage = null;
 
-   public AspectModelDocumentationGenerator( final VersionedModel versionedModel ) {
-      this.versionedModel = versionedModel;
-      aspect = AspectModelLoader.fromVersionedModelUnchecked( versionedModel );
+   public AspectModelDocumentationGenerator( final AspectContext context ) {
+      this.context = context;
    }
 
-   public AspectModelDocumentationGenerator( final String language, final VersionedModel versionedModel ) {
-      this( versionedModel );
+   public AspectModelDocumentationGenerator( final String language, final AspectContext context ) {
+      this( context );
       selectedLanguage = Locale.forLanguageTag( language );
    }
 
@@ -160,7 +157,7 @@ private void generateInternal( final Function<String, OutputStream> nameMapper,
    }
 
    private void generateHtmlDocu( final Function<String, OutputStream> nameMapper, final Format format, final Locale desiredLanguage ) {
-      final Set<Locale> languagesInModel = LanguageCollector.collectUsedLanguages( aspect );
+      final Set<Locale> languagesInModel = LanguageCollector.collectUsedLanguages( context.aspect() );
       if ( !languagesInModel.contains( desiredLanguage ) ) {
          throw new RuntimeException( String.format( "The model does not contain the desired language: %s.", desiredLanguage.toString() ) );
       }
@@ -169,15 +166,15 @@ private void generateHtmlDocu( final Function<String, OutputStream> nameMapper,
    }
 
    private void generateHtmlDocu( final Function<String, OutputStream> nameMapper, final Format format ) {
-      final Set<Locale> languagesInModel = LanguageCollector.collectUsedLanguages( aspect );
+      final Set<Locale> languagesInModel = LanguageCollector.collectUsedLanguages( context.aspect() );
       final Set<Locale> languages = languagesInModel.isEmpty() ? Set.of( Locale.ENGLISH ) : languagesInModel;
       generateHtmlDocu( nameMapper, format, languages );
    }
 
    private void generateHtmlDocu( final Function<String, OutputStream> nameMapper, final Format format, final Set<Locale> languages ) {
-      final Map<String, Object> context = new HashMap<>();
-      context.put( "aspectModel", aspect );
-      context.put( "aspectModelHelper", new AspectModelHelper( versionedModel ) );
+      final Map<String, Object> configuration = new HashMap<>();
+      configuration.put( "aspectModel", context.aspect() );
+      configuration.put( "aspectModelHelper", new AspectModelHelper( context.aspect().getMetaModelVersion() ) );
 
       final Properties engineConfiguration = new Properties();
       engineConfiguration.put( "file.resource.loader.path", ".," + DOCU_TEMPLATE_ROOT_DIR + "/html" );
@@ -194,13 +191,13 @@ private void generateHtmlDocu( final Function<String, OutputStream> nameMapper,
       final Predicate<Locale> byLanguage = locale -> selectedLanguage == null || locale.getLanguage().equals( selectedLanguage.getLanguage() );
       languages.stream().filter( byLanguage ).forEach( language -> {
 
-         logMissingTranslations( aspect, language );
+         logMissingTranslations( context.aspect(), language );
 
-         context.put( "i18n", new I18nLanguageBundle( language ) );
-         context.put( "Scalar", Scalar.class );
-         final TemplateEngine templateEngine = new TemplateEngine( context, engineConfiguration );
+         configuration.put( "i18n", new I18nLanguageBundle( language ) );
+         configuration.put( "Scalar", Scalar.class );
+         final TemplateEngine templateEngine = new TemplateEngine( configuration, engineConfiguration );
 
-         final String artifactName = getArtifactName( aspect, language );
+         final String artifactName = getArtifactName( context.aspect(), language );
          if ( nameMapper instanceof BufferingNameMapper ) {
             ((BufferingNameMapper) nameMapper).setLanguageForArtifact( artifactName, language );
          }
@@ -244,7 +241,7 @@ private String byteArrayOutputStreamToString( final ByteArrayOutputStream output
    }
 
    private String insertAspectModelDiagram( final String html, final Locale language ) throws IOException {
-      final AspectModelDiagramGenerator diagramGenerator = new AspectModelDiagramGenerator( versionedModel );
+      final AspectModelDiagramGenerator diagramGenerator = new AspectModelDiagramGenerator( context.rdfModel() );
       final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
       diagramGenerator.generateDiagram( AspectModelDiagramGenerator.Format.SVG, language, buffer );
       final String encodedImage = "data:image/svg+xml;base64," +

core/sds-aspect-model-document-generators/src/main/java/io/openmanufacturing/sds/aspectmodel/generator/json/AspectModelJsonPayloadGenerator.java

@@ -58,7 +58,6 @@
 import io.openmanufacturing.sds.aspectmodel.generator.NumericTypeTraits;
 import io.openmanufacturing.sds.aspectmodel.jackson.AspectModelJacksonModule;
 import io.openmanufacturing.sds.aspectmodel.resolver.services.DataType;
-import io.openmanufacturing.sds.aspectmodel.resolver.services.VersionedModel;
 import io.openmanufacturing.sds.aspectmodel.vocabulary.BAMM;
 import io.openmanufacturing.sds.characteristic.Collection;
 import io.openmanufacturing.sds.characteristic.Either;
@@ -70,6 +69,7 @@
 import io.openmanufacturing.sds.constraint.RegularExpressionConstraint;
 import io.openmanufacturing.sds.metamodel.AbstractEntity;
 import io.openmanufacturing.sds.metamodel.Aspect;
+import io.openmanufacturing.sds.metamodel.AspectContext;
 import io.openmanufacturing.sds.metamodel.Characteristic;
 import io.openmanufacturing.sds.metamodel.ComplexType;
 import io.openmanufacturing.sds.metamodel.Constraint;
@@ -81,7 +81,6 @@
 import io.openmanufacturing.sds.metamodel.Value;
 import io.openmanufacturing.sds.metamodel.datatypes.Curie;
 import io.openmanufacturing.sds.metamodel.impl.BoundDefinition;
-import io.openmanufacturing.sds.metamodel.loader.AspectModelLoader;
 
 public class AspectModelJsonPayloadGenerator extends AbstractGenerator {
    /**
@@ -102,8 +101,8 @@ public AspectModelJsonPayloadGenerator( final Aspect aspect ) {
       this( aspect, new BAMM( aspect.getMetaModelVersion() ), new Random() );
    }
 
-   public AspectModelJsonPayloadGenerator( final VersionedModel versionedModel ) {
-      this( AspectModelLoader.fromVersionedModelUnchecked( versionedModel ) );
+   public AspectModelJsonPayloadGenerator( final AspectContext context ) {
+      this( context.aspect() );
    }
 
    public AspectModelJsonPayloadGenerator( final Aspect aspect, final Random randomStrategy ) {