Android類參考—SQLiteOpenHelper

public 抽象類別

SQLiteOpenHelper

繼承關係

java.lang.Object

   |____android.database.sqlite.SQLiteOpenHelper

類概要

這是一個輔助類，用來管理資料庫的建立和資料庫的版本。

你要建立一個這個類的子類來實現onCreate(SQLiteDatabase)，onUpgrade(SQLiteDatabase,int,int)方法，以及可選的onOpen(SQLiteDatabase)方法，並且這個類要管理資料庫的狀態，如果資料庫存在，就開啟資料庫，否則就建立資料庫，並且在需要的時候也會更新資料庫。使用事務來確保資料庫始終在正確的狀態中。

這個類讓ContentProvider的實現變的容易，它把資料庫的開啟和升級延遲到第一次使用，從而避免了因升級資料庫的長時間運行而造成的應用程式阻塞。

注意：這個類假設用遞增的版本號碼來升級。

Public構造器

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

   建立一個輔助對象，用來建立、開啟、管理資料庫。這個方法始終是快速返回的。在getWriteableDatabase()或getReadableDatabase()方法被調用之前，這個資料庫不會實際的被建立。

   參數說明：

   context：用於開啟或建立資料庫；

   name：指定資料庫的檔案名稱，null指定一個記憶體中的資料庫

   factory：用於建立遊標對象，或預設的null；

   version：指定資料庫的版本號碼（從1開始）；如果資料庫比較舊，onUpgrade(SQLiteDatabase, int, int)方法將用於升級資料庫。如果資料庫比較新，onDowngrade(SQLiteDatabase, int, int)方法會被用於降級資料庫。

 

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

   建立一個輔助對象，用來建立、開啟、管理資料庫。這個方法始終是快速返回的。在getWriteableDatabase()或getReadableDatabase()方法被調用之前，這個資料庫不會實際的被建立。

   接收輸入參數：一個具體的DatabaseErrorHandler樣本，用於處理SQLite報告的資料庫錯誤。

   參數說明：

   context：用於開啟或建立資料庫；

   name：指定資料庫的檔案名稱，null指定一個記憶體中的資料庫

   factory：用於建立遊標對象，或預設的null；

   version：指定資料庫的版本號碼（從1開始）；如果資料庫比較舊，onUpgrade(SQLiteDatabase, int, int)方法將用於升級資料庫。如果資料庫比較新，onDowngrade(SQLiteDatabase, int, int)方法會被用於降級資料庫。

   errorHandler：該參數被用於SQLite報告資料庫錯誤，或者是null，使用預設錯誤處理器。

 

Public方法

public synchronized void close()

關閉開啟的資料庫物件。

 

public String getDatabaseName()

返回由構造器傳遞進來的，正在開啟的SQLite資料的名稱。

 

public SQLiteDatabase getReadableDatabase()

建立並（或）開啟一個資料庫，除非因為某些問題，否則這個方法返回的對象會與getWritableDatabase()方法相同，如在磁碟空間不足的情況下，就會要求資料庫以唯讀方式被開啟，在這種情況下，會返回一個唯讀資料庫。如果問題被修正，繼續調用getWritableDatabase()方法也可以成功，這時唯讀資料庫物件會被關閉，並且會返回一個讀寫對象。

getWritableDatabase()方法可能需要很長時間才能返回，因此不應該在應用程式的主線程中調用它，包括ContentProvider.onCreate()方法。

傳回值：返回一個資料庫物件，直到getWritableDatabase()或close()方法被調用之前，這個對象都是有效。

異常：如果資料不能夠被開啟，會拋出SQLiteException異常。

 

public SQLiteDatabase getWritableDatabase()

建立並（或）開啟一個用於讀寫的資料庫。如果是首次調用這個方法，那麼該資料將會被開啟，並且onCreate(SQLiteDatabase)，onUpgrade(SQLiteDatabase, int, int)和（或）onOpen(SQLiteDatabase)方法會被調用。

資料庫一旦被開啟，該資料庫就會被緩衝，因此在每次需要寫資料庫時，你都能夠調用這個方法。（在不在需要該資料庫時，要確保調用close()方法）。諸如沒有授權或沒有磁碟空間等錯誤可能會導致這個方法調用失敗，但如果這些問題被修正，這個方法就會被調用成功。

注意：資料庫升級可能需要很長時間，因此不要在應用程式的主線程中調用這個方法，包括ContentProvider.onCreate()。

傳回值：一個讀寫的資料庫物件，直到close()方法被調用才失效。

異常：如果該資料庫不能為寫入而開啟，就會拋出SQLiteException異常。

 

public void onConfigure()

在配置資料連線時會調用這個方法，確保預寫記錄檔或外鍵支援等功能可用。

這個方法在onCreate(SQLiteDatabase)，onUpgrade(SQLiteDatabase, int, int)，onDowngrade(SQLiteDatabase, int, int)或onOpen(SQLiteDatabase)方法被調用之前被調用。除了配置必要的資料庫連接之外，它不應該編輯資料庫。

這個方法只應該調用設定資料庫串連參數的方法，如enableWriteAheadLogging()，setForeignKeyConstraintsEnabled(boolean)，setLocale(Locale)，setMaximumSize(long)，或者執行PRAGMA語句。

參數：

db：被配置的資料庫物件

 

public abstract void onCreate(SQLiteDatabase db)

資料庫被首次建立時，會調用這個方法。這時建立資料庫表和表初始化的地方。

參數：

db：要建立的資料庫。

 

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

當資料庫需要被降級時，調用這個方法。這個方法與onUpgrade(SQLiteDatabase, int, int)方法非常相似，但是它是在目前的版本比請求的版本新的時候，才會被調用。但是這個方法不是抽象的，因此它不是強制要求客戶實現它的。如果這個方法沒有被重寫，預設的實現會拒絕降級處理，並拋出SQLiteException異常。

這個方法是在事務中執行的。如果有異常被拋出，所有的改變都會被復原。

參數：

db：指定要降級的資料庫

oldVersion：舊的資料庫版本

newVersion：新的資料庫版本

 

public void onOpen(SQLiteDatabase db)

資料庫被開啟時，會調用這個方法。在升級資料庫之前，這個方法的實現應該檢查資料庫是否是唯讀（調用isReadOnly()方法）。

資料庫連接被配置且資料庫策略被建立、升級或必要的降級之後，這個方法會被調用。如果資料庫連接必須在策略被建立、升級或降級前做某些設定，那麼就要在onConfigure(SQLiteDatabase)方法中來做這些事情。

參數：

db：被開啟的資料庫。

 

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

當資料庫需要升級時，會調用這個方法。應該使用這個方法來實現刪除表、添加表或者做一些需要升級新的策略版本的事情。

SQLite ALTER TABLE的文檔可以在以下網址中找到：

http://sqlite.org/lang_altertable.html

如果要給表添加一個新列，那麼使用使用ALTER TABLE能夠把新列插入到表中。如果要重新命名或刪除列，那麼你能夠使用ALTER TABLE能夠重新命名舊錶，然後，建立一個新表，並把舊錶中內容複寫到新表中。

這個方法是事務中執行的，如果有異常被拋出，所有的改變都會被自動的復原。

參數：

db：指定要降級的資料庫

oldVersion：舊的資料庫版本

newVersion：新的資料庫版本

 

public void setWriteAheadLoggingEnabled(boolean enabled)

啟用或禁用資料庫的預寫記錄檔。預寫記錄檔不能被用於唯讀資料庫，因此如果資料是以唯讀方式被開啟，這個標記值會被忽略。

參數：

enabled：true：啟用預寫記錄檔，false：禁用預寫記錄檔

參照：enableWriteAheadLogging()方法。

http://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html#enableWriteAheadLogging()