com.readystatesoftware.sqliteasset

Class SQLiteAssetHelper

java.lang.Object

SQLiteOpenHelper

com.readystatesoftware.sqliteasset.SQLiteAssetHelper

public class SQLiteAssetHelper
extends SQLiteOpenHelper

A helper class to manage database creation and version management using an application's raw asset files. This class provides developers with a simple way to ship their Android app with an existing SQLite database (which may be pre-populated with data) and to manage its initial creation and any upgrades required with subsequent version releases.

This class makes it easy for android.content.ContentProvider implementations to defer opening and upgrading the database until first use, to avoid blocking application startup with long-running database upgrades.

For examples see https://github.com/jgilfelt/android-sqlite-asset-helper

Note: this class assumes monotonically increasing version numbers for upgrades. Also, there is no concept of a database downgrade; installing a new version of your app which uses a lower version number than a previously-installed version will result in undefined behavior.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SQLiteAssetHelper.SQLiteAssetException An exception that indicates there was an error with SQLite asset retrieval or parsing.

Constructor Summary

Constructors

Constructor and Description
SQLiteAssetHelper(Context context, java.lang.String name, CursorFactory factory, int version) Create a helper object to create, open, and/or manage a database in the application's default private data directory.
SQLiteAssetHelper(Context context, java.lang.String name, java.lang.String storageDirectory, CursorFactory factory, int version) Create a helper object to create, open, and/or manage a database in a specified location.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close any open database object.
SQLiteDatabase	getReadableDatabase() Create and/or open a database.
SQLiteDatabase	getWritableDatabase() Create and/or open a database that will be used for reading and writing.
void	onConfigure(SQLiteDatabase db)
void	onCreate(SQLiteDatabase db)
void	onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion)
void	onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion)
void	setForcedUpgrade() Bypass the upgrade process for every version increment and simply overwrite the existing database with the supplied asset file.
void	setForcedUpgrade(int version) Bypass the upgrade process (for each increment up to a given version) and simply overwrite the existing database with the supplied asset file.
void	setForcedUpgradeVersion(int version) Deprecated. use setForcedUpgrade(int) instead.

Methods inherited from class java.lang.Object

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

Constructor Detail

SQLiteAssetHelper

public SQLiteAssetHelper(Context context,
                 java.lang.String name,
                 java.lang.String storageDirectory,
                 CursorFactory factory,
                 int version)

Create a helper object to create, open, and/or manage a database in a specified location. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase() or getReadableDatabase() is called.

Parameters:

context - to use to open or create the database

name - of the database file

storageDirectory - to store the database file upon creation; caller must ensure that the specified absolute path is available and can be written to

factory - to use for creating cursor objects, or null for the default

version - number of the database (starting at 1); if the database is older, SQL file(s) contained within the application assets folder will be used to upgrade the database

SQLiteAssetHelper

public SQLiteAssetHelper(Context context,
                 java.lang.String name,
                 CursorFactory factory,
                 int version)

Create a helper object to create, open, and/or manage a database in the application's default private data directory. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase() or getReadableDatabase() is called.

Parameters:

context - to use to open or create the database

name - of the database file

factory - to use for creating cursor objects, or null for the default

version - number of the database (starting at 1); if the database is older, SQL file(s) contained within the application assets folder will be used to upgrade the database

Method Detail

getWritableDatabase

public SQLiteDatabase getWritableDatabase()

Create and/or open a database that will be used for reading and writing. The first time this is called, the database will be extracted and copied from the application's assets folder.

Once opened successfully, the database is cached, so you can call this method every time you need to write to the database. (Make sure to call close() when you no longer need the database.) Errors such as bad permissions or a full disk may cause this method to fail, but future attempts may succeed if the problem is fixed.

Database upgrade may take a long time, you should not call this method from the application main thread, including from ContentProvider.onCreate().

Returns:

a read/write database object valid until close() is called

Throws:

SQLiteException - if the database cannot be opened for writing

getReadableDatabase

public SQLiteDatabase getReadableDatabase()

Create and/or open a database. This will be the same object returned by getWritableDatabase() unless some problem, such as a full disk, requires the database to be opened read-only. In that case, a read-only database object will be returned. If the problem is fixed, a future call to getWritableDatabase() may succeed, in which case the read-only database object will be closed and the read/write object will be returned in the future.

Like getWritableDatabase(), this method may take a long time to return, so you should not call it from the application main thread, including from ContentProvider.onCreate().

Returns:

a database object valid until getWritableDatabase() or close() is called.

Throws:

SQLiteException - if the database cannot be opened

close

public void close()

Close any open database object.

onConfigure

public final void onConfigure(SQLiteDatabase db)

onCreate

public final void onCreate(SQLiteDatabase db)

onUpgrade

public void onUpgrade(SQLiteDatabase db,
             int oldVersion,
             int newVersion)

onDowngrade

public final void onDowngrade(SQLiteDatabase db,
               int oldVersion,
               int newVersion)

setForcedUpgradeVersion

@Deprecated
public void setForcedUpgradeVersion(int version)

Deprecated. use setForcedUpgrade(int) instead.

Bypass the upgrade process (for each increment up to a given version) and simply overwrite the existing database with the supplied asset file.

Parameters:

version - bypass upgrade up to this version number - should never be greater than the latest database version.

setForcedUpgrade

public void setForcedUpgrade(int version)

Bypass the upgrade process (for each increment up to a given version) and simply overwrite the existing database with the supplied asset file.

Parameters:

version - bypass upgrade up to this version number - should never be greater than the latest database version.

setForcedUpgrade

public void setForcedUpgrade()

Bypass the upgrade process for every version increment and simply overwrite the existing database with the supplied asset file.