使用注意事項(xiàng)：
- getWritableDatabase() 不要放在 UI 線程，存在阻塞和操作耗時(shí)的情況;
- getReadableDatabase() 優(yōu)先返回 getWritableDatabase(), 發(fā)生 SQLiteException 異常后，才嘗試獲取只讀模式的數(shù)據(jù)庫(kù)
- getReadableDatabase() 由于調(diào)用了 getWritableDatabase(), 同樣不能放在 UI 線程
一、構(gòu)造方法
/**
* 該方法會(huì)快速返回，并不會(huì)創(chuàng)建或打開(kāi)數(shù)據(jù)庫(kù)
*
* 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.
*
* @param context to use to open or create the database
* @param name of the database file, or null for an in-memory database
* @param factory to use for creating cursor objects, or null for the default
* @param version number of the database (starting at 1); if the database is older,
* {@link #onUpgrade} will be used to upgrade the database; if the database is
* newer, {@link #onDowngrade} will be used to downgrade the database
*/
public SQLiteOpenHelper(Context context, String name, CursorFactory factory, int version) {
this(context, name, factory, version, new DefaultDatabaseErrorHandler());
}
public SQLiteOpenHelper(Context context, String name, CursorFactory factory, int version,
DatabaseErrorHandler errorHandler) {
if (version < 1) throw new IllegalArgumentException("Version must be >= 1, was " + version);
if (errorHandler == null) {
throw new IllegalArgumentException("DatabaseErrorHandler param value can't be null.");
}
mContext = context;
mName = name;
mFactory = factory;
mNewVersion = version;
mErrorHandler = errorHandler;
}
二、getWritableDatabase()
/**
* 第一次調(diào)用該方法時(shí)，將會(huì)打開(kāi)數(shù)據(jù)庫(kù)，并會(huì)視情況調(diào)用 onCreate(), onUpgrade(), onDowngrade(), onOpen()
*
* 該方法的調(diào)用不要放在 UI 線程，存在阻塞和操作耗時(shí)的情況
*
* 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.
*
* <p>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.</p>
*
* <p class="caution">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()}.
*
* @throws SQLiteException if the database cannot be opened for writing
* @return a read/write database object valid until {@link #close} is called
*/
public synchronized SQLiteDatabase getWritableDatabase() {
if (mDatabase != null) {
if (!mDatabase.isOpen()) {
// 若是 mDatabase 已被關(guān)閉，則置空, 重新獲取
// darn! the user closed the database by calling mDatabase.close()
mDatabase = null;
} else if (!mDatabase.isReadOnly()) {
// mDatabase 已滿足條件，直接返回
// The database is already open for business
return mDatabase;
}
}
if (mIsInitializing) {
// 該方法不允許被遞歸調(diào)用
throw new IllegalStateException("getWritableDatabase called recursively");
}
// If we have a read-only database open, someone could be using it
// (though they shouldn't), which would cause a lock to be held on
// the file, and our attempts to open the database read-write would
// fail waiting for the file lock. To prevent that, we acquire the
// lock on the read-only database, which shuts out other users.
boolean success = false;
SQLiteDatabase db = null;
if (mDatabase != null){
/**
* 應(yīng)對(duì)之前獲取的是只讀數(shù)據(jù)庫(kù)的情況
* 等待該線程獲取到鎖對(duì)象后返回，此處可能造成阻塞
*/
mDatabase.lock();
}
try {
mIsInitializing = true;
if (mName == null) {
db = SQLiteDatabase.create(null);
} else {
/**
* 層層跟進(jìn)，最終:
* db = new SQLiteDatabase(path, factory, flags, errorHandler, connectionNum)
* 注意此處的 mode:0 == SQLiteDatabase.OPEN_READWRITE, 即可讀寫模式
*/
db = mContext.openOrCreateDatabase(mName, 0, mFactory, mErrorHandler);
}
int version = db.getVersion();
if (version != mNewVersion) {
db.beginTransaction();
try {
if (version == 0) {
/**
* 數(shù)據(jù)庫(kù)不存在時(shí)才會(huì)調(diào)用 onCreate()
* 由子類實(shí)現(xiàn)數(shù)據(jù)庫(kù)的創(chuàng)建
*/
onCreate(db);
} else {
if (version > mNewVersion) {
// 需要注意降版本的情況，該方法的默認(rèn)實(shí)現(xiàn)是拋出異常
onDowngrade(db, version, mNewVersion);
} else {
// 由子類實(shí)現(xiàn)升級(jí)數(shù)據(jù)庫(kù)版本
onUpgrade(db, version, mNewVersion);
}
}
db.setVersion(mNewVersion);
db.setTransactionSuccessful();
} finally {
db.endTransaction();
}
}
// onOpen 為空實(shí)現(xiàn)
onOpen(db);
success = true;
return db;
} finally {
// 注意此處對(duì) try 語(yǔ)句的用法，只有 finally 語(yǔ)句塊，沒(méi)有 catch 語(yǔ)句塊
mIsInitializing = false;
if (success) {
/**
* 成功獲取到可讀寫的數(shù)據(jù)庫(kù)
*/
if (mDatabase != null) {
try { mDatabase.close(); } catch (Exception e) { }
mDatabase.unlock();
}
// 注意此處，把獲取到的可讀寫數(shù)據(jù)庫(kù)賦值給 mDatabase
mDatabase = db;
} else {
if (mDatabase != null){
mDatabase.unlock();
}
if (db != null) db.close();
}
}
}
三、getReadableDatabase()
/**
* 該方法的調(diào)用不要放在 UI 線程，存在阻塞和操作耗時(shí)的情況
* 優(yōu)先返回 getWritableDatabase()
* getWritableDatabase() 發(fā)生 SQLiteException 異常后，才嘗試獲取只讀模式的數(shù)據(jù)庫(kù)
*
* 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.
*
* <p class="caution">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()}.
*
* @throws SQLiteException if the database cannot be opened
* @return a database object valid until {@link #getWritableDatabase}
* or {@link #close} is called.
*/
public synchronized SQLiteDatabase getReadableDatabase() {
if (mDatabase != null) {
if (!mDatabase.isOpen()) {
// darn! the user closed the database by calling mDatabase.close()
// 若是 mDatabase 已被關(guān)閉，則置空, 重新獲取
mDatabase = null;
} else {
// 如果 mDatabase 未被 close()，則直接返回
return mDatabase; // The database is already open for business
}
}
if (mIsInitializing) {
throw new IllegalStateException("getReadableDatabase called recursively");
}
try {
// 注意此處，優(yōu)先獲取可讀寫的數(shù)據(jù)庫(kù)
return getWritableDatabase();
} catch (SQLiteException e) {
if (mName == null) throw e; // Can't open a temp database read-only!
Log.e(TAG, "Couldn't open " + mName + " for writing (will try read-only):", e);
}
SQLiteDatabase db = null;
try {
mIsInitializing = true;
String path = mContext.getDatabasePath(mName).getPath();
/**
* 層層跟進(jìn)，最終:
* db = new SQLiteDatabase(path, factory, flags, errorHandler, connectionNum)
* 注意此處的 SQLiteDatabase.OPEN_READONLY, 即只讀模式
*/
db = SQLiteDatabase.openDatabase(path, mFactory, SQLiteDatabase.OPEN_READONLY, mErrorHandler);
if (db.getVersion() != mNewVersion) {
throw new SQLiteException("Can't upgrade read-only database from version " +
db.getVersion() + " to " + mNewVersion + ": " + path);
}
// 該方法為空實(shí)現(xiàn)
onOpen(db);
Log.w(TAG, "Opened " + mName + " in read-only mode");
mDatabase = db;
return mDatabase;
} finally {
mIsInitializing = false;
if (db != null && db != mDatabase){
db.close();
}
}
}
