android.database.sqlite
Class SQLiteOpenHelper

java.lang.Object
  android.database.sqlite.SQLiteOpenHelper

public abstract class SQLiteOpenHelper
extends Object

A helper class to manage database creation and version management. You create a subclass implementing onCreate(android.database.sqlite.SQLiteDatabase), onUpgrade(android.database.sqlite.SQLiteDatabase, int, int) and optionally onOpen(android.database.sqlite.SQLiteDatabase), and this class takes care of opening the database if it exists, creating it if it does not, and upgrading it as necessary. Transactions are used to make sure the database is always in a sensible state.

See Also:

com.google.provider.NotePad.NotePadProvider

Constructor Summary

SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version)
Create a helper object to create, open, and/or manage a database.

Method Summary

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.
abstract void	onCreate(SQLiteDatabase db) Called when the database is created for the first time.
void	onOpen(SQLiteDatabase db) Called when the database has been opened.
abstract void	onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) Called when the database needs to be upgraded.

Methods inherited from class java.lang.Object

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

Constructor Detail

SQLiteOpenHelper

public SQLiteOpenHelper(Context context,
                        String name,
                        SQLiteDatabase.CursorFactory factory,
                        int version)

Create a helper object to create, open, and/or manage a database. 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, or null for an in-memory database

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, onUpgrade(android.database.sqlite.SQLiteDatabase, int, int) 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. 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 it.

Errors such as bad permissions or a full disk may cause this operation to fail, but future attempts may succeed if the problem is fixed.

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.

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.

onCreate

public abstract void onCreate(SQLiteDatabase db)

Called when the database is created for the first time. This is where the creation of tables and the initial population of the tables should happen.

Parameters:

db - The database.

onUpgrade

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

Called when the database needs to be upgraded. The implementation should use this method to drop tables, add tables, or do anything else it needs to upgrade to the new schema version.

The SQLite ALTER TABLE documentation can be found here. If you add new columns you can use ALTER TABLE to insert them into a live table. If you rename or remove columns you can use ALTER TABLE to rename the old table, then create the new table and then populate the new table with the contents of the old table.

Parameters:

db - The database.

oldVersion - The old database version.

newVersion - The new database version.

onOpen

public void onOpen(SQLiteDatabase db)

Called when the database has been opened. Override method should check SQLiteDatabase.isReadOnly() before updating the database.

Parameters:

db - The database.