feat: implement value only serialization and deserialization

dataformat-core/src/main/java/org/eclipse/digitaltwin/aas4j/v3/dataformat/Deserializer.java

@@ -0,0 +1,129 @@
+/*
+ * Copyright (c) 2021 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e. V.
+ * Copyright (C) 2023 SAP SE or an SAP affiliate company.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.eclipse.digitaltwin.aas4j.v3.dataformat;
+
+import java.io.BufferedReader;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.stream.Collectors;
+
+import org.eclipse.digitaltwin.aas4j.v3.model.Environment;
+
+/**
+ * Generic deserializer interface to deserialize a given string, Outputstream or
+ * java.io.File into an instance of AssetAdministrationShellEnvironment
+ */
+public interface Deserializer {
+
+    /**
+     * Default charset that will be used when no charset is specified
+     */
+    Charset DEFAULT_CHARSET = StandardCharsets.UTF_8;
+
+    /**
+     * Deserializes a given string into an instance of
+     * AssetAdministrationShellEnvironment
+     *
+     * @param value a string representation of the
+     * AssetAdministrationShellEnvironment
+     * @return an instance of AssetAdministrationShellEnvironment
+     * @throws DeserializationException if deserialization fails
+     */
+    Environment read(String value) throws DeserializationException;
+
+    /**
+     * Deserializes a given InputStream into an instance of
+     * AssetAdministrationShellEnvironment using DEFAULT_CHARSET
+     *
+     * @param src an InputStream containing the string representation of the
+     * AssetAdministrationShellEnvironment
+     * @return an instance of AssetAdministrationShellEnvironment
+     * @throws DeserializationException if deserialization fails
+     */
+    default Environment read(InputStream src) throws DeserializationException {
+        return read(src, DEFAULT_CHARSET);
+    }
+
+    /**
+     * Deserializes a given InputStream into an instance of
+     * AssetAdministrationShellEnvironment using a given charset
+     *
+     * @param src An InputStream containing the string representation of the
+     * AssetAdministrationShellEnvironment
+     * @param charset the charset to use for deserialization
+     * @return an instance of AssetAdministrationShellEnvironment
+     * @throws DeserializationException if deserialization fails
+     */
+    default Environment read(InputStream src, Charset charset) throws DeserializationException {
+        return read(new BufferedReader(
+                new InputStreamReader(src, charset))
+                .lines()
+                .collect(Collectors.joining(System.lineSeparator())));
+    }
+
+    /**
+     * Deserializes a given File into an instance of
+     * AssetAdministrationShellEnvironment using DEFAULT_CHARSET
+     *
+     * @param file A java.io.File containing the string representation of the
+     * AssetAdministrationShellEnvironment
+     * @param charset the charset to use for deserialization
+     * @return an instance of AssetAdministrationShellEnvironment
+     * @throws FileNotFoundException if file is not present
+     * @throws DeserializationException if deserialization fails
+     */
+    default Environment read(java.io.File file, Charset charset)
+            throws FileNotFoundException, DeserializationException {
+        return read(new FileInputStream(file), charset);
+    }
+
+    /**
+     * Deserializes a given File into an instance of
+     * AssetAdministrationShellEnvironment using a given charset
+     *
+     * @param file a java.io.File containing the string representation of the
+     * AssetAdministrationShellEnvironment
+     * @return an instance of AssetAdministrationShellEnvironment
+     * @throws FileNotFoundException if the file is not present
+     * @throws DeserializationException if deserialization fails
+     */
+    default Environment read(java.io.File file) throws FileNotFoundException, DeserializationException {
+        return read(file, DEFAULT_CHARSET);
+    }
+
+    /**
+     * Enables usage of custom implementation to be used for deserialization
+     * instead of default implementation, e.g. defining a custom implementation
+     * of the Submodel interface {@code class
+     * CustomSubmodel implements Submodel {}} and calling
+     * {@code useImplementation(Submodel.class, CustomSubmodel.class);} will
+     * result in all instances of Submodel will be deserialized as
+     * CustomSubmodel. Subsequent class with the same aasInterface parameter
+     * will override the effects of all previous calls.
+     *
+     * @param <T> the type of the interface to replace
+     * @param aasInterface the class of the interface to replace
+     * @param implementation the class implementing the interface that should be
+     * used for deserialization.
+     */
+    <T> void useImplementation(Class<T> aasInterface, Class<? extends T> implementation);
+
+}

dataformat-core/src/main/java/org/eclipse/digitaltwin/aas4j/v3/dataformat/Serializer.java

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2021 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e. V.
+ * Copyright (C) 2023 SAP SE or an SAP affiliate company.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.eclipse.digitaltwin.aas4j.v3.dataformat;
+
+import java.io.FileNotFoundException;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+
+import org.eclipse.digitaltwin.aas4j.v3.model.Environment;
+
+/**
+ * Generic serializer interface to serialize an instance of
+ * AssetAdministrationShellEnvironment to a string, Outputstream or java.io.File
+ */
+public interface Serializer {
+
+    /**
+     * Default charset that will be used when no charset is specified
+     */
+    Charset DEFAULT_CHARSET = StandardCharsets.UTF_8;
+
+    /**
+     * Serializes a given instance of AssetAdministrationShellEnvironment to
+     * string
+     *
+     * @param aasEnvironment the AssetAdministrationShellEnvironment to
+     * serialize
+     * @return the string representation of the environment
+     * @throws SerializationException if serialization fails
+     */
+    String write(Environment aasEnvironment) throws SerializationException;
+
+    /**
+     * Serializes a given instance of Environment to an
+     * OutputStream using DEFAULT_CHARSET
+     *
+     * @param out the Outputstream to serialize to
+     * @param aasEnvironment the Environment to
+     * serialize
+     * @throws IOException if writing to the stream fails
+     * @throws SerializationException if serialization fails
+     */
+    default void write(OutputStream out, Environment aasEnvironment) throws IOException, SerializationException {
+        write(out, DEFAULT_CHARSET, aasEnvironment);
+    }
+
+    /**
+     * Serializes a given instance of Environment to an
+     * OutputStream using given charset
+     *
+     * @param out the Outputstream to serialize to
+     * @param charset the Charset to use for serialization
+     * @param aasEnvironment the Environment to
+     * serialize
+     * @throws IOException if writing to the stream fails
+     * @throws SerializationException if serialization fails
+     */
+    default void write(OutputStream out, Charset charset, Environment aasEnvironment)
+            throws IOException, SerializationException {
+        try (OutputStreamWriter writer = new OutputStreamWriter(out, charset)) {
+            writer.write(write(aasEnvironment));
+        }
+    }
+
+    // Note that the AAS also defines a file class
+    /**
+     * Serializes a given instance of Environment to a
+     * java.io.File using DEFAULT_CHARSET
+     *
+     * @param file the java.io.File to serialize to
+     * @param charset the Charset to use for serialization
+     * @param aasEnvironment the Environment to
+     * serialize
+     * @throws FileNotFoundException if the fail does not exist
+     * @throws IOException if writing to the file fails
+     * @throws SerializationException if serialization fails
+     */
+    default void write(java.io.File file, Charset charset, Environment aasEnvironment)
+            throws FileNotFoundException, IOException, SerializationException {
+        try (OutputStream out = new FileOutputStream(file)) {
+            write(out, charset, aasEnvironment);
+        }
+    }
+
+    /**
+     * Serializes a given instance of Environment to a
+     * java.io.File using given charset
+     *
+     * @param file the java.io.File to serialize to
+     * @param aasEnvironment the Environment to
+     * serialize
+     * @throws FileNotFoundException if the fail does not exist
+     * @throws IOException if writing to the file fails
+     * @throws SerializationException if serialization fails
+     */
+    default void write(java.io.File file, Environment aasEnvironment)
+            throws FileNotFoundException, IOException, SerializationException {
+        write(file, DEFAULT_CHARSET, aasEnvironment);
+    }
+
+}

dataformat-core/src/main/java/org/eclipse/digitaltwin/aas4j/v3/dataformat/core/DataSpecificationInfo.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2021 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e. V.
+ * Copyright (c) 2023 SAP SE
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.eclipse.digitaltwin.aas4j.v3.dataformat.core;
+
+import org.eclipse.digitaltwin.aas4j.v3.model.DataSpecificationContent;
+import org.eclipse.digitaltwin.aas4j.v3.model.Reference;
+
+/**
+ * Class representing all information required for a (custom) data specification
+ */
+public class DataSpecificationInfo {
+
+    private final Class<? extends DataSpecificationContent> type;
+    private final Reference reference;
+    private final String prefix;
+
+    public DataSpecificationInfo(Class<? extends DataSpecificationContent> type, Reference reference, String prefix) {
+        this.type = type;
+        this.reference = reference;
+        this.prefix = prefix;
+    }
+
+    public Class<? extends DataSpecificationContent> getType() {
+        return type;
+    }
+
+    public Reference getReference() {
+        return reference;
+    }
+
+    public String getPrefix() {
+        return prefix;
+    }
+}