diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/dao/DeviceManagementDAOFactory.java b/components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/dao/DeviceManagementDAOFactory.java index 7c86387ee4..8d28f17825 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/dao/DeviceManagementDAOFactory.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.core/src/main/java/org/wso2/carbon/device/mgt/core/dao/DeviceManagementDAOFactory.java @@ -32,6 +32,52 @@ import java.sql.SQLException; import java.util.Hashtable; import java.util.List; +/** + * This class intends to act as the primary entity that hides all DAO instantiation related complexities and logic so + * that the business objection handling layer doesn't need to be aware of the same providing seamless plug-ability of + * different data sources, connection acquisition mechanisms as well as different forms of DAO implementations to the + * high-level implementations that require device management related metadata persistence. + *
+ * In addition, this also provides means to handle transactions across multiple device management related DAO objects. + * Any high-level business logic that requires transaction handling to be done via utility methods provided in + * DeviceManagementDAOFactory should adhere the following guidelines to avoid any unexpected behaviour that can cause + * as a result of improper use of the aforementioned utility method. + * + * Any transaction that commits data into the underlying data persistence mechanism MUST follow the sequence of + * operations mentioned below. + * + *
+ * {@code
+ * try {
+ * DeviceManagementDAOFactory.beginTransaction();
+ * .....
+ * DeviceManagementDAOFactory.commitTransaction();
+ * return success;
+ * } catch (Exception e) {
+ * DeviceManagementDAOFactory.rollbackTransaction();
+ * throw new DeviceManagementException("Error occurred while ...", e);
+ * } finally {
+ * DeviceManagementDAOFactory.closeConnection();
+ * }
+ * }
+ *
+ *
+ * Any transaction that retrieves data from the underlying data persistence mechanism MUST follow the sequence of
+ * operations mentioned below.
+ *
+ *
+ * {@code
+ * try {
+ * DeviceManagementDAOFactory.openConnection();
+ * .....
+ * } catch (Exception e) {
+ * throw new DeviceManagementException("Error occurred while ..., e);
+ * } finally {
+ * DeviceManagementDAOFactory.closeConnection();
+ * }
+ * }
+ *
+ */
public class DeviceManagementDAOFactory {
private static DataSource dataSource;