Document configuration transformation logics and their data containers

7 files changed, 266 insertions, 0 deletions

diff --git a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModClientToDozModServer.java b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModClientToDozModServer.java
index dda62aa..0d0c457 100644
--- a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModClientToDozModServer.java
+++ b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModClientToDozModServer.java
@@ -1,7 +1,18 @@
 package org.openslx.virtualization.configuration.data;
 
+/**
+ * Data container to collect and store input arguments for a
+ * {@link ConfigurationLogicDozModClientToDozModServer} transformation.
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationDataDozModClientToDozModServer
 {
+	/**
+	 * Creates a new data container to collect and store input arguments for a
+	 * {@link ConfigurationLogicDozModClientToDozModServer} transformation.
+	 */
 	public ConfigurationDataDozModClientToDozModServer()
 	{
 	}
diff --git a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToDozModClient.java b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToDozModClient.java
index c1ae37a..7b1c0b4 100644
--- a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToDozModClient.java
+++ b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToDozModClient.java
@@ -4,14 +4,52 @@ import java.io.File;
 
 import org.openslx.bwlp.thrift.iface.OperatingSystem;
 
+/**
+ * Data container to collect and store input arguments for a
+ * {@link ConfigurationLogicDozModServerToDozModClient} transformation.
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationDataDozModServerToDozModClient
 {
+	/**
+	 * Display name for a transformation of a virtualization configuration.
+	 */
 	private final String displayName;
+
+	/**
+	 * Disk image file for a transformation of a virtualization configuration.
+	 */
 	private final File diskImage;
+
+	/**
+	 * Guest operating system for a transformation of a virtualization configuration.
+	 */
 	private final OperatingSystem guestOs;
+
+	/**
+	 * Virtualizer identifier for a transformation of a virtualization configuration.
+	 */
 	private final String virtualizerId;
+
+	/**
+	 * Total amount of available memory for a transformation of a virtualization configuration.
+	 */
 	private final int totalMemory;
 
+	/**
+	 * Creates a new data container to collect and store input arguments for a
+	 * {@link ConfigurationLogicDozModServerToDozModClient} transformation.
+	 * 
+	 * @param displayName display name for a transformation of a virtualization configuration.
+	 * @param diskImage disk image file for a transformation of a virtualization configuration.
+	 * @param guestOs guest operating system for a transformation of a virtualization configuration.
+	 * @param virtualizerId virtualizer identifier for a transformation of a virtualization
+	 *           configuration.
+	 * @param totalMemory total amount of available memory for a transformation of a virtualization
+	 *           configuration.
+	 */
 	public ConfigurationDataDozModServerToDozModClient( String displayName, File diskImage, OperatingSystem guestOs,
 			String virtualizerId, int totalMemory )
 	{
@@ -22,26 +60,53 @@ public class ConfigurationDataDozModServerToDozModClient
 		this.totalMemory = totalMemory;
 	}
 
+	/**
+	 * Returns the display name for a transformation of a virtualization configuration.
+	 * 
+	 * @return display name for a transformation of a virtualization configuration.
+	 */
 	public String getDisplayName()
 	{
 		return this.displayName;
 	}
 
+	/**
+	 * Returns the disk image file for a transformation of a virtualization configuration.
+	 * 
+	 * @return disk image file for a transformation of a virtualization configuration.
+	 */
 	public File getDiskImage()
 	{
 		return this.diskImage;
 	}
 
+	/**
+	 * Returns the guest operating system for a transformation of a virtualization configuration.
+	 * 
+	 * @return guest operating system for a transformation of a virtualization configuration.
+	 */
 	public OperatingSystem getGuestOs()
 	{
 		return this.guestOs;
 	}
 
+	/**
+	 * Returns the virtualizer identifier for a transformation of a virtualization configuration.
+	 * 
+	 * @return virtualizer identifier for a transformation of a virtualization configuration.
+	 */
 	public String getVirtualizerId()
 	{
 		return this.virtualizerId;
 	}
 
+	/**
+	 * Returns the total amount of available memory for a transformation of a virtualization
+	 * configuration.
+	 * 
+	 * @return total amount of available memory for a transformation of a virtualization
+	 *         configuration.
+	 */
 	public int getTotalMemory()
 	{
 		return this.totalMemory;
diff --git a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToStatelessClient.java b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToStatelessClient.java
index f5d9a31..e92df92 100644
--- a/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToStatelessClient.java
+++ b/src/main/java/org/openslx/virtualization/configuration/data/ConfigurationDataDozModServerToStatelessClient.java
@@ -1,11 +1,40 @@
 package org.openslx.virtualization.configuration.data;
 
+/**
+ * Data container to collect and store input arguments for a
+ * {@link ConfigurationLogicDozModServerToStatelessClient} transformation.
+ * 
+ * @author Manuel Bentele
+ * @version 1.0
+ */
 public class ConfigurationDataDozModServerToStatelessClient
 {
+	/**
+	 * Display name for a transformation of a virtualization configuration.
+	 */
 	private final String displayName;
+
+	/**
+	 * Operating system identifier for a transformation of a virtualization configuration.
+	 */
 	private final String osId;
+
+	/**
+	 * State whether USB access is allowed or not for a transformation of a virtualization
+	 * configuration.
+	 */
 	private final boolean hasUsbAccess;
 
+	/**
+	 * Creates a new data container to collect and store input arguments for a
+	 * {@link ConfigurationLogicDozModServerToStatelessClient} transformation.
+	 * 
+	 * @param displayName display name for a transformation of a virtualization configuration.
+	 * @param osId operating system identifier for a transformation of a virtualization
+	 *           configuration.
+	 * @param hasUsbAccess state whether USB access is allowed or not for a transformation of a
+	 *           virtualization configuration.
+	 */
 	public ConfigurationDataDozModServerToStatelessClient( String displayName, String osId, boolean hasUsbAccess )
 	{
 		this.displayName = displayName;
@@ -13,16 +42,34 @@ public class ConfigurationDataDozModServerToStatelessClient
 		this.hasUsbAccess = hasUsbAccess;
 	}
 
+	/**
+	 * Returns the display name for a transformation of a virtualization configuration.
+	 * 
+	 * @return display name for a transformation of a virtualization configuration.
+	 */
 	public String getDisplayName()
 	{
 		return this.displayName;
 	}
 
+	/**
+	 * Returns the operating system identifier for a transformation of a virtualization
+	 * configuration.
+	 * 
+	 * @return operating system identifier for a transformation of a virtualization configuration.
+	 */
 	public String getOsId()
 	{
 		return this.osId;
 	}
 
+	/**
+	 * Returns the state whether USB access is allowed or not for a transformation of a
+	 * virtualization configuration.
+	 * 
+	 * @return state whether USB access is allowed or not for a transformation of a virtualization
+	 *         configuration.
+	 */
 	public boolean hasUsbAccess()
 	{
 		return this.hasUsbAccess;
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