1. Data Storage: Part 3 (SQLite)

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

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

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

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

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

7. 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
©SoftMoore Consulting

8. Using the sqlite3 Command-Line (continued)
Start a virtual device (emulator) and launch the ADB shell from a command prompt
C:\>adb shell
Connect to the database
# sqlite3 /data/data/edu.citadel.android.emergency/databases/emergency.db
sqlite3 /data/data/edu.citadel.android.emergency/databases/emergency.db
SQLite version
Enter ".help" for instructions
Enter 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
Note: Does not work with a real device.
response
©SoftMoore Consulting

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

10. Example: Using the sqlite3 Command-Line
sqlite> .mode column .mode column sqlite> .width width sqlite> .headers ON .headers ON sqlite> select * from emergency_contacts; select * from emergency_contacts; _id name phone_num Emergency Home Kayran - Cell John - Cell Robert - Cell Angela - Cell sqlite>
©SoftMoore Consulting

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

12. 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(), onUpgrade().
Note: Database names must be unique within
an application, not across all applications.
©SoftMoore Consulting

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

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

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

16. 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 }
Useful for adding
a content provider.
©SoftMoore Consulting

17. 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); }
(continued on next slide)
©SoftMoore Consulting

18. 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); }
(continued on next slide)
©SoftMoore Consulting

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

20. 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.
©SoftMoore Consulting

21. Selected Methods in Class SQLiteDatabase
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.
©SoftMoore Consulting

22. Selected Methods in Class SQLiteDatabase (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.
©SoftMoore Consulting

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

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

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

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

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

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

29. 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.
©SoftMoore Consulting

30. Data Binding (continued)
ListActivity
(an activity)
AdapterView
(a view group)
Adapter
data
source
©SoftMoore Consulting

31. 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 controlling the overall display of the list, and it can optionally contain another view with an id of to display when the list is empty.
©SoftMoore Consulting

32. 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.)
©SoftMoore Consulting

33. 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)
... }
});
The above approach must be used if you want to implement
a method to respond to long clicks; i.e., you must implement
OnItemLongClickListener() for the list view.
©SoftMoore Consulting

34. 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.
©SoftMoore Consulting

35. Example: Default Layout for ListActivity
<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android=" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent"> <ListView android:layout_height="wrap_content" android:fastScrollEnabled="true" android:layout_weight="1.0"/>
Note the id! No “+”
sign tells Android to use an existing id
and not to generate
a new one.)
(continued on next slide)
©SoftMoore Consulting

36. Example: Default Layout for ListActivity (continued)
<TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:textStyle="bold" /> ... other (e.g., a button) </LinearLayout>
Note the id!
©SoftMoore Consulting

37. Example: Layout for each Row in the ListActivity
<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android=" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent" "> <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" android:textStyle="bold" " />
(continued on next slide)
©SoftMoore Consulting

38. Example: Row Layout for Each Row in the ListActivity (continued)
<TextView android:layout_width="wrap_content" android:layout_height="wrap_content" /> </LinearLayout>
File name is contact.xml.
©SoftMoore Consulting

39. 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).
Note: The Cursor must include a column
named "_id" or this class will not work.
©SoftMoore Consulting

40. Example: SimpleCursorAdapter
// in MainActivity, which extends ListActivity private static final String[] COLUMNS = { "name", "phone_num" }; private static final int[] VIEWS = { R.id.name, R.id.phoneNum }; private SQLiteOpenHelper openHelper; public void onCreate(Bundle savedInstanceState) { openHelper = new EmergencyDbOpenHelper(this); setContactListAdapter(); }
(continued on next slide)
©SoftMoore Consulting

41. 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);
layout for rows
these columns get mapped to these views
©SoftMoore Consulting

42. 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.
©SoftMoore Consulting

43. Displaying the ListView
©SoftMoore Consulting

44. Example: Handling Item Click Events
@Override protected 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); }
Alternatively, use
ListView lv = getListView();
lv.setOnItemClickListener(…);
©SoftMoore Consulting

45. 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); }
Important: When making a phone call, remember to add
<uses-permission android:name="android.permission.CALL_PHONE" />
before the application element in AndroidManifest.xml.
©SoftMoore Consulting

46. 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
©SoftMoore Consulting

47. 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.
©SoftMoore Consulting

48. Relevant Links Data Storage Class SQLiteDatabase
Class SQLiteDatabase
Class SQLiteOpenHelper
SQLite (home page)
Android Database Example (slightly different approach)
Appendix H - SQL Primer
PowerPoint Slides for this course
©SoftMoore Consulting