Data Storage: Part 3 (SQLite)

SQLite SQLite is a software library that provides full relational database capability for Android applications. Each application that uses SQLite has its own instance of the database, which is by default accessible only from the application itself. The database is stored in the following folder: /data/data/<package-name>/databases A Content Provider can be used to share the database information with other applications. ©SoftMoore Consulting

Features of SQLite ACID transactions (atomic, consistent, isolated, and durable) Zero-configuration – no setup or administration. Implements most of SQL92. Complete database is stored in a single file. Supports terabyte-sized databases and gigabyte-sized strings and blobs. Small code footprint (less than 325KB fully configured). Self-contained: no external dependencies. C source code is in the public domain. ©SoftMoore Consulting

SQLite Datatypes Most SQL database systems use static typing; i.e., the type of a value is determined by the column in which the value is stored. SQLite uses a more general dynamic type system – the type of a value is associated with the value itself, not with its column. Think of column types as hints. It is possible to store a string in an integer column and vice versa. ©SoftMoore Consulting

SQLite Datatypes (continued) Each value stored in an SQLite database has one of the following storage classes: NULL. The value is a NULL value. INTEGER. The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value. REAL. The value is a floating point value, stored as an 8-byte IEEE floating point number. TEXT. The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16LE). BLOB. The value is a blob of data, stored exactly as it was input. Note that a storage class is slightly more general than a type. ©SoftMoore Consulting

SQLite Datatypes (continued) Each column in a SQLite database is assigned one of the following type affinities: TEXT – NUMERIC INTEGER – REAL NONE SQLite does not have a separate Boolean storage class. Boolean values are stored as integers 0 (false) and 1 (true). SQLite does not have a storage class set aside for storing dates and/or times. Instead, the built-in date and time functions of SQLite are capable of storing dates and times as TEXT, REAL, or INTEGER values. ©SoftMoore Consulting

Using the sqlite3 Command-Line In addition to accessing a SQLite database from an Android application, it is also possible to interact with the database on a virtual device using the sqlite3 command-line tool via the Android Debug Bridge (ADB) remote shell. Preparation add environment variables ANDROID_SDK_HOME; e.g., C:\Java\Android\sdk ANDROID_AVD_HOME; e.g., C:\Users\jmoore\.android\avd add the following to your PATH environment variable: %ANDROID_AVD_HOME% %ANDROID_SDK_HOME% %ANDROID_SDK_HOME%\tools %ANDROID_SDK_HOME%\platform-tools Put this one first – above the others. ©SoftMoore Consulting

Using the sqlite3 Command-Line (continued) Start a virtual device (emulator) and launch the ADB shell to connect to the database from a command prompt. C:>adb devices List of devices attached emulator-5554 device C:>adb -s emulator-5554 shell generic_x86:/ $ su generic_x86:/ # sqlite3 /data/data/edu.citadel.android.emergency/databases/emergency.db SQLite version 3.9.2 2015-11-02 18:31:45 Enter ".help" for usage hints. sqlite> Enter SQL statements and commands at the prompt. SQL statements must be terminated by a semicolon. SQLite commands start with a period. Note: Does not work with a real device. response ©SoftMoore Consulting

Selected SQLite Commands .databases List names/files of attached databases .exit Exit this program .header(s) ON|OFF Turn display of headers on or off .help Show all SQLite commands .import FILE TABLE Import data from FILE into TABLE .mode column Left-aligned columns. (See .width) .read FILENAME Execute SQL in FILENAME .schema Show the CREATE statements .width NUM NUM … Set column widths for “column” mode ©SoftMoore Consulting

Example: Using the sqlite3 Command-Line sqlite> .mode column sqlite> .width 3 15 12 sqlite> .headers on sqlite> select * from emergency_contacts; _id name phone_num --- --------------- ------------ 1 Emergency - 911 911 2 Consolidated Di 843-743-7200 3 Home 123-456-7890 4 Mary - Home 234-567-8901 5 Jim - Cell 345-678-9012 6 Billy - Cell 456-789-0123 7 Monica - Home 567-890-1234 8 Tommy - Cell 567-890-1234 sqlite> ©SoftMoore Consulting

Developing Applications Using SQLite Primary classes and interfaces android.database.sqlite.SQLiteDatabase android.database.sqlite.SQLiteOpenHelper (abstract) android.database.Cursor (interface) Using adapters to connect data and views Understanding relational databases and SQL ©SoftMoore Consulting

Class SQLiteOpenHelper Class SQLiteOpenHelper is an abstract helper class in package android.database.sqlite that can be used to manage database creation and versioning. Class SQLiteOpenHelper will open the database if it exists create the database if it does not exist upgrade the database as necessary To use class SQLiteOpenHelper, create a subclass that overrides abstract methods onCreate() and onUpgrade(). Note: Database names must be unique within an application, not across all applications. ©SoftMoore Consulting

Selected Methods in Class SQLiteOpenHelper SQLiteOpenHelper(Context context, String name, SQLiteDatabase.CursorFactory factory, int version) constructor to initialize a SQLiteOpenHelper object the factory parameter can be null for the default value void close() close an open database SQLiteDatabase getReadableDatabase() create and/or open a database for reading only SQLiteDatabase getWritableDatabase() create and/or open a database for both reading and writing ©SoftMoore Consulting

Selected Methods in Class SQLiteOpenHelper (continued) abstract void onCreate(SQLiteDatabase db) called when the database is created for the first time Note: You can “preload” a set of database values in this method. void onOpen(SQLiteDatabase db) called when the database is opened abstract void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) called when the database needs to be upgraded ©SoftMoore Consulting

Contract Class Applications that use a database and/or implement a content provider (see next section) often implement a “contract” class. A contract class defines constants that help applications work with the content URIs, column names, intent actions, and other features of a content provider. Contract classes are not included automatically with a provider; the provider’s developer has to define them and make them available to other developers. ©SoftMoore Consulting

Example: Contract Class public final class EmergencyDbContract { public static final String DB_NAME = "emergency.db"; public static final int DB_VERSION = 1; public static final String TABLE_NAME = "emergency_contacts"; public static final String[] COLUMNS = { "_id", "name", "phone_num" }; public static final String AUTHORITY = "edu.citadel.android.emergency"; public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/" + TABLE_NAME); private EmergencyDbContract() {} // prevent instantiation } Useful for adding a content provider. ©SoftMoore Consulting

Surrogate Primary Keys in SQLite In SQLite, a column with type INTEGER PRIMARY KEY is an alias for the ROWID. can be used as a surrogate key On an insert, if the integer primary key column is not explicitly given a value, then it will be filled in automatically by SQLite with an unsigned integer. SQLite provides an AUTOINCREMENT keyword that can be used in defining such a key, but ... it has slightly different semantics it imposes extra runtime overhead and should be avoided ©SoftMoore Consulting

Example: Using SQLiteOpenHelper public class EmergencyDbOpenHelper extends SQLiteOpenHelper { /** * Construct a SQLiteOpenHelper object for the * emergency database. */ public EmergencyDbOpenHelper(Context context) super(context, EmergencyDbContract.DB_NAME, null, EmergencyDbContract.DB_VERSION); } (continued on next slide) ©SoftMoore Consulting

Example: Using SQLiteOpenHelper (continued) @Override public void onCreate(SQLiteDatabase db) { String createSql = "create table " + EmergencyDbContract.TABLE_NAME + "(" + " _id integer primary key," + " name text not null," + " phone_num text not null" + ")"; db.execSQL(createSql); insertContacts(db); } (continued on next slide) ©SoftMoore Consulting

Example: Using SQLiteOpenHelper (continued) @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { // This is version 1 so no actions are required. // Possible actions include dropping/recreating // tables, saving/restoring data in tables, etc. } private void insertContacts(SQLiteDatabase db) // perform inserts to initialize the database ©SoftMoore Consulting

Class SQLiteDatabase Defined in package android.database.sqlite Exposes methods to manage a SQLite database Has methods to create, delete, execute SQL commands, and to perform other common database management tasks Has several “convenience” methods for constructing SQL queries, inserts, etc. Alternatively, other methods can be used to directly execute SQL commands passed as string parameters. ©SoftMoore Consulting

Selected Methods in Class SQLiteDatabase void beginTransaction() begin a transaction int delete(String table, String whereClause, String[] whereArgs) convenience method for deleting rows from the database returns the number of rows affected if a where clause is passed in; 0 otherwise void endTransaction() end a transaction void execSQL(String sql) execute a single SQL statement that does not return data ©SoftMoore Consulting

Selected Methods in Class SQLiteDatabase (continued) long insert(String table, String nullColumnHack, ContentValues values) convenience method for inserting a row into the database returns the row ID of the newly inserted row, or -1 if an error occurred Cursor query(String table, String[] columns, String selection, String[] selectionArgs, String groupBy, String having, String orderBy) query the given table, returning a Cursor over the result set Cursor rawQuery(String sql, String[] selectionArgs) runs the provided SQL and returns a Cursor over the result set ©SoftMoore Consulting

Selected Methods in Class SQLiteDatabase (continued) int update(String table, ContentValues values, String whereClause, String[] whereArgs) convenience method for updating rows in the database returns the number of rows affected ©SoftMoore Consulting

Example: Using Query Methods in Class SQLiteDatabase SQLiteOpenHelper openHelper = new EmergencyDbOpenHelper(this); SQLiteDatabase db = openHelper.getReadableDatabase(); Query using convenience methods String tableName = "emergency_contacts"; String[] columns = {"name", "phone_num"}; String orderBy = "name"; Cursor cursor = db.query(tableName, columns, null, null, null, null, orderBy); Query using method rawQuery() String query = "select name, phone_num" + " from emergency_contacts" + " order by name"; Cursor cursor = db.rawQuery(query, null); ©SoftMoore Consulting

Example: Using Insert Methods in Class SQLiteDatabase SQLiteOpenHelper openHelper = new EmergencyDbOpenHelper(this); SQLiteDatabase db = openHelper.getWritableDatabase(); Insert using convenience methods String tableName = "emergency_contacts"; ContentValues values = new ContentValues(); values.put("name", "Emergency – 911"); values.put("phone_num", "911"); db.insert(tableName, null, values); Insert using method execSQL() String insertSql = "insert into emergency_contacts" + " (name, phone_num) values" + " (\"Emergency - 911\", \"911\")"; db.execSQL(insertSql); ©SoftMoore Consulting

Interface Cursor Interface Cursor (in package android.database) is used to iterate over the rows returned by a “select” query. analogous to a Java Iterator or a JDBC ResultSet Interface Cursor provides random read-write access to the result set returned by a database query. Methods in interface Cursor can be used to position the cursor within the result set (“move” methods) to retrieve column values from the row (“get” methods) to provide metadata about the query (e.g., getColumnNames()). ©SoftMoore Consulting

Selected Methods in Interface Cursor int getColumnIndex(String columnName) Returns zero-based index for the given column name double getDouble(int columnIndex) int getInt(int columnIndex) long getLong(int columnIndex) String getString(int columnIndex) boolean move(int offset) boolean moveToFirst() boolean moveToNext() boolean moveToPosition(int position) Returns the value of the requested column as the specified type. Moves the cursor as specified. ©SoftMoore Consulting

Using a Cursor Similar to using a JDBC ResultSet, initially a cursor is positioned before the first row. The various “move” methods can be used to move the cursor to a row. The moveToNext() method moves the cursor to the next row. Since it returns false when there are no more rows, it can be used in a while loop to iterate through the rows of a cursor. Example while (cursor.moveToNext()) { ... // retrieve/process data for one row } ©SoftMoore Consulting

Example: Using Interface Cursor SQLiteDatabase db = openHelper.getReadableDatabase(); String query = "select * from emergency_contacts"; Cursor cursor = db.rawQuery(query, null); while (cursor.moveToNext()) { int id = cursor.getInt(0); String name = cursor.getString(1); String phoneNum = cursor.getString(2); String message = "ID: " + id + ", Name: " + name + ", Phone Number: " + phoneNum; Toast toast = Toast.makeText(Emergency.this, message, Toast.LENGTH_SHORT); toast.show(); } ©SoftMoore Consulting

Relevant Links Data Storage Class SQLiteDatabase https://developer.android.com/guide/topics/data/data-storage.html Class SQLiteDatabase https://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html Class SQLiteOpenHelper https://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper.html SQLite (home page) http://www.sqlite.org/ Android Database Example http://examples.javacodegeeks.com/android/core/database/android-database-example/ Appendix E - SQL Primer PowerPoint slides for this course ©SoftMoore Consulting