From 46b8f8b5f69efebb0ae389cff6627d70f7633fc2 Mon Sep 17 00:00:00 2001
From: Manuel Bentele
Date: Wed, 28 Apr 2021 09:19:42 +0200
Subject: Document configuration transformation logics and their data
 containers

---
 .../configuration/logic/ConfigurationLogic.java    | 16 ++++++
 ...nfigurationLogicDozModClientToDozModServer.java | 32 ++++++++++++
 ...nfigurationLogicDozModServerToDozModClient.java | 60 ++++++++++++++++++++++
 ...gurationLogicDozModServerToStatelessClient.java | 35 +++++++++++++
 4 files changed, 143 insertions(+)

(limited to 'src/main/java/org/openslx/virtualization/configuration/logic')

diff --git a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogic.java b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogic.java
index 1aac943..018d046 100644
--- a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogic.java
+++ b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogic.java
@@ -3,8 +3,24 @@ package org.openslx.virtualization.configuration.logic;
 import org.openslx.virtualization.configuration.VirtualizationConfiguration;
 import org.openslx.virtualization.configuration.transformation.TransformationGeneric;
 
+/**
+ * Generic transformation logic for virtualization configurations.
+ * <p>
+ * This transformation logic represents an encapsulated transformation logic to transform
+ * virtualization configurations as part of server or client implementations.
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ * 
+ * @param <T> type of configuration data used as input arguments for a transformation.
+ */
 public abstract class ConfigurationLogic<T> extends TransformationGeneric<VirtualizationConfiguration<?, ?, ?, ?>, T>
 {
+	/**
+	 * Creates a new generic transformation logic for virtualization configurations.
+	 * 
+	 * @param name generic transformation logic name.
+	 */
 	public ConfigurationLogic( String name )
 	{
 		super( name );
diff --git a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModClientToDozModServer.java b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModClientToDozModServer.java
index ca25aa3..d64f42a 100644
--- a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModClientToDozModServer.java
+++ b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModClientToDozModServer.java
@@ -5,16 +5,48 @@ import org.openslx.virtualization.configuration.VirtualizationConfigurationExcep
 import org.openslx.virtualization.configuration.data.ConfigurationDataDozModClientToDozModServer;
 import org.openslx.virtualization.configuration.transformation.TransformationException;
 
+/**
+ * Transformation logic for virtualization configurations between a dozmod-client and a
+ * dozmod-server.
+ * <p>
+ * This transformation logic is applied while uploading a new virtualization configuration from a
+ * dozmod-client to a dozmod-server.
+ * 
+ * <pre>
+ *   +------------------------------+  DozModClientToDozModServer   +------------------------------+
+ *   | virtualization configuration | ----------------------------> | virtualization configuration |
+ *   +---------------+--------------+     transformation logic      +---------------+--------------+
+ *   | dozmod-client |                                              | dozmod-server |
+ *   +---------------+                                              +---------------+
+ * </pre>
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationLogicDozModClientToDozModServer
 		extends ConfigurationLogic<ConfigurationDataDozModClientToDozModServer>
 {
+	/**
+	 * Name of the transformation logic for virtualization configurations.
+	 */
 	private static final String CONFIGURATION_LOGIC_NAME = "Transformation of virtualization configuration during upload from DozMod client to DozMod server";
 
+	/**
+	 * Creates a new transformation logic for virtualization configurations between a dozmod-client
+	 * and a dozmod-server.
+	 */
 	public ConfigurationLogicDozModClientToDozModServer()
 	{
 		super( ConfigurationLogicDozModClientToDozModServer.CONFIGURATION_LOGIC_NAME );
 	}
 
+	/**
+	 * Validates a virtualization configuration and input arguments for a transformation.
+	 * 
+	 * @param config virtualization configuration for the validation.
+	 * @param args input arguments for the validation.
+	 * @throws TransformationException validation has failed.
+	 */
 	private void validateInputs( VirtualizationConfiguration<?, ?, ?, ?> config,
 			ConfigurationDataDozModClientToDozModServer args )
 			throws TransformationException
diff --git a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToDozModClient.java b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToDozModClient.java
index 6d8687f..05b3d4a 100644
--- a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToDozModClient.java
+++ b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToDozModClient.java
@@ -9,19 +9,60 @@ import org.openslx.virtualization.configuration.VirtualizationConfigurationExcep
 import org.openslx.virtualization.configuration.data.ConfigurationDataDozModServerToDozModClient;
 import org.openslx.virtualization.configuration.transformation.TransformationException;
 
+/**
+ * Transformation logic for virtualization configurations between a dozmod-server and a
+ * dozmod-client.
+ * <p>
+ * This transformation logic is applied while downloading an existing virtualization configuration
+ * from a dozmod-server to a dozmod-client.
+ * 
+ * <pre>
+ *   +------------------------------+  DozModServerToDozModClient   +------------------------------+
+ *   | virtualization configuration | ----------------------------> | virtualization configuration |
+ *   +---------------+--------------+     transformation logic      +---------------+--------------+
+ *   | dozmod-server |                                              | dozmod-client |
+ *   +---------------+                                              +---------------+
+ * </pre>
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationLogicDozModServerToDozModClient
 		extends ConfigurationLogic<ConfigurationDataDozModServerToDozModClient>
 {
+	/**
+	 * Name of the transformation logic for virtualization configurations.
+	 */
 	private static final String CONFIGURATION_LOGIC_NAME = "Transformation of virtualization configuration during download from DozMod server to DozMod client";
 
+	/**
+	 * Default number of CPU cores set by the configuration logic for the virtualization
+	 * configuration's virtualizer.
+	 */
 	private static final int CONFIGURATION_LOGIC_NUM_CPU_CORES = 1;
+
+	/**
+	 * Default memory in megabytes set by the configuration logic for the virtualization
+	 * configuration's virtualizer.
+	 */
 	private static final int CONFIGURATION_LOGIC_MEMORY_MIN = 1024;
 
+	/**
+	 * Creates a new transformation logic for virtualization configurations between a dozmod-server
+	 * and a dozmod-client.
+	 */
 	public ConfigurationLogicDozModServerToDozModClient()
 	{
 		super( ConfigurationLogicDozModServerToDozModClient.CONFIGURATION_LOGIC_NAME );
 	}
 
+	/**
+	 * Validates a virtualization configuration and input arguments for a transformation.
+	 * 
+	 * @param config virtualization configuration for the validation.
+	 * @param args input arguments for the validation.
+	 * @throws TransformationException validation has failed.
+	 */
 	private void validateInputs( VirtualizationConfiguration<?, ?, ?, ?> config,
 			ConfigurationDataDozModServerToDozModClient args )
 			throws TransformationException
@@ -37,11 +78,30 @@ public class ConfigurationLogicDozModServerToDozModClient
 		}
 	}
 
+	/**
+	 * Rounds a given value to the nearest factor.
+	 * 
+	 * @param value input value for the rounding.
+	 * @param nearestFactor nearest factor for the rounding.
+	 * @return rounded value as a multiple of the nearest factor.
+	 * 
+	 * @apiNote This utility method rounds the given value to an integer value and no to a floating
+	 *          point value.
+	 */
 	private static int roundToNearest( int value, int nearestFactor )
 	{
 		return ( value / nearestFactor ) * nearestFactor;
 	}
 
+	/**
+	 * Calculates the amount of memory for the virtualization configuration depending on the
+	 * available resources of the dozmod-client's host system.
+	 * 
+	 * @param totalMemory maximum memory available on the dozmod-client's host system.
+	 * @param osMaxMemory maximum memory supported by the defined operating system in the
+	 *           virtualization configuration.
+	 * @return amount of memory for the virtualization configuration in megabytes
+	 */
 	private static int calculateVirtualizationMemoryOnDozmodClient( int totalMemory, int osMaxMemory )
 	{
 		// calculate the amount of memory
diff --git a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToStatelessClient.java b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToStatelessClient.java
index 8697df1..6c573bb 100644
--- a/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToStatelessClient.java
+++ b/src/main/java/org/openslx/virtualization/configuration/logic/ConfigurationLogicDozModServerToStatelessClient.java
@@ -7,18 +7,53 @@ import org.openslx.virtualization.configuration.VirtualizationConfigurationExcep
 import org.openslx.virtualization.configuration.data.ConfigurationDataDozModServerToStatelessClient;
 import org.openslx.virtualization.configuration.transformation.TransformationException;
 
+/**
+ * Transformation logic for virtualization configurations between a dozmod-server and a stateless
+ * client.
+ * <p>
+ * This transformation logic is applied while downloading an existing virtualization configuration
+ * from a dozmod-server to a stateless client.
+ * 
+ * <pre>
+ *   +------------------------------+  DozModServerToStatelessClient   +------------------------------+
+ *   | virtualization configuration | -------------------------------> | virtualization configuration |
+ *   +---------------+--------------+      transformation logic        +------------------+-----------+
+ *   | dozmod-server |                                                 | stateless client |
+ *   +---------------+                                                 +------------------+
+ * </pre>
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationLogicDozModServerToStatelessClient
 		extends ConfigurationLogic<ConfigurationDataDozModServerToStatelessClient>
 {
+	/**
+	 * Name of the transformation logic for virtualization configurations.
+	 */
 	private static final String CONFIGURATION_LOGIC_NAME = "Transformation of virtualization configuration during download from DozMod server to stateless client";
 
+	/**
+	 * Default type for an ethernet interface in a virtualization configuration.
+	 */
 	private static final EtherType CONFIGURATION_DEFAULT_ETHERNET_TYPE = EtherType.NAT;
 
+	/**
+	 * Creates a new transformation logic for virtualization configurations between a dozmod-server
+	 * and a stateless client.
+	 */
 	public ConfigurationLogicDozModServerToStatelessClient()
 	{
 		super( ConfigurationLogicDozModServerToStatelessClient.CONFIGURATION_LOGIC_NAME );
 	}
 
+	/**
+	 * Validates a virtualization configuration and input arguments for a transformation.
+	 * 
+	 * @param config virtualization configuration for the validation.
+	 * @param args input arguments for the validation.
+	 * @throws TransformationException validation has failed.
+	 */
 	private void validateInputs( VirtualizationConfiguration<?, ?, ?, ?> config,
 			ConfigurationDataDozModServerToStatelessClient args )
 			throws TransformationException
-- 
cgit v1.2.3-55-g7522