Clean up exception handling and add comments

Author: atextor

core/esmf-aspect-meta-model-interface/src/main/java/org/eclipse/esmf/aspectmodel/AspectModelFile.java

@@ -23,19 +23,53 @@
 
 import org.apache.jena.rdf.model.Model;
 
+/**
+ * An AspectModelFile is the abstraction of one "code unit". When its source location is in a file system, the
+ * AspectModelFile corresponds to one file, but this does not have to be the case: An AspectModelFile could also
+ * exist in memory, or purely virtually (e.g., as an abstraction of a sub-graph in a triple store).
+ */
 public interface AspectModelFile extends ModelElementGroup {
+   /**
+    * The RDF model with the contents of this AspectModelFile
+    *
+    * @return the model
+    */
    Model sourceModel();
 
+   /**
+    * The list of Strings that are contained as a comment block at the start of the file. This is often used
+    * for copyright and license information.
+    *
+    * @return the header comment
+    */
    default List<String> headerComment() {
       return List.of();
    }
 
+   /**
+    * The URI that denominates the source location, if present. It can be a file:// or https:// URL, but it
+    * could for example also be an Aspect Model URN, if it refers to a file that is part of the SAMM specification.
+    * Generally, this should be the physical location, not a logical identifier, in other words, where was this
+    * AspectModelFile loaded from.
+    *
+    * @return the source location
+    */
    Optional<URI> sourceLocation();
 
+   /**
+    * Returns the {@link Namespace} this AspectModelFile is a part of
+    *
+    * @return the namespace
+    */
    default Namespace namespace() {
       throw new UnsupportedOperationException( "Uninitialized Aspect Model" );
    }
 
+   /**
+    * Lists the model elements that are contained in this AspectModelFile
+    *
+    * @return the model elements
+    */
    @Override
    default List<ModelElement> elements() {
       throw new UnsupportedOperationException( "Uninitialized Aspect Model" );

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/loader/AspectModelLoader.java

@@ -17,7 +17,6 @@
 import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.FileInputStream;
-import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URI;
@@ -209,14 +208,14 @@ public AspectModel load( final InputStream inputStream ) {
     */
    public AspectModel loadNamespacePackage( final File namespacePackage ) {
       if ( !namespacePackage.exists() || !namespacePackage.isFile() ) {
-         throw new RuntimeException( new FileNotFoundException( "The specified file does not exist or is not a file." ) );
+         throw new ModelResolutionException( "The specified file does not exist or is not a file." );
       }
 
       try ( final InputStream inputStream = new FileInputStream( namespacePackage ) ) {
          return loadNamespacePackage( inputStream );
-      } catch ( final IOException e ) {
-         LOG.error( "Error reading the file: {}", namespacePackage.getAbsolutePath(), e );
-         throw new RuntimeException( "Error reading the file: " + namespacePackage.getAbsolutePath(), e );
+      } catch ( final IOException exception ) {
+         LOG.error( "Error reading the file: {}", namespacePackage.getAbsolutePath(), exception );
+         throw new ModelResolutionException( "Error reading the file: " + namespacePackage.getAbsolutePath(), exception );
       }
    }
 
@@ -228,12 +227,13 @@ public AspectModel loadNamespacePackage( final File namespacePackage ) {
     */
    public AspectModel loadNamespacePackage( final InputStream inputStream ) {
       final ByteArrayOutputStream baos = new ByteArrayOutputStream();
+      final boolean hasAspectModelsFolder;
       try {
          inputStream.transferTo( baos );
-      } catch ( final IOException e ) {
-         throw new RuntimeException( e );
+         hasAspectModelsFolder = containsFolderInNamespacePackage( new ByteArrayInputStream( baos.toByteArray() ) );
+      } catch ( final IOException exception ) {
+         throw new ModelResolutionException( "Could not read from input", exception );
       }
-      final boolean hasAspectModelsFolder = containsFolderInNamespacePackage( new ByteArrayInputStream( baos.toByteArray() ) );
       return loadNamespacePackageFromStream( new ByteArrayInputStream( baos.toByteArray() ), hasAspectModelsFolder );
    }
 
@@ -245,8 +245,8 @@ private AspectModel loadNamespacePackageFromStream( final InputStream inputStrea
 
          while ( ( entry = zis.getNextEntry() ) != null ) {
             final boolean isRelevantEntry =
-                  ( hasAspectModelsFolder && entry.getName().contains( String.format( "%s/", ASPECT_MODELS_FOLDER ) ) && entry.getName()
-                        .endsWith( ".ttl" ) )
+                  ( hasAspectModelsFolder && entry.getName().contains( String.format( "%s/", ASPECT_MODELS_FOLDER ) )
+                        && entry.getName().endsWith( ".ttl" ) )
                         || ( !hasAspectModelsFolder && entry.getName().endsWith( ".ttl" ) );
 
             if ( isRelevantEntry ) {
@@ -256,26 +256,24 @@ private AspectModel loadNamespacePackageFromStream( final InputStream inputStrea
          }
 
          zis.closeEntry();
-      } catch ( final IOException e ) {
-         LOG.error( "Error reading the Archive input stream", e );
-         throw new RuntimeException( "Error reading the Archive input stream", e );
+      } catch ( final IOException exception ) {
+         LOG.error( "Error reading the Archive input stream", exception );
+         throw new ModelResolutionException( "Error reading the Archive input stream", exception );
       }
 
       final LoaderContext loaderContext = new LoaderContext();
       resolve( aspectModelFiles, loaderContext );
       return loadAspectModelFiles( loaderContext.loadedFiles() );
    }
 
-   private boolean containsFolderInNamespacePackage( final InputStream inputStream ) {
+   private boolean containsFolderInNamespacePackage( final InputStream inputStream ) throws IOException {
       try ( final ZipInputStream zis = new ZipInputStream( inputStream ) ) {
          ZipEntry entry;
          while ( ( entry = zis.getNextEntry() ) != null ) {
             if ( entry.isDirectory() && entry.getName().contains( String.format( "%s/", ASPECT_MODELS_FOLDER ) ) ) {
                return true;
             }
          }
-      } catch ( final IOException e ) {
-         throw new RuntimeException( e );
       }
       return false;
    }

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/loader/ModelElementFactory.java

@@ -83,6 +83,10 @@
 import org.apache.jena.vocabulary.RDF;
 import org.apache.jena.vocabulary.RDFS;
 
+/**
+ * Used as part of the loading process in the {@link AspectModelLoader}, it creates instance for the the {@link ModelElement}s
+ * in an AspectModel.
+ */
 public class ModelElementFactory extends AttributeValueRetriever {
    private final Model model;
    private final Map<Resource, Instantiator<?>> instantiators = new HashMap<>();
@@ -351,7 +355,7 @@ private static Resource getModelElementType( final Resource modelElement ) {
       return getModelElementType( superElement );
    }
 
-   public AspectModelFile getSourceLocation( Resource modelElement ) {
+   public AspectModelFile getSourceLocation( final Resource modelElement ) {
       return sourceLocator.apply( modelElement );
    }
 }

core/esmf-aspect-meta-model-java/src/main/java/org/eclipse/esmf/aspectmodel/resolver/modelfile/RawAspectModelFile.java

@@ -23,6 +23,15 @@
 import org.apache.jena.rdf.model.Model;
 import org.apache.jena.rdf.model.ModelFactory;
 
+/**
+ * An implementation of an {@link AspectModelFile} that knows about the RDF model content and source location, but has not
+ * instantiated the model elements yet. Calling {@link #elements()} on this file will throw an exception. It is intended
+ * to represent the intermediary result of loading an Aspect Model file, possibly from a remote location.
+ *
+ * @param sourceModel the source RDF model
+ * @param headerComment the header comment
+ * @param sourceLocation the source location
+ */
 @SuppressWarnings( "OptionalUsedAsFieldOrParameterType" )
 @RecordBuilder
 public record RawAspectModelFile(

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

@@ -37,6 +37,7 @@
 import java.util.stream.IntStream;
 import java.util.stream.LongStream;
 import java.util.stream.Stream;
+
 import javax.xml.datatype.DatatypeConfigurationException;
 import javax.xml.datatype.DatatypeFactory;
 
@@ -566,8 +567,8 @@ void testGeneratedNumbersAreWithinRange( final RDFDatatype numericModelType, fin
          assertNumberInRange( validator.getTestNumber(), randomRange, boundKind.orElse( null ) );
          assertMinValue( minValidator.getTestNumber(), randomRange.getLeft(), boundKind.orElse( null ) );
          assertMaxValue( maxValidator.getTestNumber(), randomRange.getRight(), boundKind.orElse( null ) );
-      } catch ( final IOException e ) {
-         throw new RuntimeException( e );
+      } catch ( final IOException exception ) {
+         throw new RuntimeException( exception );
       }
    }
 

core/esmf-aspect-model-github-resolver/src/test/java/org/eclipse/esmf/aspectmodel/resolver/github/GitHubStrategyTest.java

@@ -64,8 +64,8 @@ void afterEach() {
                            System.err.println( "Could not delete file " + file );
                         }
                      } );
-            } catch ( final IOException e ) {
-               throw new RuntimeException( e );
+            } catch ( final IOException exception ) {
+               throw new RuntimeException( exception );
             }
          }
       }

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/shacl/JsLibrary.java

@@ -36,7 +36,7 @@ public JsLibrary( final Optional<String> uri, final List<String> libraryUrls, fi
             code.append( new String( inputStream.readAllBytes(), StandardCharsets.UTF_8 ) );
             code.append( "\n" );
          } catch ( final IOException exception ) {
-            throw new RuntimeException( exception );
+            throw new ShaclValidationException( "Could not resolve JsLibrary " + uri, exception );
          }
       }
 

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/shacl/ShaclValidationException.java

@@ -25,4 +25,8 @@ public class ShaclValidationException extends RuntimeException {
    public ShaclValidationException( final String message ) {
       super( message );
    }
+
+   public ShaclValidationException( final String message, final Throwable cause ) {
+      super( message, cause );
+   }
 }

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/shacl/Shape.java

@@ -58,7 +58,7 @@ public static NodeKind forNode( final RDFNode node ) {
          if ( node.isAnon() ) {
             return Shape.NodeKind.BlankNode;
          }
-         throw new RuntimeException( "Invalid nodekind: " + node );
+         throw new ShaclValidationException( "Invalid nodekind: " + node );
       }
 
       public String humanReadable() {

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/shacl/ShapeLoader.java

@@ -135,7 +135,7 @@ Constraint>> builder()
          .put( SHACL.or(), context -> new OrConstraint( nestedShapesList( context.statement() ) ) )
          .put( SHACL.xone(), context -> new XoneConstraint( nestedShapesList( context.statement() ) ) )
          .put( SHACL.node(), context -> {
-            // Since sh:node can recursively refer to the same NodeShape is used in when shapes define recursive structures,
+            // Since sh:node can recursively refer to the same NodeShape it is used in when shapes define recursive structures,
             // the NodeConstraint is built using a Supplier for the actual NodeShape. Only if the NodeShape has not yet been
             // seen (i.e., it could be in the process of being built right now), create it now.
             final Resource resource = context.statement().getObject().asResource();
@@ -148,7 +148,7 @@ Constraint>> builder()
          .put( SHACL.closed(), context -> {
             boolean closed = context.statement().getBoolean();
             if ( !closed ) {
-               throw new RuntimeException();
+               throw new ShaclValidationException( "Value of sh:closed may only be true" );
             }
             Set<Property> ignoredProperties = Optional.ofNullable(
                         context.statement().getSubject().getProperty( SHACL.ignoredProperties() ) )
@@ -335,11 +335,11 @@ private Path path( final Resource pathNode ) {
       if ( zeroOrOneStatement != null ) {
          return new ZeroOrOnePath( path( zeroOrOneStatement.getResource() ) );
       }
-      throw new RuntimeException( "Invalid path: " + PrintUtil.print( pathNode ) );
+      throw new ShaclValidationException( "Invalid path: " + PrintUtil.print( pathNode ) );
    }
 
    private boolean isRdfList( final Resource resource ) {
-      return (resource.isURIResource() && resource.getURI().equals( RDF.nil.getURI() ))
+      return ( resource.isURIResource() && resource.getURI().equals( RDF.nil.getURI() ) )
             || resource.hasProperty( RDF.rest ) || resource.hasProperty( RDF.first );
    }
 
@@ -351,7 +351,7 @@ private List<Constraint> constraints( final Resource valueNode, final Optional<P
                   return Streams.stream( valueNode.listProperties( entry.getKey() ) )
                         .map( statement -> entry.getValue().apply( new ShapeContext( statement, path ) ) );
                } catch ( final Exception exception ) {
-                  throw new RuntimeException( "Could not load SHACL shape: Invalid use of " + entry.getKey() + " on " + valueNode );
+                  throw new ShaclValidationException( "Could not load SHACL shape: Invalid use of " + entry.getKey() + " on " + valueNode );
                }
             } )
             .collect( Collectors.toList() );