Pull request #7: Fix/aasx comments

Merge in EAR/aas-serializer from fix/aasx-comments to master

* commit 'd694395454c0cf10dfeeec646b462df2b088d9da':
  Adds missing comments for aasx dataformat
  Remove unnecessary utility class in AASX serializer

Author: Daespen

dataformat-aasx/src/main/java/io/adminshell/aas/v3/dataformat/aasx/AASXDeserializer.java

@@ -23,15 +23,12 @@
 import java.util.Collection;
 import java.util.List;
 
-import javax.xml.parsers.ParserConfigurationException;
-
 import org.apache.commons.io.IOUtils;
 import org.apache.poi.openxml4j.exceptions.InvalidFormatException;
 import org.apache.poi.openxml4j.opc.OPCPackage;
 import org.apache.poi.openxml4j.opc.PackagePart;
 import org.apache.poi.openxml4j.opc.PackageRelationshipCollection;
 import org.apache.poi.openxml4j.opc.PackagingURIHelper;
-import org.xml.sax.SAXException;
 
 import io.adminshell.aas.v3.dataformat.DeserializationException;
 import io.adminshell.aas.v3.dataformat.xml.XmlDeserializer;
@@ -44,11 +41,6 @@
 /**
  * The AASX package converter converts a aasx package into a list of aas, a list
  * of submodels a list of assets, a list of Concept descriptions
- * 
- * The aas provides the references to the submodels and assets
- * 
- * @author zhangzai, conradi
- *
  */
 public class AASXDeserializer {
 
@@ -60,15 +52,39 @@ public class AASXDeserializer {
     private AssetAdministrationShellEnvironment environment;
     private final OPCPackage aasxRoot;
 
+    /**
+     * Constructor that takes the aasx package for this deserializer
+     * 
+     * @param inputStream an input stream to an aasx package that can be read with this instance
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws IOException if creating input streams for aasx fails
+     */
     public AASXDeserializer(InputStream inputStream) throws InvalidFormatException, IOException {
         aasxRoot = OPCPackage.open(inputStream);
     }
 
+    /**
+     * Constructor for custom XML deserialization
+     * 
+     * @param deserializer a custom deserializer used for deserializing the aas environment
+     * @param inputStream an input stream to an aasx package that can be read with this instance
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws IOException if creating input streams for aasx fails
+     */
     public AASXDeserializer(XmlDeserializer deserializer, InputStream inputStream) throws InvalidFormatException, IOException {
         aasxRoot = OPCPackage.open(inputStream);
         this.deserializer = deserializer;
     }
 
+    /**
+     * Reads the AASX package that belongs to this deserializer
+     * 
+     * @return The deserialized aas environment from the aasx package given in the constructor
+     * 
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws IOException if creating input streams for aasx fails
+     * @throws DeserializationException if deserialization of the serialized aas environment fails
+     */
     public AssetAdministrationShellEnvironment read() throws InvalidFormatException, IOException, DeserializationException {
         // If the XML was already parsed return cached environment
         if (environment != null) {
@@ -81,9 +97,8 @@ public AssetAdministrationShellEnvironment read() throws InvalidFormatException,
     /**
      * Return the Content of the xml file in the aasx-package as String
      * 
-     * @return Content of XML as String
-     * @throws InvalidFormatException
-     * @throws IOException
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws IOException if creating input streams for aasx fails
      */
     public String getXMLResourceString() throws InvalidFormatException, IOException {
         return getXMLResourceString(this.aasxRoot);
@@ -119,11 +134,9 @@ private String getXMLResourceString(OPCPackage aasxPackage) throws InvalidFormat
      * the package
      * 
      * @return a map of the folder name and folder path, the folder holds the files
-     * @throws IOException
-     * @throws SAXException
-     * @throws ParserConfigurationException
-     * @throws InvalidFormatException
-     * @throws DeserializationException
+     * @throws IOException if creating input streams for aasx fails
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws DeserializationException if deserialization of the serialized aas environment fails
      * 
      */
     private List<String> parseReferencedFilePathsFromAASX() throws IOException, InvalidFormatException, DeserializationException {
@@ -137,9 +150,9 @@ private List<String> parseReferencedFilePathsFromAASX() throws IOException, Inva
     }
 
     /**
-     * Gets the paths from a collection of ISubmodelElement
+     * Gets the file paths from a collection of ISubmodelElement
      * 
-     * @param elements
+     * @param elements the submodel elements to process
      * @return the Paths from the File elements
      */
     private List<String> parseElements(Collection<SubmodelElement> elements) {
@@ -161,6 +174,14 @@ private List<String> parseElements(Collection<SubmodelElement> elements) {
         return paths;
     }
 
+    /**
+     * Retrieves a list of related files from the deserialized aasx package
+     * 
+     * @return the list of file in memory
+     * @throws InvalidFormatException if aasx package format is invalid
+     * @throws IOException if creating input streams for aasx fails
+     * @throws DeserializationException if deserialization of the serialized aas environment fails
+     */
     public List<InMemoryFile> getRelatedFiles() throws InvalidFormatException, IOException, DeserializationException {
         List<String> filePaths = parseReferencedFilePathsFromAASX();
         List<InMemoryFile> files = new ArrayList<>();

dataformat-aasx/src/main/java/io/adminshell/aas/v3/dataformat/aasx/AASXSerializer.java

@@ -63,27 +63,39 @@ public class AASXSerializer {
 
     private Serializer xmlSerializer = new XmlSerializer();
 
-    public AASXSerializer(Serializer xmlSerializer) {
-        this.xmlSerializer = xmlSerializer;
-    }
-
+    /**
+     * Default constructor
+     */
     public AASXSerializer() {
+    }
 
+    /**
+     * Constructor with a custom serializer for serializing the aas environment
+     * 
+     * @param xmlSerializer a custom serializer used for serializing the aas environment
+     */
+    public AASXSerializer(Serializer xmlSerializer) {
+        this.xmlSerializer = xmlSerializer;
     }
 
     /**
      * Generates the .aasx file and writes it to the given OutputStream
      * 
-     * @throws SerializationException
-     * @throws IOException
+     * @param environment the aas environment that will be included in the aasx package as an xml serialization
+     * @param files related inMemory files that belong to the given aas environment
+     * @param os an output stream for writing the aasx package
+     * @throws SerializationException if serializing the given elements fails
+     * @throws IOException if creating output streams for aasx fails
      */
-    public void write(AssetAdministrationShellEnvironment environment, Collection<InMemoryFile> files, OutputStream os) throws SerializationException, IOException {
+    public void write(AssetAdministrationShellEnvironment environment, Collection<InMemoryFile> files, OutputStream os)
+            throws SerializationException, IOException {
         prepareFilePaths(environment.getSubmodels());
 
         OPCPackage rootPackage = OPCPackage.create(os);
 
         // Create the empty aasx-origin file
-        PackagePart origin = createAASXPart(rootPackage, rootPackage, ORIGIN_PATH, MIME_PLAINTXT, ORIGIN_RELTYPE, ORIGIN_CONTENT.getBytes());
+        PackagePart origin = createAASXPart(rootPackage, rootPackage, ORIGIN_PATH, MIME_PLAINTXT, ORIGIN_RELTYPE,
+                ORIGIN_CONTENT.getBytes());
 
         // Convert the given Metamodels to XML
         String xml = xmlSerializer.write(environment);
@@ -99,16 +111,13 @@ public void write(AssetAdministrationShellEnvironment environment, Collection<In
     /**
      * Stores the files from the Submodels in the .aasx file
      * 
-     * @param submodelList
-     *            the Submodels
-     * @param files
-     *            the content of the files
-     * @param rootPackage
-     *            the OPCPackage
-     * @param xmlPart
-     *            the Part the files should be related to
+     * @param submodelList the Submodels
+     * @param files the content of the files
+     * @param rootPackage the OPCPackage
+     * @param xmlPart the Part the files should be related to
      */
-    private void storeFilesInAASX(List<Submodel> submodelList, Collection<InMemoryFile> files, OPCPackage rootPackage, PackagePart xmlPart) {
+    private void storeFilesInAASX(List<Submodel> submodelList, Collection<InMemoryFile> files, OPCPackage rootPackage,
+            PackagePart xmlPart) {
 
         for (Submodel sm : submodelList) {
             for (File file : findFileElements(sm.getSubmodelElements())) {
@@ -128,11 +137,9 @@ private void storeFilesInAASX(List<Submodel> submodelList, Collection<InMemoryFi
     /**
      * Saves the OPCPackage to the given OutputStream
      * 
-     * @param os
-     *            the Stream to be saved to
-     * @param rootPackage
-     *            the Package to be saved
-     * @throws IOException
+     * @param os the Stream to be saved to
+     * @param rootPackage the Package to be saved
+     * @throws IOException if creating output streams for aasx fails
      */
     private void saveAASX(OutputStream os, OPCPackage rootPackage) throws IOException {
         rootPackage.flush();
@@ -152,23 +159,16 @@ private String createUniqueID() {
     /**
      * Creates a Part (a file in the .aasx) of the .aasx and adds it to the Package
      * 
-     * @param root
-     *            the OPCPackage
-     * @param relateTo
-     *            the Part of the OPC the relationship of the new Part should be
-     *            added to
-     * @param path
-     *            the path inside the .aasx where the new Part should be created
-     * @param mimeType
-     *            the mime-type of the file
-     * @param relType
-     *            the type of the Relationship
-     * @param content
-     *            the data the new part should contain
-     * @return the created PackagePart; Returned in case it is needed late as a Part
-     *         to relate to
+     * @param root the OPCPackage
+     * @param relateTo the Part of the OPC the relationship of the new Part should be added to
+     * @param path the path inside the .aasx where the new Part should be created
+     * @param mimeType the mime-type of the file
+     * @param relType the type of the Relationship
+     * @param content the data the new part should contain
+     * @return the created PackagePart; Returned in case it is needed late as a Part to relate to
      */
-    private PackagePart createAASXPart(OPCPackage root, RelationshipSource relateTo, String path, String mimeType, String relType, byte[] content) {
+    private PackagePart createAASXPart(OPCPackage root, RelationshipSource relateTo, String path, String mimeType, String relType,
+            byte[] content) {
         if (mimeType == null || mimeType.equals("")) {
             throw new RuntimeException("Could not create AASX Part '" + path + "'. No MIME_TYPE specified.");
         }
@@ -191,10 +191,8 @@ private PackagePart createAASXPart(OPCPackage root, RelationshipSource relateTo,
     /**
      * Writes the content of a byte[] to a Part
      * 
-     * @param part
-     *            the Part to be written to
-     * @param content
-     *            the content to be written to the part
+     * @param part the Part to be written to
+     * @param content the content to be written to the part
      */
     private void writeDataToPart(PackagePart part, byte[] content) {
         try (OutputStream ostream = part.getOutputStream();) {
@@ -209,8 +207,7 @@ private void writeDataToPart(PackagePart part, byte[] content) {
      * Gets the File elements from a collection of elements Also recursively
      * searches in SubmodelElementCollections
      * 
-     * @param elements
-     *            the Elements to be searched for File elements
+     * @param elements the Elements to be searched for File elements
      * @return the found Files
      */
     private Collection<File> findFileElements(Collection<SubmodelElement> elements) {
@@ -231,20 +228,18 @@ private Collection<File> findFileElements(Collection<SubmodelElement> elements)
     /**
      * Replaces the path in all File Elements with the result of preparePath
      * 
-     * @param submodels
-     *            the Submodels
+     * @param submodels the Submodels
      */
     private void prepareFilePaths(Collection<Submodel> submodels) {
-        submodels.stream().forEach(sm -> findFileElements(sm.getSubmodelElements()).stream().forEach(f -> f.setValue(preparePath(f.getValue()))));
+        submodels.stream()
+                .forEach(sm -> findFileElements(sm.getSubmodelElements()).stream().forEach(f -> f.setValue(preparePath(f.getValue()))));
     }
 
     /**
      * Finds an InMemoryFile by its path
      * 
-     * @param files
-     *            the InMemoryFiles
-     * @param path
-     *            the path of the wanted file
+     * @param files the InMemoryFiles
+     * @param path the path of the wanted file
      * @return the InMemoryFile if it was found; else null
      */
     private InMemoryFile findFileByPath(Collection<InMemoryFile> files, String path) {
@@ -259,8 +254,7 @@ private InMemoryFile findFileByPath(Collection<InMemoryFile> files, String path)
     /**
      * Removes the serverpart from a path and ensures it starts with a slash
      * 
-     * @param path
-     *            the path to be prepared
+     * @param path the path to be prepared
      * @return the prepared path
      */
     private String preparePath(String path) {

dataformat-aasx/src/main/java/io/adminshell/aas/v3/dataformat/aasx/InMemoryFile.java

@@ -19,13 +19,18 @@
 
 /**
  * Container class for the content of a File and its Path
- *
  */
 public class InMemoryFile {
 
     private byte[] fileContent;
     private String path;
 
+    /**
+     * Constructor for directly setting the InMemoryFile contents
+     * 
+     * @param fileContent byte-array content of the represented file
+     * @param path relative or absolute path of the represented file
+     */
     public InMemoryFile(byte[] fileContent, String path) {
         this.fileContent = fileContent;
         this.path = path;