net.zer0bandwidth.android.lib.database

Class SQLiteAssetPortal

java.lang.Object

android.database.sqlite.SQLiteOpenHelper

net.zer0bandwidth.android.lib.database.SQLitePortal

net.zer0bandwidth.android.lib.database.SQLiteAssetPortal

public abstract class SQLiteAssetPortal
extends SQLitePortal

Provides a SQLiteOpenHelper implementation which manages a read-only database that is loaded from an asset file.

See Using Your Own SQLite Database in Android Applications for the basis of this implementation.

Example

 public class MyDB extends SQLiteAssetPortal
 {
     protected static final String DB_NAME = "mydb" ;

     /**
      * Rather than using this to represent the version of the database
      * schema, use this constant to represent the version of the asset. Thus,
      * whenever new content is added to the asset, the app will know to
      * overwrite its database with the contents of the new asset. See the
      * example of onUpgrade() below.
      */
     protected static final int DB_VERSION = 2 ;

     /** Filename of the asset containing the static database instance.  */
     protected static final String DB_SOURCE_ASSET = "mydb.v2.db" ;

     public MyDB( Context ctx )
     { super( ctx, DB_NAME, null, DB_VERSION ) ; }

     @Override
     public abstract String getAssetName()
     { return DB_SOURCE_ASSET ; }
 }
 

Since:

zer0bandwidth-net/android 0.1.4 (#34)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	SQLiteAssetPortal.ConnectionTask Allows the SQLiteAssetPortal to create a persistent connection to its underlying database on a background thread.

Nested classes/interfaces inherited from class net.zer0bandwidth.android.lib.database.SQLitePortal

SQLitePortal.ConnectionListener

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	LOG_TAG
protected boolean	m_bNeedsCopy The only method in which the old and new schema versions are exposed is in onUpgrade(android.database.sqlite.SQLiteDatabase, int, int); thus, that method will set this indicator flag so that the consumer can then explicitly invoke copyFromAsset().

Fields inherited from class net.zer0bandwidth.android.lib.database.SQLitePortal

m_bIsConnected, m_bReadOnly, m_ctx, m_db, m_nLatestVersion, SQLITE_FALSE_INT, SQLITE_FALSE_INTSTRING, SQLITE_TRUE_INT, SQLITE_TRUE_INTSTRING, WHERE_FALSE, WHERE_TRUE

Constructor Summary

Constructors

Constructor and Description
SQLiteAssetPortal(android.content.Context ctx, java.lang.String sDatabaseName, android.database.sqlite.SQLiteDatabase.CursorFactory cf, int nVersion)

Method Summary

Modifier and Type	Method and Description
protected boolean	copyFromAsset() If indicated by the flag set during connection, this method overwrites the portal's database with the contents of a static asset packaged in the APK.
abstract java.lang.String	getAssetName() Descendant classes must implement this method to provide the name of the asset from which the database will be replicated.
void	onCreate(android.database.sqlite.SQLiteDatabase db) If the database did not previously exist, then we need to copy it from the asset.
void	onUpgrade(android.database.sqlite.SQLiteDatabase db, int nOld, int nNew) Copy the database asset only if an upgrade is needed.
SQLiteAssetPortal	openDB(boolean bReadOnly, SQLitePortal.ConnectionListener l) Forces the connection to be read-only, and uses the descendant version of SQLiteAssetPortal.ConnectionTask to open, and then copy, the database.

Methods inherited from class net.zer0bandwidth.android.lib.database.SQLitePortal

boolToInt, boolToIntString, close, closeCursor, closeDB, databaseExists, getBooleanColumn, getColumnListForTable, getColumnMapForTable, getContext, getDatabaseFileSize, getLatestSchemaVersion, getPathToDatabaseFile, intToBool, isConnected, openDB, openDB, openDB

Methods inherited from class android.database.sqlite.SQLiteOpenHelper

getDatabaseName, getReadableDatabase, getWritableDatabase, onConfigure, onDowngrade, onOpen, setIdleConnectionTimeout, setLookasideConfig, setWriteAheadLoggingEnabled

Methods inherited from class java.lang.Object

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

Field Detail

LOG_TAG

public static final java.lang.String LOG_TAG

m_bNeedsCopy

protected boolean m_bNeedsCopy

The only method in which the old and new schema versions are exposed is in onUpgrade(android.database.sqlite.SQLiteDatabase, int, int); thus, that method will set this indicator flag so that the consumer can then explicitly invoke copyFromAsset().

Constructor Detail

SQLiteAssetPortal

public SQLiteAssetPortal(android.content.Context ctx,
                         java.lang.String sDatabaseName,
                         android.database.sqlite.SQLiteDatabase.CursorFactory cf,
                         int nVersion)

Method Detail

onCreate

public final void onCreate(android.database.sqlite.SQLiteDatabase db)

If the database did not previously exist, then we need to copy it from the asset.

Note that, since SQLiteAssetPortal.ConnectionTask executes SQLiteOpenHelper.getReadableDatabase() twice, it is possible that this method will be called spuriously during the second invocation. However, since the task immediately resets m_bNeedsCopy to false after this, this has no negative consequence, other than the time wasted on the method call.

Specified by:

onCreate in class android.database.sqlite.SQLiteOpenHelper

onUpgrade

public final void onUpgrade(android.database.sqlite.SQLiteDatabase db,
                            int nOld,
                            int nNew)

Copy the database asset only if an upgrade is needed.

Specified by:

onUpgrade in class android.database.sqlite.SQLiteOpenHelper

openDB

public SQLiteAssetPortal openDB(boolean bReadOnly,
                                SQLitePortal.ConnectionListener l)

Forces the connection to be read-only, and uses the descendant version of SQLiteAssetPortal.ConnectionTask to open, and then copy, the database.

Overrides:

openDB in class SQLitePortal

Parameters:

bReadOnly - placebo - always overridden as true in this version of the method

l - the listener for the "on connected" callback

Returns:

(fluid)

getAssetName

public abstract java.lang.String getAssetName()

Descendant classes must implement this method to provide the name of the asset from which the database will be replicated.

Returns:

the name of the asset which will be copied as the app's database

copyFromAsset

protected boolean copyFromAsset()

If indicated by the flag set during connection, this method overwrites the portal's database with the contents of a static asset packaged in the APK.

Returns:

true if the asset was successfully copied; false otherwise