org.quickconnectfamily.dbaccess
Class DataAccessObject

java.lang.Object
  extended by org.quickconnectfamily.dbaccess.DataAccessObject

public class DataAccessObject
extends java.lang.Object

The DataAccessObject class is a wrapper created to ease the use of SQLite databases available in Android Applications. It supports the use of multiple databases per application, database transactions, and all transactions, queries, insertions into the database, and modifications of existing data are thread safe.
To use this wrapper include an SQLite file in the assets directory of your Android application. To access this database call the DataAccessObject getData static method. To make database modifications use the DataAccesObject setData method. Both of these methods will do all of the preparatory setup required to use the database if it has not already been done.
Transactions are started and stopped using the DataAccessObject startTransaction and endTransaction methods. If the endTransaction method is passed false as the third parameter then a roll back of the changes done as part of the transaction will be executed.
If your database is not going to be used any longer you can use the DataAccessObject close method to free the resources. Only close databases if you will no longer be using them during the run of your application or you need to free resources for memory reasons.

Author:
Lee S. Barney

Method Summary
static void close(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName)
          This method is used to free up resources required to access a specific SQLite database file.
static void closeAll()
          This method is used to free up resources required to access all open SQLite database files.
static void endTransaction(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName, boolean successful)
          This method is used as the ending boundary of a database transaction.
static DataAccessResult getData(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName, java.lang.String SQL, java.lang.Object[] parameters)
          Deprecated. Replaced by #transact(Activity aContext, String databaseName, String SQL, Object[] parameters)
static DataAccessResult setData(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName, java.lang.String SQL, java.lang.Object[] parameters)
          Deprecated. Replaced by #transact(Activity aContext, String databaseName, String SQL, Object[] parameters)
static void startTransaction(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName)
          This method is used as the beginning boundary of a database transaction.
static DataAccessResult transact(java.lang.ref.WeakReference<android.content.Context> aContextRef, java.lang.String databaseName, java.lang.String SQL, java.lang.Object[] parameters)
          This method is used to execute standard select, insert, update, etc.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getData

public static DataAccessResult getData(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                                       java.lang.String databaseName,
                                       java.lang.String SQL,
                                       java.lang.Object[] parameters)
                                throws DataAccessException
Deprecated. Replaced by #transact(Activity aContext, String databaseName, String SQL, Object[] parameters)

This method is used to execute standard SQL query statements and matching prepared statements against any SQLite database file included in the assets directory of an Android application.

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
SQL - - An SQL string for a standard SQL statement or a prepared statement used to query the database
parameters - - An array of Objects to be bound to the ? characters in the SQL string if it is a prepared statement. If the SQL string is not to be used for a prepared statement this parameter should be null.
Returns:
- A DataAccessResult object that contains information regarding any database errors generated during execution, the data found as a result of the query, and other helpful pieces of information.
Throws:
DataAccessException

setData

public static DataAccessResult setData(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                                       java.lang.String databaseName,
                                       java.lang.String SQL,
                                       java.lang.Object[] parameters)
                                throws DataAccessException
Deprecated. Replaced by #transact(Activity aContext, String databaseName, String SQL, Object[] parameters)

This method is used to execute standard insert, update, etc. SQL statements and matching prepared statements against any SQLite database file included in the assets directory of an Android application.

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
SQL - - An SQL string for a standard SQL statement or a prepared statement used to query the database
parameters - - An array of Objects to be bound to the ? characters in the SQL string if it is a prepared statement. If the SQL string is not to be used for a prepared statement this parameter should be null.
Returns:
- A DataAccessResult object that contains information regarding any database errors generated during execution and other helpful pieces of information.
Throws:
DataAccessException

transact

public static DataAccessResult transact(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                                        java.lang.String databaseName,
                                        java.lang.String SQL,
                                        java.lang.Object[] parameters)
                                 throws DataAccessException
This method is used to execute standard select, insert, update, etc. SQL statements and matching prepared statements against any SQLite database file included in the assets directory of an Android application.

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
SQL - - An SQL string for a standard SQL statement or a prepared statement used to query the database
parameters - - An array of Objects to be bound to the ? characters in the SQL string if it is a prepared statement. If the SQL string is not to be used for a prepared statement this parameter should be null.
Returns:
- A DataAccessResult object that contains information regarding any database errors generated during execution and other helpful pieces of information.
Throws:
DataAccessException

startTransaction

public static void startTransaction(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                                    java.lang.String databaseName)
                             throws DataAccessException
This method is used as the beginning boundary of a database transaction. After this call then any calls to setData or getData will be executed as part of a transaction

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
Throws:
DataAccessException

endTransaction

public static void endTransaction(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                                  java.lang.String databaseName,
                                  boolean successful)
                           throws DataAccessException
This method is used as the ending boundary of a database transaction. Any setData or getData calls made after the startTransaction method and before a call to this method are treated in such a way that they can be rolled back.

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
successful - - a boolean value indicating if a roll back of all statements in the transaction should be done. A value of true causes a roll back, false does not.
Throws:
DataAccessException

close

public static void close(java.lang.ref.WeakReference<android.content.Context> aContextRef,
                         java.lang.String databaseName)
                  throws DataAccessException
This method is used to free up resources required to access a specific SQLite database file. This method should be used sparingly. Do NOT close a database after each use and then reopen it again using a getData or setData call unless you must for memory reasons since this will slow down the execution of your application.

Parameters:
aContext - - The Activity object with which the database is associated. This is usually the main, or first, Activity of the application.
databaseName - - A string that matches the name of the SQLite file included in the assets directory of the Android application.
Throws:
DataAccessException

closeAll

public static void closeAll()
This method is used to free up resources required to access all open SQLite database files. This method should be used sparingly. Do NOT close a databases after each use and then reopen them again using a getData or setData call unless you must for memory reasons since this will slow down the execution of your application.