doc comments

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dao/DeviceOrganizationDAO.java

@@ -29,85 +29,100 @@ import java.util.List;
 public interface DeviceOrganizationDAO {
 
     /**
-     * retrieve child devices per particular device ID
+     * Retrieves child devices per particular device ID
      *
-     * @param node
-     * @param maxDepth
-     * @param includeDevice
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * @param node The device node for which child devices are retrieved.
+     * @param maxDepth The maximum depth to traverse when fetching child devices.
+     * @param includeDevice Flag to indicate whether to include the parent device in the result.
+     * @return A list of child device nodes.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while retrieving child devices.
      */
     List<DeviceNode> getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * @param node
-     * @param maxDepth
-     * @param includeDevice
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * Retrieves parent devices for a given device node.
+     *
+     * @param node The device node for which parent devices are retrieved.
+     * @param maxDepth The maximum depth to traverse when fetching parent devices.
+     * @param includeDevice Flag to indicate whether to include the current device node in the result.
+     * @return A list of parent device nodes.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while retrieving parent devices.
      */
     List<DeviceNode> getParentsOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * get All Device Organization records
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * Retrieves all device organization records.
+     *
+     * @return A list of device organization records.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while retrieving device organization records.
      */
     List<DeviceOrganization> getAllDeviceOrganizations() throws DeviceOrganizationMgtDAOException;
 
     /**
-     * add a new reocrd to device organization table
+     * Adds a new record to the device organization table.
      *
-     * @param deviceOrganization
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * @param deviceOrganization The device organization to be added.
+     * @return True if the device organization is successfully added, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while adding the device organization record.
      */
     boolean addDeviceOrganization(DeviceOrganization deviceOrganization) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * check whether a record already exist with same deviceId and parentDeviceId
-     * @param deviceId
-     * @param parentDeviceId
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * Checks whether a record already exists with the same deviceId and parentDeviceId.
+     *
+     * @param deviceId       The ID of the device.
+     * @param parentDeviceId The ID of the parent device.
+     * @return True if a record with the specified deviceId and parentDeviceId exists, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while checking the existence of the record.
      */
     boolean organizationExists(int deviceId, int parentDeviceId) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * update a record in device organization table
+     * Updates a record in the device organization table with the provided information.
      *
-     * @param deviceOrganization
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * @param deviceOrganization The DeviceOrganization object containing the updated information.
+     * @return True if the record was successfully updated, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while updating the record.
      */
-
     boolean updateDeviceOrganization(DeviceOrganization deviceOrganization)
             throws DeviceOrganizationMgtDAOException;
 
     /**
-     * @param organizationId
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * Retrieves a device organization record from the database based on the provided organization ID.
+     *
+     * @param organizationId The unique identifier of the device organization record to retrieve.
+     * @return The DeviceOrganization object representing the retrieved organization, or null if not found.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while retrieving the organization record.
      */
     DeviceOrganization getDeviceOrganizationByID(int organizationId) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * delete a record from device organization table
+     * Deletes a device organization record from the database based on the provided organization ID.
      *
-     * @param organizationId
-     * @throws DeviceOrganizationMgtDAOException
+     * @param organizationId The unique identifier of the device organization record to delete.
+     * @return true if the organization record was successfully deleted, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while deleting the organization record.
      */
     boolean deleteDeviceOrganizationByID(int organizationId) throws DeviceOrganizationMgtDAOException;
 
     /**
-     * delete a record associated with a particular device ID from device organization table
-     * delete a record if the param ID is either device_ID OR parent_device_ID in the device organization table
+     * Deletes records associated with a particular device ID from the device organization table.
+     * This method deletes records where the provided device ID matches either the deviceID column or
+     * parentDeviceID column in the device organization table.
      *
-     * @param deviceId
-     * @return
-     * @throws DeviceOrganizationMgtDAOException
+     * @param deviceId The unique identifier of the device for which associated records should be deleted.
+     * @return true if associated records were successfully deleted, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while deleting the associated records.
      */
     boolean deleteDeviceAssociations(int deviceId) throws DeviceOrganizationMgtDAOException;
 
+    /**
+     * Checks whether a record with the specified device ID exists either in the deviceID column or
+     * parentDeviceID column in the device organization table.
+     *
+     * @param deviceId The unique identifier of the device to check for existence.
+     * @return true if a record with the given device ID exists, false otherwise.
+     * @throws DeviceOrganizationMgtDAOException If an error occurs while querying the database.
+     */
     boolean doesDeviceIdExist(int deviceId) throws DeviceOrganizationMgtDAOException;
 }

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dao/DeviceOrganizationDAOFactory.java

@@ -34,8 +34,9 @@ public class DeviceOrganizationDAOFactory {
     private static String databaseEngine;
 
     /**
+     * Initialize the Device Organization Data Source.
      *
-     * @param dataSourceConfiguration
+     * @param dataSourceConfiguration The DataSourceConfig containing data source information.
      */
     public static void init(DataSourceConfig dataSourceConfiguration) {
         if (log.isDebugEnabled()) {
@@ -46,8 +47,9 @@ public class DeviceOrganizationDAOFactory {
     }
 
     /**
+     * Retrieves a DeviceOrganizationDAO implementation based on the configured database engine.
      *
-     * @return
+     * @return a DeviceOrganizationDAO implementation
      */
     public static DeviceOrganizationDAO getDeviceOrganizationDAO() {
         if (databaseEngine != null) {

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dao/impl/DeviceOrganizationDAOImpl.java

@@ -41,10 +41,16 @@ import java.util.Set;
 import static io.entgra.device.mgt.core.device.mgt.extensions.device.organization.dao.util.DeviceOrganizationDaoUtil.getDeviceFromResultSet;
 import static io.entgra.device.mgt.core.device.mgt.extensions.device.organization.dao.util.DeviceOrganizationDaoUtil.loadDeviceOrganization;
 
+/**
+ * Implementation of the DeviceOrganizationDAO interface.
+ */
 public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
 
     private static final Log log = LogFactory.getLog(DeviceOrganizationDAOImpl.class);
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceNode> getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtDAOException {
         List<DeviceNode> childNodes = new ArrayList<>();
@@ -102,6 +108,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceNode> getParentsOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtDAOException {
 
@@ -127,6 +136,7 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+
     private void getParentsRecursive(DeviceNode node, int maxDepth, Set<Integer> visited, Connection conn,
                                      List<DeviceNode> parentNodes, boolean includeDevice) throws SQLException {
         if (maxDepth <= 0 || visited.contains(node.getDeviceId())) {
@@ -164,6 +174,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceOrganization> getAllDeviceOrganizations() throws DeviceOrganizationMgtDAOException {
         List<DeviceOrganization> deviceOrganizations = new ArrayList<>();
@@ -190,6 +203,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean addDeviceOrganization(DeviceOrganization deviceOrganization)
             throws DeviceOrganizationMgtDAOException {
@@ -224,6 +240,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean organizationExists(int deviceId, int parentDeviceId) throws DeviceOrganizationMgtDAOException {
         try {
@@ -254,7 +273,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
-
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean updateDeviceOrganization(DeviceOrganization deviceOrganization)
             throws DeviceOrganizationMgtDAOException {
@@ -296,6 +317,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public DeviceOrganization getDeviceOrganizationByID(int organizationId) throws DeviceOrganizationMgtDAOException {
         try {
@@ -327,6 +351,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean deleteDeviceOrganizationByID(int organizationId) throws DeviceOrganizationMgtDAOException {
         try {
@@ -353,6 +380,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean deleteDeviceAssociations(int deviceId) throws DeviceOrganizationMgtDAOException {
         try {
@@ -385,6 +415,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean doesDeviceIdExist(int deviceId) throws DeviceOrganizationMgtDAOException {
         try {

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dao/util/ConnectionManagerUtil.java

@@ -31,6 +31,9 @@ import java.sql.SQLException;
 import java.util.Hashtable;
 import java.util.List;
 
+/**
+ * Utility class for managing database connections.
+ */
 public class ConnectionManagerUtil {
 
     private static final Log log = LogFactory.getLog(ConnectionManagerUtil.class);
@@ -38,8 +41,9 @@ public class ConnectionManagerUtil {
     private static DataSource dataSource;
 
     /**
+     * Opens a database connection.
      *
-     * @throws DBConnectionException
+     * @throws DBConnectionException If an error occurs while opening the connection.
      */
     public static void openDBConnection() throws DBConnectionException {
         Connection conn = currentConnection.get();
@@ -55,9 +59,10 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Gets a database connection.
      *
-     * @return
-     * @throws DBConnectionException
+     * @return The database connection.
+     * @throws DBConnectionException If an error occurs while getting the connection.
      */
     public static Connection getDBConnection() throws DBConnectionException {
         Connection conn = currentConnection.get();
@@ -73,8 +78,9 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Begins a new database transaction.
      *
-     * @throws DBConnectionException
+     * @throws DBConnectionException If an error occurs while starting the transaction.
      */
     public static void beginDBTransaction() throws DBConnectionException {
         Connection conn = currentConnection.get();
@@ -92,8 +98,10 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Ends the current database transaction by setting auto-commit mode to true.
      *
-     * @throws DBConnectionException
+     * @throws DBConnectionException If an error occurs while ending the transaction.
+     * @throws IllegalTransactionStateException If there is no active transaction to end.
      */
     public static void endDBTransaction() throws DBConnectionException {
         Connection conn = currentConnection.get();
@@ -113,7 +121,9 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Commits the current database transaction.
      *
+     * @throws IllegalTransactionStateException If there is no active transaction to commit.
      */
     public static void commitDBTransaction() {
         Connection conn = currentConnection.get();
@@ -133,7 +143,9 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Rolls back the current database transaction.
      *
+     * @throws IllegalTransactionStateException If there is no active transaction to roll back.
      */
     public static void rollbackDBTransaction() {
         Connection conn = currentConnection.get();
@@ -153,7 +165,9 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Closes the current database connection and removes it from the thread-local context.
      *
+     * @throws IllegalTransactionStateException If there is no active database connection to close.
      */
     public static void closeDBConnection() {
         Connection conn = currentConnection.get();
@@ -169,9 +183,11 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Checks if the provided database connection is currently in a transaction.
      *
-     * @param conn
-     * @return
+     * @param conn The database connection to check.
+     * @return True if the connection is in a transaction, false otherwise.
+     * @throws IllegalTransactionStateException If there is an issue checking the transaction state.
      */
     private static boolean inTransaction(Connection conn) {
         boolean inTransaction = true;
@@ -186,9 +202,10 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Checks if a transaction has been started on the current database connection.
      *
-     * @return
-     * @throws DBConnectionException
+     * @return True if a transaction has been started, false otherwise.
+     * @throws DBConnectionException If there is an issue obtaining a database connection.
      */
     public static boolean isTransactionStarted() throws DBConnectionException {
         Connection connection = getDBConnection();
@@ -196,10 +213,11 @@ public class ConnectionManagerUtil {
     }
 
     /**
-     * Resolve data source from the data source definition.
+     * Resolve a data source from the given data source configuration.
      *
-     * @param config Data source configuration
-     * @return data source resolved from the data source definition
+     * @param config Data source configuration.
+     * @return A data source resolved based on the configuration.
+     * @throws RuntimeException If the data source configuration is null and not initialized.
      */
     public static DataSource resolveDataSource(DataSourceConfig config) {
         if (config == null) {
@@ -228,10 +246,12 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Lookup a data source using the given data source name and JNDI properties.
      *
-     * @param dataSourceName
-     * @param jndiProperties
-     * @return
+     * @param dataSourceName  The JNDI name of the data source to lookup.
+     * @param jndiProperties  Optional JNDI properties used for the lookup.
+     * @return A data source object representing the looked-up data source.
+     * @throws RuntimeException If an error occurs during the lookup process.
      */
     public static DataSource lookupDataSource(String dataSourceName,
                                               final Hashtable<Object, Object> jndiProperties) {
@@ -250,8 +270,10 @@ public class ConnectionManagerUtil {
     }
 
     /**
+     * Get the name of the database product to which the current connection belongs.
      *
-     * @return
+     * @return A string representing the name of the database product.
+     *         Returns null if an error occurs during the retrieval process.
      */
     public static String getDatabaseType() {
         try {

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dao/util/DeviceOrganizationDaoUtil.java

@@ -19,9 +19,9 @@ public class DeviceOrganizationDaoUtil {
 
     /**
      * Helper method to create a Device Organization object from a ResultSet
-     * @param rs
-     * @return
-     * @throws SQLException
+     * @param rs The ResultSet containing the organization data.
+     * @return A DeviceOrganization object.
+     * @throws SQLException If there's an issue reading data from the ResultSet.
      */
     public static DeviceOrganization loadDeviceOrganization(ResultSet rs) throws SQLException {
         DeviceOrganization deviceOrganization = new DeviceOrganization() {
@@ -38,10 +38,10 @@ public class DeviceOrganizationDaoUtil {
     }
 
     /**
-     * Helper method to create a Device object from a ResultSet
-     * @param rs
-     * @return
-     * @throws SQLException
+     * Helper method to create a DeviceNode object from a ResultSet
+     * @param rs The ResultSet containing device data.
+     * @return A DeviceNode object.
+     * @throws SQLException If there's an issue reading data from the ResultSet.
      */
     public static DeviceNode getDeviceFromResultSet(ResultSet rs) throws SQLException {
         DeviceNode node = new DeviceNode();

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dto/DeviceNode.java

@@ -23,7 +23,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * This class is used in DeviceOrganizationService
+ * This class represents a node in a device hierarchy used in various organizational structures,
+ * including hierarchical organizations, sequential organizations, multiple root organizations,
+ * and multiple child organizations.
  */
 public class DeviceNode {
 

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/dto/DeviceOrganization.java

@@ -22,7 +22,8 @@ package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.dto;
 import java.util.Date;
 
 /**
- * This class is used in DeviceOrganizationService
+ * This abstract class represents a device organization entity used in DeviceOrganizationService.
+ * It serves as a base class for defining various organizational structures related to devices.
  */
 public abstract class DeviceOrganization {
 

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/exception/BadRequestDaoException.java

@@ -1,5 +1,9 @@
 package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.exception;
 
+/**
+ * This exception is thrown when a bad request is encountered in the Device Organization Management DAO layer.
+ * It typically indicates issues with the input parameters or data during DAO operations.
+ */
 public class BadRequestDaoException extends DeviceOrganizationMgtDAOException{
 
     private static final long serialVersionUID = -6275360486437601206L;

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/exception/BadRequestException.java

@@ -19,7 +19,9 @@
 package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.exception;
 
 /**
- * Represents the exception thrown during validating the request.
+ * Represents an exception thrown during the validation of a request in the Device Organization
+ * Management Plugin. This exception is typically thrown when the request parameters or
+ * data are invalid or do not meet the required criteria.
  */
 public class BadRequestException extends DeviceOrganizationMgtPluginException {
     private static final long serialVersionUID = -2036794959420530981L;

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/exception/DBConnectionException.java

@@ -20,14 +20,27 @@ package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.exce
 
 /**
  * Exception thrown due to Database Connection issues.
+ * This exception is typically thrown when there are problems establishing or maintaining a
+ * database connection.
  */
 public class DBConnectionException extends Exception {
     private static final long serialVersionUID = 8485257804482934068L;
 
+    /**
+     * Constructs a new `DBConnectionException` with the specified detail message and a cause.
+     *
+     * @param message The detail message that describes the exception.
+     * @param cause   The cause of the exception.
+     */
     public DBConnectionException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Constructs a new `DBConnectionException` with the specified detail message.
+     *
+     * @param msg The detail message that describes the exception.
+     */
     public DBConnectionException(String msg) {
         super(msg);
     }

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/exception/DeviceOrganizationMgtDAOException.java

@@ -20,38 +20,76 @@ package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.exce
 
 /**
  * Exception thrown during the DeviceOrganization Management DAO operations.
+ * This exception is typically used to handle errors related to DeviceOrganization management
+ * data access operations.
  */
 public class DeviceOrganizationMgtDAOException extends Exception {
     private static final long serialVersionUID = 2412162605436684110L;
     private String errorMessage;
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtDAOException` without a specified detail message.
+     */
     public DeviceOrganizationMgtDAOException() {
         super();
     }
 
+
+    /**
+     * Constructs a new `DeviceOrganizationMgtDAOException` with a specified cause.
+     *
+     * @param cause The cause of the exception.
+     */
     public DeviceOrganizationMgtDAOException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtDAOException` with a specified detail message and a nested exception.
+     *
+     * @param msg       The detail message that describes the exception.
+     * @param nestedEx  The nested exception.
+     */
     public DeviceOrganizationMgtDAOException(String msg, Exception nestedEx) {
         super(msg, nestedEx);
         setErrorMessage(msg);
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtDAOException` with a specified detail message and a cause.
+     *
+     * @param message The detail message that describes the exception.
+     * @param cause   The cause of the exception.
+     */
     public DeviceOrganizationMgtDAOException(String message, Throwable cause) {
         super(message, cause);
         setErrorMessage(message);
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtDAOException` with a specified detail message.
+     *
+     * @param msg The detail message that describes the exception.
+     */
     public DeviceOrganizationMgtDAOException(String msg) {
         super(msg);
         setErrorMessage(msg);
     }
 
+    /**
+     * Get the error message associated with this exception.
+     *
+     * @return The error message.
+     */
     public String getErrorMessage() {
         return errorMessage;
     }
 
+    /**
+     * Set the error message for this exception.
+     *
+     * @param errorMessage The error message.
+     */
     public void setErrorMessage(String errorMessage) {
         this.errorMessage = errorMessage;
     }

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/exception/DeviceOrganizationMgtPluginException.java

@@ -20,6 +20,7 @@ package io.entgra.device.mgt.core.device.mgt.extensions.device.organization.exce
 
 /**
  * Exception thrown during the DeviceOrganization Management operations.
+ * This exception is typically used to handle errors related to DeviceOrganization management operations.
  */
 public class DeviceOrganizationMgtPluginException extends Exception {
 
@@ -27,33 +28,69 @@ public class DeviceOrganizationMgtPluginException extends Exception {
 
     private String errorMessage;
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtPluginException` without a specified detail message.
+     */
     public DeviceOrganizationMgtPluginException() {
         super();
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtPluginException` with a specified cause.
+     *
+     * @param cause The cause of the exception.
+     */
     public DeviceOrganizationMgtPluginException(Throwable cause) {
         super(cause);
     }
 
+
+    /**
+     * Constructs a new `DeviceOrganizationMgtPluginException` with a specified detail message and a nested exception.
+     *
+     * @param msg       The detail message that describes the exception.
+     * @param nestedEx  The nested exception.
+     */
     public DeviceOrganizationMgtPluginException(String msg, Exception nestedEx) {
         super(msg, nestedEx);
         setErrorMessage(msg);
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtPluginException` with a specified detail message and a cause.
+     *
+     * @param message The detail message that describes the exception.
+     * @param cause   The cause of the exception.
+     */
     public DeviceOrganizationMgtPluginException(String message, Throwable cause) {
         super(message, cause);
         setErrorMessage(message);
     }
 
+    /**
+     * Constructs a new `DeviceOrganizationMgtPluginException` with a specified detail message.
+     *
+     * @param msg The detail message that describes the exception.
+     */
     public DeviceOrganizationMgtPluginException(String msg) {
         super(msg);
         setErrorMessage(msg);
     }
 
+    /**
+     * Get the error message associated with this exception.
+     *
+     * @return The error message.
+     */
     public String getErrorMessage() {
         return errorMessage;
     }
 
+    /**
+     * Set the error message for this exception.
+     *
+     * @param errorMessage The error message.
+     */
     public void setErrorMessage(String errorMessage) {
         this.errorMessage = errorMessage;
     }

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/impl/DeviceOrganizationServiceImpl.java

@@ -42,6 +42,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         this.deviceOrganizationDao = DeviceOrganizationDAOFactory.getDeviceOrganizationDAO();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceNode> getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice)
             throws DeviceOrganizationMgtPluginException {
@@ -73,6 +76,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceNode> getParentsOf(DeviceNode node, int maxDepth, boolean includeDevice)
             throws DeviceOrganizationMgtPluginException {
@@ -104,8 +110,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
-
-    // In DeviceOrganizationServiceImpl.java (implementation)
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public List<DeviceOrganization> getAllDeviceOrganizations() throws DeviceOrganizationMgtPluginException {
         try {
@@ -126,7 +133,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
-
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean addDeviceOrganization(DeviceOrganization deviceOrganization)
             throws DeviceOrganizationMgtPluginException {
@@ -174,7 +183,20 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
-    // Helper method to check if an organization with the same deviceID and parentDeviceID already exists
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void addDeviceOrganizationList(List<DeviceOrganization> deviceOrganizationList)
+            throws DeviceOrganizationMgtPluginException {
+        for (DeviceOrganization deviceOrganization : deviceOrganizationList){
+            boolean result = addDeviceOrganization(deviceOrganization);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean organizationExists(int deviceID, int parentDeviceID) throws DeviceOrganizationMgtPluginException {
         try {
@@ -195,6 +217,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean updateDeviceOrganization(DeviceOrganization organization)
             throws DeviceOrganizationMgtPluginException {
@@ -247,6 +272,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public DeviceOrganization getDeviceOrganizationByID(int organizationID)
             throws DeviceOrganizationMgtPluginException {
@@ -275,6 +303,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean deleteDeviceOrganizationByID(int organizationID)
             throws DeviceOrganizationMgtPluginException {
@@ -324,6 +355,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean deleteDeviceAssociations(int deviceID)
             throws DeviceOrganizationMgtPluginException {
@@ -372,6 +406,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean doesDeviceIdExist(int deviceID)
             throws DeviceOrganizationMgtPluginException {

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/main/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/spi/DeviceOrganizationService.java

@@ -23,34 +23,123 @@ import io.entgra.device.mgt.core.device.mgt.extensions.device.organization.excep
 
 import java.util.List;
 
+/**
+ * This interface defines operations for managing device organizations.
+ */
 public interface DeviceOrganizationService {
 
+    /**
+     * Adds a new device organization.
+     *
+     * @param deviceOrganization The device organization to add.
+     * @return True if the operation was successful, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean addDeviceOrganization(DeviceOrganization deviceOrganization)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Retrieves a list of child nodes of a given device node, up to a specified depth.
+     *
+     * @param node          The parent device node.
+     * @param maxDepth      The maximum depth of child nodes to retrieve.
+     * @param includeDevice Indicates whether to include device information in the retrieved nodes.
+     * @return A list of child device nodes.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     List<DeviceNode> getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Retrieves a list of parent nodes of a given device node, up to a specified depth.
+     *
+     * @param node          The child device node.
+     * @param maxDepth      The maximum depth of parent nodes to retrieve.
+     * @param includeDevice Indicates whether to include device information in the retrieved nodes.
+     * @return A list of parent device nodes.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     List<DeviceNode> getParentsOf(DeviceNode node, int maxDepth, boolean includeDevice)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Adds a list of device organizations.
+     *
+     * @param deviceOrganizations The list of device organizations to add.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
+    void addDeviceOrganizationList(List<DeviceOrganization> deviceOrganizations)
+            throws DeviceOrganizationMgtPluginException;
+
+    /**
+     * Retrieves a list of all device organizations.
+     *
+     * @return A list of all device organizations.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     List<DeviceOrganization> getAllDeviceOrganizations() throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Retrieves a specific device organization by its organization ID.
+     *
+     * @param organizationId The organization ID of the device organization to retrieve.
+     * @return The device organization with the specified ID.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     DeviceOrganization getDeviceOrganizationByID(int organizationId)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Checks if a device organization with the specified device and parent device IDs already exists.
+     *
+     * @param deviceId       The ID of the device.
+     * @param parentDeviceId The ID of the parent device.
+     * @return True if the organization exists, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean organizationExists(int deviceId, int parentDeviceId)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Checks whether a record with the specified device ID exists either in the deviceID column or
+     * parentDeviceID column in the device organization table.
+     *
+     * @param deviceId The ID of the device to check.
+     * @return True if the device exists, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean doesDeviceIdExist(int deviceId)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Updates a device organization.
+     *
+     * @param organization The device organization to update.
+     * @return True if the operation was successful, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean updateDeviceOrganization(DeviceOrganization organization)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Deletes a device organization by its organizationID.
+     *
+     * @param organizationId The organization ID of the device organization to delete.
+     * @return True if the operation was successful, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean deleteDeviceOrganizationByID(int organizationId)
             throws DeviceOrganizationMgtPluginException;
 
+    /**
+     * Deletes records associated with a particular device ID from the device organization table.
+     * This method deletes records where the provided device ID matches either the deviceID column or
+     * parentDeviceID column in the device organization table.
+     *
+     * @param deviceId The ID of the device for which associations should be deleted.
+     * @return True if the operation was successful, false otherwise.
+     * @throws DeviceOrganizationMgtPluginException If an error occurs during the operation.
+     */
     boolean deleteDeviceAssociations(int deviceId)
             throws DeviceOrganizationMgtPluginException;
 

components/device-mgt-extensions/io.entgra.device.mgt.core.device.mgt.extensions.device.organization/src/test/java/io/entgra/device/mgt/core/device/mgt/extensions/device/organization/DAOTest.java

@@ -55,7 +55,6 @@ public class DAOTest extends BaseDeviceOrganizationTest {
         Assert.assertNotNull(parentList, "Cannot be null");
     }
 
-
     @Test
     public void testAddDeviceOrganizationDAO() throws DBConnectionException, DeviceOrganizationMgtDAOException {