Merge pull request #147 from bci-oss/feature/aasxgeneration

Feature/aasxgeneration

Author: atextor

core/sds-aspect-model-aas-generator/README.md

@@ -0,0 +1,50 @@
+# AAS Generator Module of the BAMM SDK
+
+The Asset Administration Shell (AAS) and its information model [1] is a widely recognized standard developed by the 
+Industrial Digital Twin Association (IDTA) [2] to express and handle Digital Twins. Central element of the AAS is 
+the concept of Submodels, which describe certain aspects of a Digital Twin.
+
+The BAMM Aspect Meta Model allows to specify aspects of a digital twin and its semantics. 
+The AAS Generator module provides mapping implementations to derive AAS Submodels from BAMM Aspect models
+and by that allows to on the one hand integrate BAMM models in AAS environments and on the other hand allow 
+AAS Submodels to be described with rich semantics, as it is possible with BAMM.
+
+The implementation relies on the AAS Meta Model implementation [3] and the AAS file serializers provided by [4].
+
+## Example uses
+One example use of the generator is with the BAMM CLI, which provides the AAS generator functionality by
+```
+java -jar bamm-cli.jar aspect org.idtwin/1.0.0/Nameplate.ttl to aas -f xml -o nameplate.xml
+```
+or
+```
+java -jar bamm-cli.jar aspect org.idtwin/1.0.0/Nameplate.ttl to aas -f aasx -o nameplate.aasx
+```
+The first call generates a plain xml representation of the AAS whereas the second one generates an AASX archive
+with the AAS xml file in it.
+ 
+Should the generator be integrated into custom implementations, the class `AspectModelAASGenerator`
+with its method `io.openmanufacturing.sds.aspectmodel.aas.AspectModelAASGenerator.generateOutput` is the 
+proper entry point. It expects an `io.openmanufacturing.sds.metamodel.Aspect` and returns a 
+`ByteArrayOutputStream`.
+
+
+## Details of the Mapping Concept
+The mapping rules applied by the generator are explained in the [user documentation](https://openmanufacturingplatform.github.io/sds-documentation/sds-developer-guide/tooling-guide/java-aspect-tooling.html#details-mapping-aas).
+The rules apply to BAMM v1.0.0 [6] and  AAS Specification Part 1 V3.0RC01 [7].
+
+
+## References
+[1] https://www.plattform-i40.de/IP/Redaktion/EN/Standardartikel/specification-administrationshell.html
+
+[2] https://industrialdigitaltwin.org
+
+[3] https://github.com/admin-shell-io/java-model
+
+[4] https://github.com/admin-shell-io/java-serializer
+
+[5] https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/v1.0.0/characteristics.html
+
+[6] https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/v1.0.0/index.html
+
+[7] https://www.plattform-i40.de/IP/Redaktion/EN/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part1_V3.html

core/sds-aspect-model-aas-generator/pom.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>sds-sdk-parent</artifactId>
+        <groupId>io.openmanufacturing</groupId>
+        <version>DEV-SNAPSHOT</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>sds-aspect-model-aas-generator</artifactId>
+
+    <properties>
+        <maven.compiler.source>11</maven.compiler.source>
+        <maven.compiler.target>11</maven.compiler.target>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.openmanufacturing</groupId>
+            <artifactId>sds-aspect-model-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.openmanufacturing</groupId>
+            <artifactId>sds-aspect-meta-model-java</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.admin-shell.aas</groupId>
+            <artifactId>model</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.admin-shell.aas</groupId>
+            <artifactId>dataformat-xml</artifactId>
+        </dependency>
+       <dependency>
+          <groupId>io.admin-shell.aas</groupId>
+          <artifactId>dataformat-aasx</artifactId>
+       </dependency>
+        <dependency>
+            <groupId>io.openmanufacturing</groupId>
+            <artifactId>sds-test-resources</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+        </dependency>
+    </dependencies>
+</project>

core/sds-aspect-model-aas-generator/src/main/java/io/openmanufacturing/sds/aspectmodel/aas/AspectModelAASGenerator.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2021, 2022 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.aspectmodel.aas;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.function.Function;
+
+import io.adminshell.aas.v3.dataformat.SerializationException;
+import io.adminshell.aas.v3.dataformat.aasx.AASXSerializer;
+import io.adminshell.aas.v3.dataformat.xml.XmlSerializer;
+import io.adminshell.aas.v3.model.AssetAdministrationShellEnvironment;
+import io.openmanufacturing.sds.metamodel.Aspect;
+
+/** Generator that generates an AASX file containing an AAS submodel for a given Aspect model */
+public class AspectModelAASGenerator {
+
+   /**
+    * Generates an AASX archive file for a given Aspect and writes it to a given OutputStream provided by <code>nameMapper<code/>
+    *
+    * @param aspect the Aspect for which an AASX archive shall be generated
+    * @param nameMapper a Name Mapper implementation, which provides an OutputStream for a given filename
+    * @throws IOException in case the generation can not properly be executed
+    */
+   public void generateAASXFile( final Aspect aspect, final Function<String, OutputStream> nameMapper )
+         throws IOException {
+      try ( final OutputStream output = nameMapper.apply( aspect.getName() ) ) {
+         output.write( generateAasxOutput( aspect ).toByteArray() );
+      }
+   }
+
+   /**
+    * Generates an AAS XML archive file for a given Aspect and writes it to a given OutputStream provided by <code>nameMapper<code/>
+    *
+    * @param aspect the Aspect for which an AASX archive shall be generated
+    * @param nameMapper a Name Mapper implementation, which provides an OutputStream for a given filename
+    * @throws IOException in case the generation can not properly be executed
+    */
+   public void generateAasXmlFile(
+         final Aspect aspect, final Function<String, OutputStream> nameMapper ) throws IOException {
+      try ( final OutputStream output = nameMapper.apply( aspect.getName() ) ) {
+         output.write( generateXmlOutput( aspect ).toByteArray() );
+      }
+   }
+
+   protected ByteArrayOutputStream generateAasxOutput( Aspect aspect ) throws IOException {
+      final AspectModelAASVisitor visitor = new AspectModelAASVisitor();
+      AssetAdministrationShellEnvironment environment = visitor.visitAspect( aspect, null );
+
+      try ( ByteArrayOutputStream out = new ByteArrayOutputStream() ) {
+         AASXSerializer serializer = new AASXSerializer();
+         serializer.write( environment, null, out );
+         return out;
+      } catch ( SerializationException e ) {
+         throw new IOException( e );
+      }
+   }
+
+   protected ByteArrayOutputStream generateXmlOutput( Aspect aspect ) throws IOException {
+      final AspectModelAASVisitor visitor = new AspectModelAASVisitor();
+      AssetAdministrationShellEnvironment environment = visitor.visitAspect( aspect, null );
+
+      try ( ByteArrayOutputStream out = new ByteArrayOutputStream() ) {
+         XmlSerializer serializer = new XmlSerializer();
+         serializer.write( out, environment );
+         return out;
+      } catch ( SerializationException e ) {
+         throw new IOException( e );
+      }
+   }
+}