From 4bd5b7d2231a39348535026a852aa3ded3cbe540 Mon Sep 17 00:00:00 2001 From: isuri Date: Tue, 26 Sep 2023 15:32:38 +0530 Subject: [PATCH] doc comments --- .../dao/DeviceOrganizationDAO.java | 93 +++++++++++-------- .../dao/DeviceOrganizationDAOFactory.java | 6 +- .../dao/impl/DeviceOrganizationDAOImpl.java | 35 ++++++- .../dao/util/ConnectionManagerUtil.java | 54 +++++++---- .../dao/util/DeviceOrganizationDaoUtil.java | 14 +-- .../device/organization/dto/DeviceNode.java | 4 +- .../organization/dto/DeviceOrganization.java | 3 +- .../exception/BadRequestDaoException.java | 4 + .../exception/BadRequestException.java | 4 +- .../exception/DBConnectionException.java | 13 +++ .../DeviceOrganizationMgtDAOException.java | 38 ++++++++ .../DeviceOrganizationMgtPluginException.java | 37 ++++++++ .../impl/DeviceOrganizationServiceImpl.java | 45 ++++++++- .../spi/DeviceOrganizationService.java | 89 ++++++++++++++++++ .../device/organization/DAOTest.java | 1 - 15 files changed, 367 insertions(+), 73 deletions(-) diff --git a/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 b/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 index 9418ed79a2..3b09017c70 100644 --- a/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 +++ b/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 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 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 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; } diff --git a/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 b/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 index 8cd8763f03..6b58363d7f 100644 --- a/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 +++ b/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) { diff --git a/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 b/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 index c256d9ffe7..bf5e451681 100644 --- a/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 +++ b/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 getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtDAOException { List childNodes = new ArrayList<>(); @@ -102,6 +108,9 @@ public class DeviceOrganizationDAOImpl implements DeviceOrganizationDAO { } } + /** + * {@inheritDoc} + */ @Override public List 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 visited, Connection conn, List 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 getAllDeviceOrganizations() throws DeviceOrganizationMgtDAOException { List 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 { diff --git a/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 b/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 index 26277c41a8..e8c3012347 100644 --- a/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 +++ b/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 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 { diff --git a/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 b/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 index 23b980f108..5cd1f0df82 100644 --- a/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 +++ b/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(); diff --git a/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 b/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 index 7d0d81ec1f..3ec106543e 100644 --- a/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 +++ b/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 { diff --git a/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 b/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 index dd02b8dc45..c90350c7a6 100644 --- a/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 +++ b/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 { diff --git a/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 b/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 index 22a4a95579..d453449c4e 100644 --- a/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 +++ b/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; diff --git a/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 b/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 index b5dae69fb5..0a87897426 100644 --- a/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 +++ b/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; diff --git a/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 b/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 index 7414aec104..69818565ae 100644 --- a/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 +++ b/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); } diff --git a/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 b/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 index 9cf394ad6d..16502d05a6 100644 --- a/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 +++ b/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; } diff --git a/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 b/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 index 7cf3d497f3..a4ca5b9355 100644 --- a/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 +++ b/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; } diff --git a/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 b/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 index c3712c9a5c..ef6d324999 100644 --- a/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 +++ b/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 getChildrenOf(DeviceNode node, int maxDepth, boolean includeDevice) throws DeviceOrganizationMgtPluginException { @@ -73,6 +76,9 @@ public class DeviceOrganizationServiceImpl implements DeviceOrganizationService } } + /** + * {@inheritDoc} + */ @Override public List 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 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 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 { diff --git a/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 b/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 index 52b1d49f3a..652b677d3a 100644 --- a/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 +++ b/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 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 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 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 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; diff --git a/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 b/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 index 9a7b7bb129..a70f2da26d 100644 --- a/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 +++ b/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 {