SQLiteOpenHelperpublic abstract class SQLiteOpenHelper extends Object | A helper class to manage database creation and version management.
You create a subclass implementing {@link #onCreate}, {@link #onUpgrade} and
optionally {@link #onOpen}, 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.
This class makes it easy for {@link 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 an example, see the NotePadProvider class in the NotePad sample application,
in the samples/ directory of the SDK.
Note: this class assumes
monotonically increasing version numbers for upgrades. |
| Fields Summary |
|---|
| private static final String | TAG | | private static final boolean | DEBUG_STRICT_READONLY | | private final android.content.Context | mContext | | private final String | mName | | private final android.database.sqlite.SQLiteDatabase.CursorFactory | mFactory | | private final int | mNewVersion | | private SQLiteDatabase | mDatabase | | private boolean | mIsInitializing | | private boolean | mEnableWriteAheadLogging | | private final android.database.DatabaseErrorHandler | mErrorHandler |
| Constructors Summary |
|---|
public SQLiteOpenHelper(android.content.Context context, String name, android.database.sqlite.SQLiteDatabase.CursorFactory factory, int version)Create a helper object to create, open, and/or manage a database.
This method always returns very quickly. The database is not actually
created or opened until one of {@link #getWritableDatabase} or
{@link #getReadableDatabase} is called.
this(context, name, factory, version, null);
| public SQLiteOpenHelper(android.content.Context context, String name, android.database.sqlite.SQLiteDatabase.CursorFactory factory, int version, android.database.DatabaseErrorHandler errorHandler)Create a helper object to create, open, and/or manage a database.
The database is not actually created or opened until one of
{@link #getWritableDatabase} or {@link #getReadableDatabase} is called.
Accepts input param: a concrete instance of {@link DatabaseErrorHandler} to be
used to handle corruption when sqlite reports database corruption.
if (version < 1) throw new IllegalArgumentException("Version must be >= 1, was " + version);
mContext = context;
mName = name;
mFactory = factory;
mNewVersion = version;
mErrorHandler = errorHandler;
|
| Methods Summary |
|---|
| public synchronized void | close()Close any open database object.
if (mIsInitializing) throw new IllegalStateException("Closed during initialization");
if (mDatabase != null && mDatabase.isOpen()) {
mDatabase.close();
mDatabase = null;
}
| | private SQLiteDatabase | getDatabaseLocked(boolean writable)
if (mDatabase != null) {
if (!mDatabase.isOpen()) {
// Darn! The user closed the database by calling mDatabase.close().
mDatabase = null;
} else if (!writable || !mDatabase.isReadOnly()) {
// The database is already open for business.
return mDatabase;
}
}
if (mIsInitializing) {
throw new IllegalStateException("getDatabase called recursively");
}
SQLiteDatabase db = mDatabase;
try {
mIsInitializing = true;
if (db != null) {
if (writable && db.isReadOnly()) {
db.reopenReadWrite();
}
} else if (mName == null) {
db = SQLiteDatabase.create(null);
} else {
try {
if (DEBUG_STRICT_READONLY && !writable) {
final String path = mContext.getDatabasePath(mName).getPath();
db = SQLiteDatabase.openDatabase(path, mFactory,
SQLiteDatabase.OPEN_READONLY, mErrorHandler);
} else {
db = mContext.openOrCreateDatabase(mName, mEnableWriteAheadLogging ?
Context.MODE_ENABLE_WRITE_AHEAD_LOGGING : 0,
mFactory, mErrorHandler);
}
} catch (SQLiteException ex) {
if (writable) {
throw ex;
}
Log.e(TAG, "Couldn't open " + mName
+ " for writing (will try read-only):", ex);
final String path = mContext.getDatabasePath(mName).getPath();
db = SQLiteDatabase.openDatabase(path, mFactory,
SQLiteDatabase.OPEN_READONLY, mErrorHandler);
}
}
onConfigure(db);
final int version = db.getVersion();
if (version != mNewVersion) {
if (db.isReadOnly()) {
throw new SQLiteException("Can't upgrade read-only database from version " +
db.getVersion() + " to " + mNewVersion + ": " + mName);
}
db.beginTransaction();
try {
if (version == 0) {
onCreate(db);
} else {
if (version > mNewVersion) {
onDowngrade(db, version, mNewVersion);
} else {
onUpgrade(db, version, mNewVersion);
}
}
db.setVersion(mNewVersion);
db.setTransactionSuccessful();
} finally {
db.endTransaction();
}
}
onOpen(db);
if (db.isReadOnly()) {
Log.w(TAG, "Opened " + mName + " in read-only mode");
}
mDatabase = db;
return db;
} finally {
mIsInitializing = false;
if (db != null && db != mDatabase) {
db.close();
}
}
| | public java.lang.String | getDatabaseName()Return the name of the SQLite database being opened, as given to
the constructor.
return mName;
| | public SQLiteDatabase | getReadableDatabase()Create and/or open a database. This will be the same object returned by
{@link #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 {@link #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 {@link #getWritableDatabase}, this method may
take a long time to return, so you should not call it from the
application main thread, including from
{@link android.content.ContentProvider#onCreate ContentProvider.onCreate()}.
synchronized (this) {
return getDatabaseLocked(false);
}
| | 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 opened and
{@link #onCreate}, {@link #onUpgrade} and/or {@link #onOpen} will be
called.
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 {@link #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 {@link android.content.ContentProvider#onCreate ContentProvider.onCreate()}.
synchronized (this) {
return getDatabaseLocked(true);
}
| | public void | onConfigure(SQLiteDatabase db)Called when the database connection is being configured, to enable features
such as write-ahead logging or foreign key support.
This method is called before {@link #onCreate}, {@link #onUpgrade},
{@link #onDowngrade}, or {@link #onOpen} are called. It should not modify
the database except to configure the database connection as required.
This method should only call methods that configure the parameters of the
database connection, such as {@link SQLiteDatabase#enableWriteAheadLogging}
{@link SQLiteDatabase#setForeignKeyConstraintsEnabled},
{@link SQLiteDatabase#setLocale}, {@link SQLiteDatabase#setMaximumSize},
or executing PRAGMA statements.
| | 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.
| | public void | onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion)Called when the database needs to be downgraded. This is strictly similar to
{@link #onUpgrade} method, but is called whenever current version is newer than requested one.
However, this method is not abstract, so it is not mandatory for a customer to
implement it. If not overridden, default implementation will reject downgrade and
throws SQLiteException
This method executes within a transaction. If an exception is thrown, all changes
will automatically be rolled back.
throw new SQLiteException("Can't downgrade database from version " +
oldVersion + " to " + newVersion);
| | public void | onOpen(SQLiteDatabase db)Called when the database has been opened. The implementation
should check {@link SQLiteDatabase#isReadOnly} before updating the
database.
This method is called after the database connection has been configured
and after the database schema has been created, upgraded or downgraded as necessary.
If the database connection must be configured in some way before the schema
is created, upgraded, or downgraded, do it in {@link #onConfigure} instead.
| | 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.
This method executes within a transaction. If an exception is thrown, all changes
will automatically be rolled back.
| | public void | setWriteAheadLoggingEnabled(boolean enabled)Enables or disables the use of write-ahead logging for the database.
Write-ahead logging cannot be used with read-only databases so the value of
this flag is ignored if the database is opened read-only.
synchronized (this) {
if (mEnableWriteAheadLogging != enabled) {
if (mDatabase != null && mDatabase.isOpen() && !mDatabase.isReadOnly()) {
if (enabled) {
mDatabase.enableWriteAheadLogging();
} else {
mDatabase.disableWriteAheadLogging();
}
}
mEnableWriteAheadLogging = enabled;
}
}
|
|
