Clean up and add comments

Author: atextor

core/sds-aspect-model-resolver/src/main/java/io/openmanufacturing/sds/aspectmodel/resolver/AspectModelResolver.java

@@ -84,7 +84,7 @@ public Try<VersionedModel> resolveAspectModel( final ResolutionStrategy resolver
 
       if ( mergedModel.isFailure() ) {
          if ( mergedModel.getCause() instanceof FileNotFoundException ) {
-            return Try.failure( new ModelResolutionException( mergedModel.getCause() ) );
+            return Try.failure( new ModelResolutionException( "While trying to resolve " + input + ": " + mergedModel.getCause() ) );
          }
          return Try.failure( mergedModel.getCause() );
       }
@@ -133,6 +133,14 @@ public static boolean containsDefinition( final Model model, final AspectModelUr
       return model.contains( model.createResource( urn.toString() ), RDF.type, (RDFNode) null );
    }
 
+   /**
+    * The main model resolution method that takes an Aspect Model element URN and a resolution strategy as input.
+    * The strategy is applied to the URN to load a model, and then repeated for all URNs in the loaded model that
+    * have not yet been loaded.
+    * @param urn the Aspect Model element URN
+    * @param resolutionStrategy the resolution strategy that knowns how to turn a URN into a Model
+    * @return the fully resolved model, or a failure if one of the transitively referenced elements can't be found
+    */
    private Try<Model> resolve( final String urn, final ResolutionStrategy resolutionStrategy ) {
       final Model result = ModelFactory.createDefaultModel();
       final Stack<String> unresolvedUrns = new Stack<>();
@@ -147,14 +155,17 @@ private Try<Model> resolve( final String urn, final ResolutionStrategy resolutio
          }
          final Model model = resolvedModel.get();
 
-         // Merge the resolved model into the target if it was not already merged before
-         // (because the model contains more than one definition)
+         // Merge the resolved model into the target if it was not already merged before.
+         // It could have been merged before when the model contains another model definition that was already resolved
          if ( !mergedModels.contains( model ) ) {
             mergeModels( result, model );
             mergedModels.add( model );
          }
          for ( final String element : getAllUrnsInModel( model ) ) {
             if ( !result.contains( model.createResource( element ), RDF.type, (RDFNode) null )
+                  // Backwards compatibility with BAMM 1.0.0
+                  && !result.contains( model.createResource( element ), model.createProperty( "urn:bamm:io.openmanufacturing:meta-model:1.0.0#refines" ),
+                  (RDFNode) null )
                   && !unresolvedUrns.contains( element ) ) {
                unresolvedUrns.push( element );
             }
@@ -166,6 +177,14 @@ private Try<Model> resolve( final String urn, final ResolutionStrategy resolutio
 
    private final Model EMPTY_MODEL = ModelFactory.createDefaultModel();
 
+   /**
+    * Applies a {@link ResolutionStrategy} to a URI to be resolved, but only if the URI is actually a valid {@link AspectModelUrn}.
+    * For meta model elements or other URIs, an empty model is returned. This method returns only a failure, when the used resolution
+    * strategy fails.
+    * @param urn the URN to resolve
+    * @param resolutionStrategy the resolution strategy to apply
+    * @return the model containing the defintion of the given model element
+    */
    private Try<Model> getModelForUrn( final String urn, final ResolutionStrategy resolutionStrategy ) {
       if ( urn.startsWith( RDF.getURI() ) || urn.startsWith( XSD.getURI() ) ) {
          return Try.success( EMPTY_MODEL );
@@ -189,6 +208,15 @@ private Try<Model> getModelForUrn( final String urn, final ResolutionStrategy re
       }
    }
 
+   /**
+    * Defensively merge a model into an existing target model. This means:
+    * <ul>
+    *    <li>Prefixes are only added when they are not already present, i.e., a model won't overwrite the empty prefix of the target model</li>
+    *    <li>Statements that have a blank node (including RDF lists) as their object won't be added</li>
+    * </ul>
+    * @param target the model to merge into
+    * @param other the model to be merged
+    */
    private void mergeModels( final Model target, final Model other ) {
       for ( final Map.Entry<String, String> prefixEntry : other.getNsPrefixMap().entrySet() ) {
          if ( !target.getNsPrefixMap().containsKey( prefixEntry.getKey() ) ) {

core/sds-aspect-model-resolver/src/main/java/io/openmanufacturing/sds/aspectmodel/resolver/ClasspathStrategy.java

@@ -173,6 +173,6 @@ public Try<Model> apply( final AspectModelUrn aspectModelUrn ) {
                   .getOrElse( false ) )
             .findFirst()
             .orElse( Try.failure( new FileNotFoundException(
-                  "The AspectModel: " + aspectModelUrn + " could not be found in directory: " + directory ) ) );
+                  "The model file " + aspectModelUrn + " could not be found in directory: " + directory ) ) );
    }
 }

core/sds-aspect-model-resolver/src/main/java/io/openmanufacturing/sds/aspectmodel/resolver/FileSystemStrategy.java

@@ -2,7 +2,7 @@
  * Copyright (c) 2021 Robert Bosch Manufacturing Solutions GmbH
  *
  * See the AUTHORS file(s) distributed with this work for additional
- * information regarding authorship. 
+ * 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
@@ -80,17 +80,16 @@ public Try<Model> apply( final AspectModelUrn aspectModelUrn ) {
             aspectModelUrn.getName(), directory );
 
       return Arrays.stream( Optional.ofNullable( directory.toFile().listFiles() ).orElse( new File[] {} ) )
-                   .filter( File::isFile )
-                   .filter( file -> file.getName().endsWith( ".ttl" ) )
-                   .map( File::toURI )
-                   .sorted()
-                   .map( this::loadFromUri )
-                   .filter( tryModel -> tryModel
-                         .map( model -> AspectModelResolver.containsDefinition( model, aspectModelUrn ) )
-                         .getOrElse( false ) )
-                   .findFirst()
-                   .orElse( Try.failure( new FileNotFoundException(
-                         "The AspectModel: " + aspectModelUrn.toString() + " could not be found in directory: "
-                               + directory ) ) );
+            .filter( File::isFile )
+            .filter( file -> file.getName().endsWith( ".ttl" ) )
+            .map( File::toURI )
+            .sorted()
+            .map( this::loadFromUri )
+            .filter( tryModel -> tryModel
+                  .map( model -> AspectModelResolver.containsDefinition( model, aspectModelUrn ) )
+                  .getOrElse( false ) )
+            .findFirst()
+            .orElse( Try.failure( new FileNotFoundException(
+                  "The model file " + aspectModelUrn.toString() + " could not be found in directory: " + directory ) ) );
    }
 }