org.quickconnectfamily.sync
Class SynchronizedDB

java.lang.Object
  extended by org.quickconnectfamily.sync.SynchronizedDB

public class SynchronizedDB
extends java.lang.Object

The SynchronizedDB class provides a safe way of keeping a SQLite file on an Android device in sync with a remote server. The API for this class is the only API needed.
This class depends upon the QCDBAccess library. It must also be included in your project.
Transactions are started and stopped using the SynchronizedDB startTransaction and endTransaction methods. If any error occurs while executing the SQL found within these two transaction method calls then a roll back of the changes made will be executed.
If your database is not going to be used any longer you can use the SynchronizedDB cleanUp method to free the resources.

Author:
Lee S. Barney

Constructor Summary
SynchronizedDB(java.lang.ref.WeakReference<android.content.Context> theActivityRef, java.lang.String aDbName, java.net.URL aRemoteURL, int port, java.lang.String aRemoteUname, java.lang.String aRemotePword, long syncTimeout)
          Creates a SynchronizedDB object used to interact with a local database and a remote HTTP service.
 
Method Summary
 void cleanUp()
          This method sends a logout command to the remote HTTP service and closes down the HTTP client on the Android device.
 void clearSync()
          This is a method that should rarely, if ever, be used.
 void endTransaction()
          This method is called after the startTransaction method and any number of setData calls.
 DataAccessResult getData(java.lang.String sqlKey, java.lang.Object[] parameters)
          This method is used to retrieve data from the SQLite database on the device.
 void registerSynchedStatement(java.lang.String sqlKey, java.lang.String SQL)
          This method is used to associate a representative key String with a String containing SQL.
 void registerSyncStatements(java.util.HashMap<java.lang.String,java.lang.String> keySQLMap)
          This method is used to associate a series of key - SQL pairs as if they had been registered individually using the registerSynchedStatement method.
 DataAccessResult setData(java.lang.String sqlKey, java.lang.Object[] parameters)
          This method is used to insert data into the SQLite database on the device or do any other type of database modification.
 void startTransaction()
          This method is called prior to making multiple setData calls.
 void sync()
          This method pushes any stored setData parameters to the HTTP service, waits for any data from the service, and then inserts any data received from the service into the appropriate tables in the local SQLite database.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SynchronizedDB

public SynchronizedDB(java.lang.ref.WeakReference<android.content.Context> theActivityRef,
                      java.lang.String aDbName,
                      java.net.URL aRemoteURL,
                      int port,
                      java.lang.String aRemoteUname,
                      java.lang.String aRemotePword,
                      long syncTimeout)
               throws DataAccessException,
                      java.net.URISyntaxException,
                      java.lang.InterruptedException
Creates a SynchronizedDB object used to interact with a local database and a remote HTTP service. It sends a login request to the

Parameters:
theActivityRef - - the activity that the database is associated with. This is usually your initial Acivity class.
aDbName - - the name of the SQLite file to be kept in sync.
aRemoteURL - - the URL of the service that will respond to synchronization requests including the port number if not port 80. For security reasons it is suggested that your URL be an HTTPS URL but this is not required.
port - - the port number of the remote HTTP service.
aRemoteUname - - a security credential used in the remote service
aRemotePword - - a security credential used in the remote service
syncTimeout - - the amount of time in seconds to attempt all sync requests before timing out.
Throws:
DataAccessException
java.net.URISyntaxException
java.lang.InterruptedException
Method Detail

registerSynchedStatement

public void registerSynchedStatement(java.lang.String sqlKey,
                                     java.lang.String SQL)
                              throws java.lang.InterruptedException
This method is used to associate a representative key String with a String containing SQL. All SQL that is used to interact with the database must be registered if it is to be used with the setData and getData SynchronizedDB methods.

Parameters:
sqlKey - - a representative String describing the SQL. Usually one word or camel case phrase.
SQL - - the SQL to be executed later using the getData or setData methods.
Throws:
java.lang.InterruptedException

registerSyncStatements

public void registerSyncStatements(java.util.HashMap<java.lang.String,java.lang.String> keySQLMap)
                            throws java.lang.InterruptedException
This method is used to associate a series of key - SQL pairs as if they had been registered individually using the registerSynchedStatement method.

Parameters:
keySQLMap - - a HashMap containing multiple key/SQL pairs to be registered for later use.
Throws:
java.lang.InterruptedException

getData

public DataAccessResult getData(java.lang.String sqlKey,
                                java.lang.Object[] parameters)
                         throws DataAccessException,
                                java.lang.InterruptedException
This method is used to retrieve data from the SQLite database on the device.

Parameters:
sqlKey - - the key representing the SQL to be executed. This may be a standard or prepared SQL statement but must have previously been registered using one of the registerSync* methods.
parameters - - an array of objects to be bound to the ? place holders if the registered SQL is to be used as a prepared statement.
Returns:
a DataAccessResult containing the data retrieved by the query, the names of the resultant fields, and any SQL error that may have been generated by faulty SQL. See the QCDBAccess library documentation.
Throws:
DataAccessException
java.lang.InterruptedException

setData

public DataAccessResult setData(java.lang.String sqlKey,
                                java.lang.Object[] parameters)
                         throws DataAccessException,
                                java.lang.InterruptedException,
                                JSONException
This method is used to insert data into the SQLite database on the device or do any other type of database modification.

Parameters:
sqlKey - - the key representing the SQL to be executed. This may be a standard or prepared SQL statement but must have previously been registered using one of the registerSync* methods.
parameters - - an array of objects to be bound to the ? place holders if the registered SQL is to be used as a prepared statement. This array of values is stored for sending to the remote HTTP service as data to be synchronized and stored in the remote database behind the service.
Returns:
a DataAccessResult containing a SQL error if any was generated by faulty SQL. See the QCDBAccess library documentation.
Throws:
DataAccessException
java.lang.InterruptedException
JSONException

startTransaction

public void startTransaction()
                      throws java.lang.InterruptedException,
                             DataAccessException
This method is called prior to making multiple setData calls. It starts an SQLite transaction.

Throws:
java.lang.InterruptedException
DataAccessException

endTransaction

public void endTransaction()
                    throws java.lang.InterruptedException,
                           DataAccessException
This method is called after the startTransaction method and any number of setData calls. It terminates an SQLite transaction and does a rollback if any of the setData calls generated an SQL error.

Throws:
java.lang.InterruptedException
DataAccessException

sync

public void sync()
          throws org.apache.http.client.ClientProtocolException,
                 DataAccessException,
                 JSONException,
                 java.io.IOException,
                 java.lang.InterruptedException,
                 QCSynchronizationException
This method pushes any stored setData parameters to the HTTP service, waits for any data from the service, and then inserts any data received from the service into the appropriate tables in the local SQLite database.

Throws:
org.apache.http.client.ClientProtocolException
DataAccessException
JSONException
java.io.IOException
java.lang.InterruptedException
QCSynchronizationException

clearSync

public void clearSync()
               throws java.lang.InterruptedException,
                      DataAccessException,
                      JSONException
This is a method that should rarely, if ever, be used. It deletes all data previously stored for later synchronization.

Throws:
java.lang.InterruptedException
DataAccessException
JSONException

cleanUp

public void cleanUp()
             throws java.io.IOException
This method sends a logout command to the remote HTTP service and closes down the HTTP client on the Android device.

Throws:
java.io.IOException