android.lib.database

Class Database

java.lang.Object

android.lib.database.Database

public class Database
extends java.lang.Object

Provides database abstraction layer APIs to handle SQLite operations: SELECT, UPDATE, INSERT, DELETE.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Database(android.content.Context context, java.lang.Class<?>... tables) Creates a new instance of Database with the given context.
protected	Database(android.content.Context context, int version, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, version.
protected	Database(android.content.Context context, java.lang.String name, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, name.
protected	Database(android.content.Context context, java.lang.String name, int version, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, name, version.
protected	Database(android.database.sqlite.SQLiteDatabase database)

Method Summary

Methods

Modifier and Type	Method and Description
void	beginTransaction() Starts a new transaction.
void	close() Closes the database, and abort any uncommitted changes.
void	commit() Persists any uncommitted changes to the database.
static void	createTables(android.content.Context context, java.lang.Class<?>... tables) Creates database tables/columns/indices.
<T> void	deleteById(java.lang.Class<T> table, java.lang.String idColumn, int idValue) Execute SQL DELETE statement against the database and deletes any rows with the matching id value.
void	execute(Query query) Executes a Query of type Update, Insert or Delete against the database.
<T> java.util.List<T>	execute(Query query, RowMapper<T> mapper) Executes a Query of type Select against the database and returns a list of object of type T using the given RowMapper.
<T> void	insert(T row) Executes SQL INSERT statement against the database.
static Database	newInstance(android.content.Context context, java.lang.Class<?>... tables) Creates a new instance of Database with the given context.
static Database	newInstance(android.content.Context context, int version, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, version.
static Database	newInstance(android.content.Context context, java.lang.String name, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, name.
static Database	newInstance(android.content.Context context, java.lang.String name, int version, java.lang.Class<?>... tables) Creates a new instance of Database with the given context, name, version.
void	rollback() Rolls back any uncommitted changes of the database.
<T> T	selectById(java.lang.Class<T> table, java.lang.String idColumn, int idValue) Execute SQL SELECT statement against the database and returns the row matching the given id, or null if there is no matching row.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Database

protected Database(android.database.sqlite.SQLiteDatabase database)

Database

protected Database(android.content.Context context,
        java.lang.String name,
        int version,
        java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, name, version.

Parameters:

context - the context to use to open or create the database.

name - the file name of the database file, or null for an in-memory database.

version - the version number of the database (starting at 1); if the database is older, DatabaseOpenHelper.onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database; if the database is newer, SQLiteOpenHelper.onDowngrade(SQLiteDatabase, int, int) will be used to downgrade the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

Database

protected Database(android.content.Context context,
        java.lang.String name,
        java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, name.

Parameters:

context - the context to use to open or create the database.

name - the file name of the database file, or null for an in-memory database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

Database

protected Database(android.content.Context context,
        int version,
        java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, version.

Parameters:

context - the context to use to open or create the database.

version - the version number of the database (starting at 1); if the database is older, DatabaseOpenHelper.onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database; if the database is newer, SQLiteOpenHelper.onDowngrade(SQLiteDatabase, int, int) will be used to downgrade the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

Database

protected Database(android.content.Context context,
        java.lang.Class<?>... tables)

Creates a new instance of Database with the given context.

Parameters:

context - the context to use to open or create the database. DatabaseOpenHelper.onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database; if the database is newer, SQLiteOpenHelper.onDowngrade(SQLiteDatabase, int, int) will be used to downgrade the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

Method Detail

newInstance

public static Database newInstance(android.content.Context context,
                   java.lang.String name,
                   int version,
                   java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, name, version.

Parameters:

context - the context to use to open or create the database.

name - the file name of the database file, or null for an in-memory database.

version - the version number of the database (starting at 1); if the database is older, DatabaseOpenHelper.onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database; if the database is newer, SQLiteOpenHelper.onDowngrade(SQLiteDatabase, int, int) will be used to downgrade the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

newInstance

public static Database newInstance(android.content.Context context,
                   java.lang.String name,
                   java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, name.

Parameters:

context - the context to use to open or create the database

name - the file name of the database file, or null for an in-memory database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

newInstance

public static Database newInstance(android.content.Context context,
                   int version,
                   java.lang.Class<?>... tables)

Creates a new instance of Database with the given context, version.

Parameters:

context - the context to use to open or create the database.

version - the version number of the database (starting at 1); if the database is older, DatabaseOpenHelper.onUpgrade(SQLiteDatabase, int, int) will be used to upgrade the database; if the database is newer, SQLiteOpenHelper.onDowngrade(SQLiteDatabase, int, int) will be used to downgrade the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

newInstance

public static Database newInstance(android.content.Context context,
                   java.lang.Class<?>... tables)

Creates a new instance of Database with the given context.

Parameters:

context - the context to use to open or create the database.

tables - the tables of the database to create in when the application runs for the first time. For subsequent call, tables can be null.

createTables

public static void createTables(android.content.Context context,
                java.lang.Class<?>... tables)

Creates database tables/columns/indices.

Call this method on application first-run after installation.

This method should be called once per application installation.

Parameters:

context - the context to use to open the database.

tables - the tables of the database to create.

close

public void close()

Closes the database, and abort any uncommitted changes.

This is a no-op if the database has already been closed before.

commit

public void commit()

Persists any uncommitted changes to the database.

The current transaction, if any, will be closed when this method returns. If necessary, call beginTransaction() to start a new transaction.

This is no-op if there is no uncommitted changes

Throws:

java.lang.IllegalStateException - if the database has been closed.

rollback

public void rollback()

Rolls back any uncommitted changes of the database.

The current transaction, if any, will be closed when this method returns. If necessary, call beginTransaction() to start a new transaction.

This is a no-op if there is no uncommitted changes.

Throws:

java.lang.IllegalStateException - if the database has been closed.

beginTransaction

public void beginTransaction()

Starts a new transaction.

If a transaction has already been started and not closed yet, a nested transaction will be started.

Throws:

java.lang.IllegalStateException - if the database has been closed.

execute

public <T> java.util.List<T> execute(Query query,
                            RowMapper<T> mapper)
                          throws java.lang.IllegalAccessException,
                                 java.lang.InstantiationException,
                                 UnsupportedTypeException,
                                 android.database.SQLException

Executes a Query of type Select against the database and returns a list of object of type T using the given RowMapper.

Type Parameters:

T - the type of the table object to cast the result set to.

Parameters:

query - the Query object containing the raw SQL statement to be executed.

mapper - the mapper to map Cursor to T.

Returns:

the result set returned from the query execution.

Throws:

java.lang.IllegalArgumentException - if the column name is not found from the resulting cursor.

UnsupportedTypeException - if the type T contains fields of unsupported types.

java.lang.IllegalAccessException - if the if the default constructor of T is not visible, or the default constructor of the TypeConverter associated with any field of T is not visible.

java.lang.InstantiationException - if the instance of T can not be created, or the instance of the TypeConverter associated with any field of T can not be created.

android.database.SQLException - if the SQL string is invalid.

selectById

public <T> T selectById(java.lang.Class<T> table,
               java.lang.String idColumn,
               int idValue)
             throws java.lang.IllegalAccessException,
                    java.lang.InstantiationException,
                    UnsupportedTypeException,
                    android.database.SQLException

Execute SQL SELECT statement against the database and returns the row matching the given id, or null if there is no matching row.

Parameters:

table - the table containing the data to retrieve from.

idColumn - the name of the id column.

idValue - an unique value to match the id column of a row.

Returns:

the result set returned from the query execution, or null if there is no matching row.

Throws:

java.lang.IllegalArgumentException - if the column name is not found from the resulting cursor.

UnsupportedTypeException - if the type T contains fields of unsupported types.

java.lang.IllegalAccessException - if the if the default constructor of T is not visible, or the default constructor of the TypeConverter associated with any field of T is not visible.

java.lang.InstantiationException - if the instance of T can not be created, or the instance of the TypeConverter associated with any field of T can not be created.

android.database.SQLException - if the SQL string is invalid.

insert

public <T> void insert(T row)
            throws java.lang.IllegalAccessException,
                   java.lang.InstantiationException,
                   UnsupportedTypeException,
                   android.database.SQLException

Executes SQL INSERT statement against the database.

Parameters:

row - the data to insert into the database.

Throws:

UnsupportedTypeException - if the type T contains fields of unsupported types.

java.lang.IllegalAccessException - if the if the default constructor of T is not visible, or the default constructor of the TypeConverter associated with any field of T is not visible.

java.lang.InstantiationException - if the instance of T can not be created, or the instance of the TypeConverter associated with any field of T can not be created.

android.database.SQLException - if the SQL string is invalid.

deleteById

public <T> void deleteById(java.lang.Class<T> table,
                  java.lang.String idColumn,
                  int idValue)
                throws android.database.SQLException

Execute SQL DELETE statement against the database and deletes any rows with the matching id value.

Parameters:

table - the table to delete rows from.

idColumn - the name of the id column.

idValue - an unique value to match the id column of a row.

Throws:

android.database.SQLException - if the SQL string is invalid .

execute

public void execute(Query query)
             throws android.database.SQLException

Executes a Query of type Update, Insert or Delete against the database.

Parameters:

query - the Query object to execute.

Throws:

android.database.SQLException - if the SQL string is invalid .