Data Storage: Part 3 (SQLite). SQLite SQLite is a software library that provides full relational database capability for Android applications. Each application.

Data Storage: Part 3(SQLite)

©SoftMoore Consulting

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.

Slide 2


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.

Slide 3


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.

Slide 4


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.

Slide 5


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.

Slide 6


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 an environment variable ANDROID_SDK_HOME; e.g.,

ANDROID_SDK_HOME=C:\Java\android-sdk-windows– add the following to your PATH environment variable:

• %ANDROID_SDK_HOME%• %ANDROID_SDK_HOME%\tools• %ANDROID_SDK_HOME%\platform-tools

Slide 7


Using the sqlite3 Command-Line(continued)

• Start a virtual device (emulator) and launch the ADB shell from a command promptC:\>adb shell

• Connect to the database# sqlite3

/data/data/edu.citadel.android.emergency/databases/emergency.dbsqlite3

/data/data/edu.citadel.android.emergency/databases/emergency.dbSQLite version 3.6.22Enter ".help" for instructionsEnter SQL statements terminated with a ";"sqlite>

• Enter SQL statements and SQLite commands at the prompt.– SQL statements must be terminated by a semicolon.– SQLite commands start with a period.– SQL statements and SQLite commands are echoed Slide 8

response

Note: Does not work with a real device.


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

Slide 9


Example: Using the sqlite3 Command-Line

sqlite> .mode column.mode columnsqlite> .width 3 15 12.width 3 15 12sqlite> .headers ON.headers ONsqlite> select * from emergency_contacts;select * from emergency_contacts;_id name phone_num--- --------------- ------------1 Emergency - 911 9112 Home 843-123-45673 Kayran - Cell 843-234-56784 John - Cell 847-345-67895 Robert - Cell 202-456-78906 Angela - Cell 434-567-8901sqlite>

Slide 10


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

Slide 11


Class SQLiteOpenHelper

• Class SQLiteOpenHelper is an abstract helper classin 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(), onUpgrade().

Slide 12

Note: Database names must be unique withinan application, not across all applications.


Selected Methods in ClassSQLiteOpenHelper

• 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

Slide 13


Selected Methods in ClassSQLiteOpenHelper (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

Slide 14


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.

Slide 15


Example: Contract Class

public final class EmergencyContract { 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 EmergencyContract() {} // prevent instantiation }

Slide 16

Useful for addinga content provider.


Example: Using SQLiteOpenHelper

public class EmergencyDbOpenHelper extends SQLiteOpenHelper { /** * Construct a SQLiteOpenHelper object for the * emergency database. */ public EmergencyDbOpenHelper(Context context) { super(context, EmergencyContract.DB_NAME, null, EmergencyContract.DB_VERSION); }

Slide 17

(continued on next slide)


Example: Using SQLiteOpenHelper(continued)

@Override public void onCreate(SQLiteDatabase db) { String createSql = "create table " + EmergencyContract.TABLE_NAME + "(" + " _id integer primary key autoincrement," + " name text not null," + " phone_num text not null" + ")"; db.execSQL(createSql); insertContacts(db); }

Slide 18



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 }

Slide 19


Class SQLiteDatabase

• Class SQLiteDatabase (in package android.database.sqlite) exposes methods to manage a SQLite database.

• Class SQLiteDatabase has methods to create, delete, execute SQL commands, and to perform other common database management tasks.

• Class SQLiteDatabase 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.

Slide 20


Selected Methods in ClassSQLiteDatabase

• void beginTransaction()– Begins a transaction.

• int delete(String table, String whereClause, String[] whereArgs)– Convenience method for deleting rows in the database.

• void endTransaction()– End a transaction.

• void execSQL(String sql)– Execute a single SQL statement that does not return data.

• long insert(String table, String nullColumnHack, ContentValues values)– Convenience method for inserting a row into the database.

Slide 21


Selected Methods in ClassSQLiteDatabase (continued)

• 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.

• int update(String table, ContentValues values, String whereClause, String[] whereArgs)– Convenience method for updating rows in the database.

Slide 22


Example: Using Query Methods in ClassSQLiteDatabase

SQLiteOpenHelper openHelper = new EmergencyDbOpenHelper(this); SQLiteDatabase db = openHelper.getReadableDatabase();

• Query using convenience methodsString 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);

Slide 23


Example: Using Insert Methods in ClassSQLiteDatabase

SQLiteOpenHelper openHelper = new EmergencyDbOpenHelper(this); SQLiteDatabase db = openHelper.getWritableDatabase();

• Insert using convenience methodsString 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);

Slide 24


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()).

Slide 25


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)

Slide 26

Returns the valueof the requestedcolumn as thespecified type.

Moves the cursoras specified.


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.

• Examplewhile (cursor.moveToNext()) { ... // retrieve/process data for one row }

Slide 27


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(); }

Slide 28


Data Binding

• The binding of data to views is simplified by using a few specialized classes and interfaces.

• Class ListActivity can be used to display a list of items by binding to a data source such as an array or Cursor.

• Class AdapterView is a view group whose children are determined by an Adapter. Commonly used subclasses include ListView and Spinner.

• Interface Adapter acts as a bridge between an AdapterView and the underlying data for that view. Commonly used classes that extend Adapter include ArrayAdapter<T> and CursorAdapter.

Slide 29


Data Binding(continued)

Slide 30

ListActivity(an activity)

AdapterView(a view group)

Adapter

datasource


Class ListActivity

• Class ListActivity is a subclass of Activity used to display a list of items by binding to a data source such as an array or Cursor. It also exposes event handlers when the user selects an item.

• A ListActivity uses two layouts, a default layout for the screen and a row layout for the individual rows in the list.

• The default layout contains a ListView object with the id “@android:id/list” controlling the overall display of the list, and it can optionally contain another view with an id of "@android:id/empty" to display when the list is empty.

Slide 31


Selected Methods in Class ListActivity

• ListAdapter getListAdapter()– Get the ListAdapter associated with this activity’s ListView.

• ListView getListView()– Get the activity’s list view widget.

• void setListAdapter(ListAdapter adapter)– Set the ListAdapter for the list view.

• void onListItemClick(ListView l, View v, int position, long id)– Called when an item in the list is selected.

(Equivalent to implementing an OnItemClickListener for the list view − see next slide.)

Slide 32


Selected Methods in Class ListActivity(continued)

Implementing method onListItemClick() is equivalent to implementing an OnItemClickListener for the list view.

ListView lv = getListView();lv.setOnItemClickListener(new AdapterView.OnItemClickListener() { public void onItemClick(AdapterView<?> parent, View view, int position, long id) { ... } });

Slide 33

The above approach must be used if you want to implementa method to respond to long clicks; i.e., you must implementOnItemLongClickListener() for the list view.


Using Class ListActivity

• Extend class ListActivity (rather than Activity)public class MainActivity extends ListActivity { ... }

• Define the default layout for the screen.

• Define the row layout for the individual rows.

Slide 34


Example: Default Layout for ListActivity

<?xml version="1.0" encoding="utf-8"?><LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent">

<ListView android:id="@android:id/list" android:layout_width="match_parent" android:layout_height="wrap_content" android:fastScrollEnabled="true" android:scrollbarSize="@dimen/scrollbarSize" android:divider="@color/dividerColor" android:dividerHeight="@dimen/dividerHeight" android:layout_weight="1.0"/> Slide 35

Note the id! No “+”sign tells Androidto use an existing idand not to generatea new one.)



Example: Default Layout for ListActivity(continued)

<TextView android:id="@android:id/empty" android:layout_width="match_parent" android:layout_height="wrap_content" android:textStyle="bold" android:textSize=“@dimen/emptyTextSize" android:text="@string/emptyList" />

... other (e.g., a button)

</LinearLayout>

Slide 36

Note the id!


Example: Layout for eachRow in the ListActivity

<?xml version="1.0" encoding="utf-8"?><LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent" android:padding=" @dimen/contactPadding "> <TextView android:id="@+id/name" android:layout_width="wrap_content" android:layout_height="wrap_content" android:textStyle="bold" android:textSize=" @dimen/nameTextSize " />

Slide 37



Example: Row Layout for EachRow in the ListActivity (continued)

<TextView android:id="@+id/phoneNum" android:layout_width="wrap_content" android:layout_height="wrap_content" android:textSize="@dimen/phoneTextSize" />

</LinearLayout>

Slide 38

File name is contact.xml.


Class SimpleCursorAdapter

• Class CursorAdapter maps columns from a cursor to TextViews or ImageViews defined in an XML file. Class SimpleCursorAdapter is a subclass of CursorAdapter that is simple and easy to use.

• To use a SimpleCursorAdapter, specify the columns from the cursor, the views to display the columns (e.g., TextViews), and the XML files that defines the appearance of these views (i.e., the default layout and the row layout).

Slide 39

Note: The Cursor must include a columnnamed "_id" or this class will not work.


Example: SimpleCursorAdapter

// in MainActivity, which extends ListActivityprivate static final String[] COLUMNS = { "name", "phone_num" };private static final int[] VIEWS = { R.id.name, R.id.phoneNum };

private SQLiteOpenHelper openHelper;

...

@Overridepublic void onCreate(Bundle savedInstanceState) { ...

openHelper = new EmergencyDbOpenHelper(this); setContactListAdapter(); }

Slide 40



Example: SimpleCursorAdapter(continued)

private void setContactListAdapter() { try { String query = "select * from " + EmergencyContract.TABLE_NAME; SQLiteDatabase db = openHelper.getReadableDatabase(); Cursor cursor = db.rawQuery(query, null); SimpleCursorAdapter adapter = new SimpleCursorAdapter (this, R.layout.contact, cursor, COLUMNS, VIEWS, 0); setListAdapter(adapter); } catch (Exception ex) { String errorMsg = "Error retrieving emergency contacts"; Log.e(LOG_TAG, errorMsg, ex); } }

Slide 41

these columns get mapped to these views

layout for rows


Comments on the Example

• Not every column returned by the cursor needs to be mapped to a view; e.g., _id is not mapped to a view in this example.

• Calling setContactListAdapter() after a change to the database will requery the database and reset the list in the display.

Slide 42


Displaying the ListView

Slide 43


Example: Handling Item Click Events

@Overrideprotected void onListItemClick(ListView listView, View view, int position, long id) { ViewGroup vg = (ViewGroup) view; TextView nameView = (TextView) vg.getChildAt(0); String name = nameView.getText().toString(); TextView phoneNumView = (TextView) vg.getChildAt(1); String phoneNum = phoneNumView.getText().toString();

callContact(phoneNum); }

Slide 44

Alternatively, useListView lv = getListView();lv.setOnItemClickListener(…);


Example: Handling Item Click Events(continued)

private void callContact(String phoneNum) { Uri uri = Uri.parse("tel:" + phoneNum); Intent intent = new Intent(Intent.ACTION_CALL, uri); startActivity(intent); }

Slide 45

Important: When making a phone call, remember to add<uses-permission android:name="android.permission.CALL_PHONE" />

before the application element in AndroidManifest.xml.


Parameters to Method onListItemClick()

• parent: The ListView where the click happened.

• view: The view within the ListView that was clicked

• position: The position of the view in the adapter.– 0-based position numbers

• id: The row id of the item that was clicked.– from the database

Slide 46


Comments on Using an Unmanaged Cursor

• The approach described in this section for creating a ListView using a SimpleCursorAdapter and a SQLite database is acceptable if the database is relatively small and the data doesn’t change (no re-query necessary).

For larger databases or when re-query is necessary:

• Older versions of Android used a method named startManagingCursor(), deprecated in API 11, that managed the cursor’s lifecycle based on the activity’s lifecycle.

• As described in subsequent sections, the more modern approach is to implement a content provider and to use classes CursorLoader and LoaderManager.

Slide 47


Relevant Links

• Data Storagehttp://developer.android.com/guide/topics/data/data-storage.html

• Class SQLiteDatabasehttp://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html

• Class SQLiteOpenHelperhttp://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper.html

• SQLite (home page)http://www.sqlite.org/

• Android Database Example (slightly different approach)http://examples.javacodegeeks.com/android/core/database/android-database-example/

• Appendix H - SQL PrimerPowerPoint Slides for this course

Slide 48

http://developer.android.com/guide/topics/data/data-storage.html

http://developer.android.com/reference/android/database/sqlite/SQLiteDatabase.html

http://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper.html

http://www.sqlite.org/

http://examples.javacodegeeks.com/android/core/database/android-database-example/

Data Storage: Part 3 (SQLite). SQLite SQLite is a software library that provides full relational database capability for Android applications. Each application.

Documents