public abstract class SQLitePortal
extends android.database.sqlite.SQLiteOpenHelper
SQLiteOpenHelper
with a few additional features.
The portal maintains its own persistent reference to the underlying SQLite
database. This connection is established with a background thread kicked off
by the openDB()
method. The
class provides variants of this method allowing the caller to specify whether
the connection should be opened read-only, and provide a
ConnectionListener
instance which can handle the
onDatabaseConnected()
callback
method.
The portal's close()
method also overrides the parent's, so that
it can close the connection to the database before closing out the portal
itself.
The class provides several static methods that are generally useful when dealing with SQLite databases. In particular:
closeCursor(Cursor)
boolToInt(boolean)
and intToBool(int)
Since 0.1.1 (#20), some of these items also form the basis of
QueryBuilder
and its descendants.
Note that most of the static constants provided by this class were
moved to SQLiteSyntax
in 0.1.7 (#48).
Modifier and Type | Class and Description |
---|---|
static interface |
SQLitePortal.ConnectionListener
Classes interested in immediately reacting to a database's connection
status may implement this interface to catch the event.
|
protected class |
SQLitePortal.ConnectionTask
Allows the
SQLitePortal to create a persistent connection to its
underlying database on a background thread. |
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
LOG_TAG |
protected boolean |
m_bIsConnected
Indicates whether a connection to the database has been established.
|
protected boolean |
m_bReadOnly
Indicates whether connections should be read-only.
|
protected android.content.Context |
m_ctx
The context in which the portal is created.
|
protected android.database.sqlite.SQLiteDatabase |
m_db
A persistent reference to the underlying database.
|
protected int |
m_nLatestVersion
Remembers the version number with which the instance was constructed.
|
static int |
SQLITE_FALSE_INT
Integer representation of "false".
|
static java.lang.String |
SQLITE_FALSE_INTSTRING
Stringified-integer representation of "false".
|
static int |
SQLITE_TRUE_INT
Integer representation of "true".
|
static java.lang.String |
SQLITE_TRUE_INTSTRING
Stringified-integer representation of "true".
|
static java.lang.String |
WHERE_FALSE
If using integer columns to store Boolean values, where
1 is true
and 0 is false, use this constant when supplying WHERE
value substitutions for "false". |
static java.lang.String |
WHERE_TRUE
If using integer columns to store Boolean values, where
1 is true
and 0 is false, use this constant when supplying WHERE
value substitutions for "true". |
Constructor and Description |
---|
SQLitePortal(android.content.Context ctx,
java.lang.String sDatabaseName,
android.database.sqlite.SQLiteDatabase.CursorFactory cf,
int nVersion) |
Modifier and Type | Method and Description |
---|---|
static int |
boolToInt(boolean b)
Simplistic transformation of a Boolean value to an integer, for storage
in an SQLite database.
|
static java.lang.String |
boolToIntString(boolean b)
Transforms a Boolean value into the string representation of a
corresponding integer, for use in SQLite statements.
|
void |
close()
Closes the database connection and releases all references to it, before
closing the portal itself.
|
static void |
closeCursor(android.database.Cursor crs)
Safely closes a database cursor.
|
SQLitePortal |
closeDB()
Closes the database connection and releases all references to it.
|
protected boolean |
databaseExists()
Checks whether the portal's database exists in the app's data folder on
the Android device.
|
static boolean |
getBooleanColumn(android.database.Cursor crs,
java.lang.String sColName)
Shorthand to fetch the Boolean value from a column that stores Boolean
values as integers.
|
java.util.List<SQLiteColumnInfo> |
getColumnListForTable(java.lang.String sTableName)
Uses SQLite pragmas to discover the structure of an existing table, and
return a list of its column definitions.
|
java.util.Map<java.lang.String,SQLiteColumnInfo> |
getColumnMapForTable(java.lang.String sTableName)
Uses SQLite pragmas to discover the structure of an existing table, and
return a map of column names to column definitions.
|
android.content.Context |
getContext()
Accessor for the context in which the instance was created.
|
protected long |
getDatabaseFileSize()
Discovers the size of the database file in storage.
|
int |
getLatestSchemaVersion()
Accessor for the schema version with which the instance was constructed.
|
protected java.lang.String |
getPathToDatabaseFile()
Discovers the full path to the database file for this portal in the app's
data folder on the Android device.
|
static boolean |
intToBool(int z)
Simplistic transformation of an integer to a Boolean value, for retrieval
of a value from an SQLite database.
|
boolean |
isConnected()
Indicates whether the portal has established a connection.
|
SQLitePortal |
openDB()
Kicks off a
SQLitePortal.ConnectionTask to establish the connection to the
SQLite database. |
SQLitePortal |
openDB(boolean bReadOnly)
Kicks off a
SQLitePortal.ConnectionTask which will optionally connect in
read-only mode. |
SQLitePortal |
openDB(boolean bReadOnly,
SQLitePortal.ConnectionListener l)
Kicks off a
SQLitePortal.ConnectionTask which will optionally connect in
read-only mode, and will inform the specified SQLitePortal.ConnectionListener
when the connection to the SQLite database is established |
SQLitePortal |
openDB(SQLitePortal.ConnectionListener l)
Kicks off a
SQLitePortal.ConnectionTask which will inform the specified
SQLitePortal.ConnectionListener when the connection to the SQLite database is
established. |
public static final java.lang.String LOG_TAG
public static final int SQLITE_TRUE_INT
boolToInt(boolean)
,
intToBool(int)
,
Constant Field Valuespublic static final java.lang.String SQLITE_TRUE_INTSTRING
boolToIntString(boolean)
,
SQLITE_TRUE_INT
,
Constant Field Valuespublic static final int SQLITE_FALSE_INT
boolToInt(boolean)
,
intToBool(int)
,
Constant Field Valuespublic static final java.lang.String SQLITE_FALSE_INTSTRING
boolToIntString(boolean)
,
SQLITE_FALSE_INT
,
Constant Field Valuespublic static final java.lang.String WHERE_TRUE
1
is true
and 0
is false, use this constant when supplying WHERE
value substitutions for "true".boolToInt(boolean)
,
intToBool(int)
,
Constant Field Valuespublic static final java.lang.String WHERE_FALSE
1
is true
and 0
is false, use this constant when supplying WHERE
value substitutions for "false".boolToInt(boolean)
,
intToBool(int)
,
Constant Field Valuesprotected android.content.Context m_ctx
protected android.database.sqlite.SQLiteDatabase m_db
protected int m_nLatestVersion
SQLiteOpenHelper
, so in order to use this
in SQLitePortal
and its descendants, we have to copy it here.protected boolean m_bIsConnected
protected boolean m_bReadOnly
public SQLitePortal(android.content.Context ctx, java.lang.String sDatabaseName, android.database.sqlite.SQLiteDatabase.CursorFactory cf, int nVersion)
SQLiteOpenHelper.SQLiteOpenHelper(Context, String, SQLiteDatabase.CursorFactory, int)
public static void closeCursor(android.database.Cursor crs)
null
, or the
cursor is already closed, then the method returns trivially.crs
- the cursor to be closedpublic static int boolToInt(boolean b)
b
- the Boolean value to be converted1
for true or 0
for falsepublic static java.lang.String boolToIntString(boolean b)
b
- the Boolean value to be converted"1"
for true or "0"
for falsepublic static boolean intToBool(int z)
z
- the integer to be convertedtrue
iff the integer is non-zeropublic static boolean getBooleanColumn(android.database.Cursor crs, java.lang.String sColName)
crs
- the cursor that contains a row with one of these columnssColName
- the name of the columnpublic boolean isConnected()
true
if the instance thinks that it is connected.public SQLitePortal openDB()
SQLitePortal.ConnectionTask
to establish the connection to the
SQLite database.public SQLitePortal openDB(SQLitePortal.ConnectionListener l)
SQLitePortal.ConnectionTask
which will inform the specified
SQLitePortal.ConnectionListener
when the connection to the SQLite database is
established.l
- the listener for the "on connected" callbackpublic SQLitePortal openDB(boolean bReadOnly)
SQLitePortal.ConnectionTask
which will optionally connect in
read-only mode.bReadOnly
- specifies whether to open the database in read-only modepublic SQLitePortal openDB(boolean bReadOnly, SQLitePortal.ConnectionListener l)
SQLitePortal.ConnectionTask
which will optionally connect in
read-only mode, and will inform the specified SQLitePortal.ConnectionListener
when the connection to the SQLite database is establishedbReadOnly
- specifies whether to open the database in read-only model
- the listener for the "on connected" callbackpublic SQLitePortal closeDB()
Note: Since 0.1.4 (#34), there is no need to invoke this method
before close()
; this class now overrides the parent's
close()
method to call closeDB()
first.
public void close()
close
in class android.database.sqlite.SQLiteOpenHelper
protected java.lang.String getPathToDatabaseFile()
protected boolean databaseExists()
true
if the database has already been createdpublic java.util.List<SQLiteColumnInfo> getColumnListForTable(java.lang.String sTableName)
sTableName
- the name of the table to be describedSQLiteColumnInfo.gatherColumnList(android.database.sqlite.SQLiteDatabase, java.lang.String)
public java.util.Map<java.lang.String,SQLiteColumnInfo> getColumnMapForTable(java.lang.String sTableName)
sTableName
- the name of the table to be describedSQLiteColumnInfo.gatherColumnMap(android.database.sqlite.SQLiteDatabase, java.lang.String)
protected long getDatabaseFileSize()
public int getLatestSchemaVersion()
public android.content.Context getContext()