Merge pull request #287 from bci-oss/278-handle-models-with-multiple-aspects

Handle models with any number of Aspects in artifact generators

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

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 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 io.openmanufacturing.sds.metamodel;
+
+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 ) {