Add files via upload

Author: arsakarme

AttributeType.java

@@ -25,7 +25,12 @@
 package sync.db.mysql;
 
 /**
- *
+ * Enum class that defines the type of attribute being mapped between two tables.
+ * <p>
+ * <b>STRING</b> type refers to all attributes that require them to be 
+ * surrounded with a '' or "" in a MySQL insert statement.
+ * <b>NUMERICAL</b> type refers to all attributes that do not require them to 
+ * be surrounded with a '' or "" in a MySQL insert statement.
  * @author Arvind Sasikumar
  */
 public enum AttributeType {

DBSyncAgent.java

@@ -27,7 +27,36 @@
 import java.sql.*;
 
 /**
- * 
+ * An object of this class serves as the agent for the synchronization process.
+ * All synchronization tasks are handed over to an object of this class, which 
+ * then takes the required steps to perform the actual synchronization depending 
+ * on its set properties. It requires all details for establishing a connection 
+ * to the server and client MySQL servers and some additional synchronization 
+ * specific properties.<p>
+ * An object of this class is created using the Builder pattern as opposed to 
+ * the usual constructor based initialization.<p>
+ * An example on using the Builder pattern to create a new DBSyncObject:<p>
+ * <pre>
+ * {@code
+ * DBSyncAgent dbSyncAgent = new DBSyncAgent.Builder()
+                            .setServerDatabaseAddress("localhost")
+                            .setServerDatabaseName("test1")
+                            .setServerDatabaseUsername("root")
+                            .setServerDatabasePassword("root")
+                            .setServerDatabasePort(3306)
+                            .setServerDatabaseConnectionOptions("?useSSL=false")
+                            .setClientDatabaseAddress("localhost")
+                            .setClientDatabaseName("test2")
+                            .setClientDatabaseUsername("root")
+                            .setClientDatabasePassword("root")
+                            .setClientDatabasePort(3306)
+                            .setClientDatabaseConnectionOptions("?useSSL=false")
+                            .setDBMap(dbMap)
+                            .setSyncInterval(12)
+                            .build();
+ * }
+ * </pre>
+ * @see #DBSyncAgent(sync.db.mysql.DBSyncAgent.Builder) 
  * @author Arvind Sasikumar
  */
 public class DBSyncAgent {
@@ -58,6 +87,11 @@ public class DBSyncAgent {
 
     private DBSynchronizer dbSynchronizer;
 
+    /**
+     * Build the DBSyncAgent class using the Builder pattern.
+     * @author Arvind Sasikumar
+     * @see <a href="http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern">Builder Pattern</a>
+     */
     public static class Builder{
 
         private String serverDatabaseAddress;
@@ -78,96 +112,194 @@ public static class Builder{
 
         private int syncInterval;
 
+        /**
+         * Set the address of the server database.
+         * @param serverDatabaseAddress address of the server database, 
+         * e.g. "localhost" or "59.23.54.22"
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setServerDatabaseAddress(String serverDatabaseAddress){
 
             this.serverDatabaseAddress = serverDatabaseAddress;
             return this;
         }
 
+        /**
+         * Set the name of the server database.
+         * @param serverDatabaseName name of the server database, e.g. "testdb"
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setServerDatabaseName(String serverDatabaseName){
 
             this.serverDatabaseName = serverDatabaseName;
             return this;
         }
 
+        /**
+         * Set the username to access the server database.
+         * @param serverDatabaseUsername username to access the server database
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setServerDatabaseUsername(String serverDatabaseUsername){
 
             this.serverDatabaseUsername = serverDatabaseUsername;
             return this;
         }
 
+        /**
+         * Set the password to access the server database.
+         * @param serverDatabasePassword password to access the server database
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setServerDatabasePassword(String serverDatabasePassword){
 
             this.serverDatabasePassword = serverDatabasePassword;
             return this;
         }
 
-        public Builder setServerDatabaseConnectionOptions(String serverDatabaseConnectionOptions){
+        /**
+         * Set the optional connection string to be used for the server 
+         * connection.
+         * All options in the MySQL connection string as per the Connector/J 
+         * appear here. e.g. "?useSSL=false"
+         * @param serverDatabaseConnectionOptions optional connection string
+         * @return Builder object as per the Builder pattern
+         */
+        public Builder setServerDatabaseConnectionOptions(String 
+                                            serverDatabaseConnectionOptions){
 
-            this.serverDatabaseConnectionOptions = serverDatabaseConnectionOptions;
+            this.serverDatabaseConnectionOptions 
+                                            = serverDatabaseConnectionOptions;
             return this;
         }
 
+        /**
+         * Set the port for the server connection.
+         * @param serverDatabasePort port for the server connection, e.g. 3306
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setServerDatabasePort(int serverDatabasePort){
 
             this.serverDatabasePort = serverDatabasePort;
             return this;
         }
 
+        /**
+         * Set the address of the client database.
+         * @param clientDatabaseAddress address of the client database, 
+         * e.g. "localhost" or "59.23.54.22"
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setClientDatabaseAddress(String clientDatabaseAddress){
 
             this.clientDatabaseAddress = clientDatabaseAddress;
             return this;
         }
 
+        /**
+         * Set the name of the client database.
+         * @param clientDatabaseName name of the client database, e.g. "testdb"
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setClientDatabaseName(String clientDatabaseName){
 
             this.clientDatabaseName = clientDatabaseName;
             return this;
         }
 
+        /**
+         * Set the username to access the client database.
+         * @param clientDatabaseUsername username to access the client database
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setClientDatabaseUsername(String clientDatabaseUsername){
 
             this.clientDatabaseUsername = clientDatabaseUsername;
             return this;
         }
 
+        /**
+         * Set the password to access the client database.
+         * @param clientDatabasePassword password to access the client database
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setClientDatabasePassword(String clientDatabasePassword){
 
             this.clientDatabasePassword = clientDatabasePassword;
             return this;
         }
 
-        public Builder setClientDatabaseConnectionOptions(String clientDatabaseConnectionOptions){
+        /**
+         * Set the optional connection string to be used for the client 
+         * connection.
+         * All options in the MySQL connection string as per the Connector/J 
+         * appear here. e.g. "?useSSL=false"
+         * @param clientDatabaseConnectionOptions optional connection string
+         * @return Builder object as per the Builder pattern
+         */
+        public Builder setClientDatabaseConnectionOptions(String 
+                                            clientDatabaseConnectionOptions){
 
-            this.clientDatabaseConnectionOptions = clientDatabaseConnectionOptions;
+            this.clientDatabaseConnectionOptions 
+                                            = clientDatabaseConnectionOptions;
             return this;
         }
 
+        /**
+         * Set the port for the client connection.
+         * @param clientDatabasePort port for the client connection, e.g. 3306
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setClientDatabasePort(int clientDatabasePort){
 
             this.clientDatabasePort = clientDatabasePort;
             return this;
         }
 
+        /**
+         * Set the database map.
+         * @param dbMap database map
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setDBMap(DBMap dbMap){
 
             this.dbMap = dbMap;
             return this;
         }
 
+        /**
+         * Set the synchronization interval.
+         * This specifies the time interval between two successive 
+         * synchronization attempts during a live sync. Specified in seconds.
+         * @param syncInterval synchronization interval in seconds
+         * @return Builder object as per the Builder pattern
+         */
         public Builder setSyncInterval(int syncInterval){
 
             this.syncInterval = syncInterval;
             return this;
         }
 
+        /**
+         * Build the DBSyncAgent object using the Builder pattern after all 
+         * properties have been set using the Builder class.
+         * @return a new DBSyncAgent object with all properties set
+         * @see <a href="http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern">Builder Pattern</a>
+         */
         public DBSyncAgent build(){
 
             return new DBSyncAgent(this);
         }
     }
 
+    /**
+     * Create a new DBSyncAgent object using the Builder Pattern.
+     * This constructor is declared as private and is hence not accessible from 
+     * outside. To use this constructor, one must use the Builder pattern.
+     * @param builder the builder object used to build the new DBSyncAgent 
+     * object using the Builder pattern
+     * @see <a href="http://stackoverflow.com/questions/328496/when-would-you-use-the-builder-pattern">Builder Pattern</a>
+     */
     private DBSyncAgent(Builder builder){
 
         serverDatabaseAddress = builder.serverDatabaseAddress;
@@ -189,11 +321,20 @@ private DBSyncAgent(Builder builder){
         syncInterval = builder.syncInterval;
     }
 
+    /**
+      * Set the synchronization interval.
+      * This specifies the time interval between two successive 
+      * synchronization attempts during a live sync. Specified in seconds.
+      * @param syncInterval synchronization interval in seconds
+     */
     public void setSyncInterval(int syncInterval){
 
         this.syncInterval = syncInterval;
     }
 
+    /**
+     * Connects to the client and server databases as per the set properties.
+     */
     public void connect(){
 
         try{
@@ -203,13 +344,15 @@ public void connect(){
             String connectionString = "jdbc:mysql://" + serverDatabaseAddress + ":" +
                                       serverDatabasePort + "/" + serverDatabaseName +
                                       serverDatabaseConnectionOptions;
-            serverConnection = DriverManager.getConnection(connectionString,serverDatabaseUsername,serverDatabasePassword);
+            serverConnection = DriverManager.getConnection(connectionString,
+                                serverDatabaseUsername,serverDatabasePassword);
             serverStatement = serverConnection.createStatement();
 
             connectionString = "jdbc:mysql://" + clientDatabaseAddress + ":" +
                                clientDatabasePort + "/" + clientDatabaseName +
                                clientDatabaseConnectionOptions;
-            clientConnection = DriverManager.getConnection(connectionString,clientDatabaseUsername,clientDatabasePassword);
+            clientConnection = DriverManager.getConnection(connectionString,
+                                clientDatabaseUsername,clientDatabasePassword);
             clientStatement = clientConnection.createStatement();
         }
 
@@ -219,22 +362,58 @@ public void connect(){
         }         
     }
 
+    /**
+     * Performs initial synchronization between the client and the server 
+     * databases.
+     * When synchronization is done for the first time or after a reasonable 
+     * interval of time, call this function before calling the {@link #liveSync()}.
+     */
     public void sync(){
 
         dbSynchronizer = new DBSynchronizer(serverStatement, clientStatement, dbMap);
         Thread dbSynchronizerThread = new Thread(dbSynchronizer);
         dbSynchronizerThread.start();
     }
 
+    /**
+     * Synchronizes the client and the server databases periodically.
+     * This synchronization is done periodically as specified using 
+     * {@link #setSyncInterval(int)} or initialized using the Builder pattern.
+     */
     public void liveSync(){
 
-        dbSynchronizer = new DBSynchronizer(serverStatement, clientStatement, dbMap, syncInterval);
+        dbSynchronizer = new DBSynchronizer(serverStatement, clientStatement, 
+                                                            dbMap, syncInterval);
         Thread dbSynchronizerThread = new Thread(dbSynchronizer);
         dbSynchronizerThread.start();
     }
 
+    /**
+     * Stops the synchronization process.
+     * The current transaction will be finished before the stop takes places 
+     * to make sure the database is in proper state.
+     */
     public void stopSync(){
 
         dbSynchronizer.stopSync();
     }
+    
+    /**
+     * Disconnects the existing client and server connections safely.
+     * Call this after calling {@link #stopSync()} if a {@link #liveSync()} is 
+     * in progress.
+     */
+    public void disconnect(){
+        
+        try{
+            
+            clientStatement.close();
+            serverStatement.close();
+        }
+        
+        catch(Exception e){
+            
+            e.printStackTrace();
+        }
+    }
 }