net.akaish.kitty.orm

Class KittyDatabaseHelper

java.lang.Object

android.database.sqlite.SQLiteOpenHelper

net.akaish.kitty.orm.KittyDatabaseHelper

All Implemented Interfaces:

java.lang.Cloneable

public class KittyDatabaseHelper
extends android.database.sqlite.SQLiteOpenHelper
implements java.lang.Cloneable

Helper implementation to be used with KittyORM with support of database version migrations and with implementation of cloning interface.

(!) There is no need to annotate this class or it's child with KITTY_DATABASE_HELPER annotation. KITTY_DATABASE_HELPER annotation should be applied only to implementations of KittyDatabase.

Author:

akaish (Denis Bogomolov)

Field Summary

Fields

Modifier and Type	Field and Description
protected KittySQLiteDumpScript	afterCreateScript
protected KittySQLiteDumpScript	afterMigrateScript
protected android.content.Context	context
protected java.util.LinkedList<KittySQLiteQuery>	createSchemaAutogeneratedScript
protected KittyDatabaseConfiguration	databaseConfiguration
protected static java.lang.String	DC_CE_NO_CREATE_SEQUENCE
protected static java.lang.String	DC_CE_NO_DROP_SEQUENCE
protected java.util.LinkedList<KittySQLiteQuery>	dropSchemaAutogeneratedScript
protected KittyDBHelperConfiguration	helperConfiguration
(package private) static int	JELLY_BEAN_ANDROID_VERSION_CODE
protected static java.lang.String	PRAGMA_ON
protected static java.lang.String	QE_RIT

Constructor Summary

Constructors

Constructor and Description
KittyDatabaseHelper(android.content.Context context, KittyDBHelperConfiguration helperCfg, KittyDatabaseConfiguration conf) Create a KittyORM helper object to create, open, and/or manage a database.
KittyDatabaseHelper(android.content.Context context, KittyDBHelperConfiguration helperCfg, KittyDatabaseConfiguration conf, android.database.sqlite.SQLiteDatabase.CursorFactory cursorFactory) Create a helper object to create, open, and/or manage a database.
KittyDatabaseHelper(android.content.Context context, KittyDBHelperConfiguration helperCfg, KittyDatabaseConfiguration conf, android.database.sqlite.SQLiteDatabase.CursorFactory cursorFactory, java.util.LinkedList<KittySQLiteQuery> createSchemaAutogeneratedScript, java.util.LinkedList<KittySQLiteQuery> dropSchemaAutogeneratedScript, KittySQLiteDumpScript afterCreateScript, KittySQLiteDumpScript afterMigrateScript) Create a helper object to create, open, and/or manage a database.

Method Summary

Modifier and Type	Method and Description
protected java.util.LinkedList<KittySQLiteQuery>	acquireBestCreateScriptSequence() Returns best create script sequence available.
protected java.util.LinkedList<KittySQLiteQuery>	acquireBestDropScriptSequence(int oldDatabaseVersion, android.database.sqlite.SQLiteDatabase database) Returns drop tables sequence following those priority: 1) Returning old drop script stored as file in database's assets directory using pattern '{0}-v-{1}-drop.sql' where {0} is schema name and {1} is schema version..
KittyDatabaseHelper	clone()
<T extends KittyDatabaseHelper> T	clone(java.lang.Class<T> recordClass)
protected java.util.LinkedList<KittySQLiteQuery>	generateDropTablesScript(java.lang.String schemaName, android.database.sqlite.SQLiteDatabase database) Returns drop script generated from list of tables acquired via SelectTableNamesQuery.
protected KittySQLiteDumpScript	getAssetsScript(java.lang.String assetPath) Creates and returns KittySQLiteDumpScript implementation designed to be used with this databaseClass helper (from assets)
KittyORMVersionMigrator	getCustomMigratorImplementation(android.database.sqlite.SQLiteDatabase database, int oldVersion, int newVersion) Method for getting custom KittyORMVersionMigrator implementation for this KittyORM database.
protected KittyORMVersionMigrator	getDropCreateVersionMigrator(int oldVersion, int currentVersion, android.database.sqlite.SQLiteDatabase database) Returns default DropCreate migrator that contains only one Migration generated from create and drop statements fetched from acquireBestDropScriptSequence(int, SQLiteDatabase) and acquireBestCreateScriptSequence() if possible (if drop script for old schema version doesn't exists than for getting drop dumped script would be used generateDropTablesScript(String, SQLiteDatabase))
protected KittySQLiteDumpScript	getFileScript(java.lang.String fileUriString, boolean newDump) Creates and returns KittySQLiteDumpScript implementation designed to be used with this databaseClass helper (from fs)
protected KittyORMVersionMigrator	getFileVersionMigrator(int oldVersion, int currentVersion) Returns version migrator from version oldVersion to version currentVersion
protected java.lang.String	getOldDropScriptLocation(KittyDBHelperConfiguration configuration, int oldVersion) Return path (assets or fs) for old drop script using pattern '{0}-v-{1}-drop.sql' where {0} is databaseClass name and {1} is old version integer code with prefix as absolute path to assets schema directory If old script was stored as fs file and new as assets, would be returned path to assets
android.database.sqlite.SQLiteDatabase	getReadableDatabase(java.lang.String pwd) Returns readable databaseClass object created and\or getWritableDatabase with r access and with use of databaseClass encryption implementation
protected java.util.LinkedList<KittySQLiteQuery>	getScriptSequenceFromFileDump(java.lang.String pathToFiledScript) Returns SQLite script sequence from provided file path if possible or null.
protected KittyORMVersionMigrator	getSimpleMigrator(int oldVersion, int currentVersion, android.database.sqlite.SQLiteDatabase database)
android.database.sqlite.SQLiteDatabase	getWritableDatabase(java.lang.String pwd) Returns writable databaseClass object created and\or getWritableDatabase with w access and with use of databaseClass encryption implementation
protected java.lang.String	log(KittyLog.LOG_LEVEL level, java.lang.String pattern, boolean useDefaultFormatter, java.lang.Throwable tr) Simple method for logging in this helper if log is on.
protected void	logQuery(java.lang.String executor, KittySQLiteQuery query)
protected void	migrate(android.database.sqlite.SQLiteDatabase database, KittyORMVersionMigrator migrator, int oldVersion, int currentVersion) Tries to migrate from old db version to current with usage of custom migrator
void	onConfigure(android.database.sqlite.SQLiteDatabase database) Called when the database connection is being configured.
void	onCreate(android.database.sqlite.SQLiteDatabase database) Called when the database is created for the first time.
void	onOpen(android.database.sqlite.SQLiteDatabase database) Called when the database has been opened.
void	onUpgrade(android.database.sqlite.SQLiteDatabase database, int oldVersion, int newVersion) Called when the database needs to be upgraded.
protected void	runScriptSequenceInTransaction(java.util.LinkedList<KittySQLiteQuery> scriptSequence, android.database.sqlite.SQLiteDatabase database) Tries to start transaction and end it.
void	setAfterCreateScript(KittySQLiteDumpScript afterCreateScript) Sets after create schema script sequence as dump script.
void	setAfterMigrateScript(KittySQLiteDumpScript afterMigrateScript) Sets after migrate schema script sequence as dump script.
void	setCreateSchemaAutogeneratedScript(java.util.LinkedList<KittySQLiteQuery> createSchemaAutogeneratedScript) Sets CREATE schema script sequence wrapped into instances of KittySQLiteQuery to be used in onCreate(SQLiteDatabase) and onUpgrade(SQLiteDatabase, int, int).
void	setDropSchemaAutogeneratedScript(java.util.LinkedList<KittySQLiteQuery> dropSchemaAutogeneratedScript) Sets DROP schema script sequence wrapped into instances of KittySQLiteQuery to be used in onUpgrade(SQLiteDatabase, int, int).
protected void	setPragmaKeysAPI15AndLower(android.database.sqlite.SQLiteDatabase db, boolean pragmaKeys) Sets pragma key for Android API 15 and lower If API higher than 15 than nothing happens

Methods inherited from class android.database.sqlite.SQLiteOpenHelper

close, getDatabaseName, getReadableDatabase, getWritableDatabase, onDowngrade, setIdleConnectionTimeout, setLookasideConfig, setWriteAheadLoggingEnabled

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DC_CE_NO_DROP_SEQUENCE

protected static java.lang.String DC_CE_NO_DROP_SEQUENCE

DC_CE_NO_CREATE_SEQUENCE

protected static java.lang.String DC_CE_NO_CREATE_SEQUENCE

JELLY_BEAN_ANDROID_VERSION_CODE

static int JELLY_BEAN_ANDROID_VERSION_CODE

PRAGMA_ON

protected static final java.lang.String PRAGMA_ON

See Also:

Constant Field Values

helperConfiguration

protected final KittyDBHelperConfiguration helperConfiguration

databaseConfiguration

protected final KittyDatabaseConfiguration databaseConfiguration

context

protected final android.content.Context context

createSchemaAutogeneratedScript

protected java.util.LinkedList<KittySQLiteQuery> createSchemaAutogeneratedScript

dropSchemaAutogeneratedScript

protected java.util.LinkedList<KittySQLiteQuery> dropSchemaAutogeneratedScript

afterCreateScript

protected KittySQLiteDumpScript afterCreateScript

afterMigrateScript

protected KittySQLiteDumpScript afterMigrateScript

QE_RIT

protected static final java.lang.String QE_RIT

See Also:

Constant Field Values

Constructor Detail

KittyDatabaseHelper

public KittyDatabaseHelper(android.content.Context context,
                           KittyDBHelperConfiguration helperCfg,
                           KittyDatabaseConfiguration conf)

Create a KittyORM helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase(java.lang.String) or getReadableDatabase(java.lang.String) is called.

(!) There is no need to annotate this class or it's child with KITTY_DATABASE_HELPER annotation. KITTY_DATABASE_HELPER annotation should be applied only to implementations of KittyDatabase.

Parameters:

context - Android context.

helperCfg - KittyORM helper configuration instance.

KittyDatabaseHelper

public KittyDatabaseHelper(android.content.Context context,
                           KittyDBHelperConfiguration helperCfg,
                           KittyDatabaseConfiguration conf,
                           android.database.sqlite.SQLiteDatabase.CursorFactory cursorFactory)

Create a helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase(java.lang.String) or getReadableDatabase(java.lang.String) is called.

(!) There is no need to annotate this class or it's child with KITTY_DATABASE_HELPER annotation. KITTY_DATABASE_HELPER annotation should be applied only to implementations of KittyDatabase.

Parameters:

context - Android context.

helperCfg - KittyORM helper configuration instance.

cursorFactory - cursor factory to use instead default one.

KittyDatabaseHelper

public KittyDatabaseHelper(android.content.Context context,
                           KittyDBHelperConfiguration helperCfg,
                           KittyDatabaseConfiguration conf,
                           android.database.sqlite.SQLiteDatabase.CursorFactory cursorFactory,
                           java.util.LinkedList<KittySQLiteQuery> createSchemaAutogeneratedScript,
                           java.util.LinkedList<KittySQLiteQuery> dropSchemaAutogeneratedScript,
                           KittySQLiteDumpScript afterCreateScript,
                           KittySQLiteDumpScript afterMigrateScript)

Create a helper object to create, open, and/or manage a database. This method always returns very quickly. The database is not actually created or opened until one of getWritableDatabase(java.lang.String) or getReadableDatabase(java.lang.String) is called.

Parameters:

context - Android context.

helperCfg - KittyORM helper configuration instance.

cursorFactory - cursor factory to use instead default one.

createSchemaAutogeneratedScript - predefined create script sequence for this database. See setCreateSchemaAutogeneratedScript(LinkedList) for more details.

dropSchemaAutogeneratedScript - predefined drop script sequence for this database. See setDropSchemaAutogeneratedScript(LinkedList) for more details.

Method Detail

setCreateSchemaAutogeneratedScript

public void setCreateSchemaAutogeneratedScript(java.util.LinkedList<KittySQLiteQuery> createSchemaAutogeneratedScript)

Sets CREATE schema script sequence wrapped into instances of KittySQLiteQuery to be used in onCreate(SQLiteDatabase) and onUpgrade(SQLiteDatabase, int, int).
This script would be used in following cases:
In onCreate(SQLiteDatabase) if getFileScript(String, boolean) returned null (buy default this method returns LinkedList of KittySQLiteQuery fetched from dump file)
In onUpgrade(SQLiteDatabase, int, int) if getFileVersionMigrator(int, int) returned null or helper forced by helper configuration to use drop and created migrator

Parameters:

createSchemaAutogeneratedScript -

setAfterCreateScript

public void setAfterCreateScript(KittySQLiteDumpScript afterCreateScript)

Sets after create schema script sequence as dump script. Script set from this method had higher priority than any script acquired from any other source.

Parameters:

afterCreateScript -

setAfterMigrateScript

public void setAfterMigrateScript(KittySQLiteDumpScript afterMigrateScript)

Sets after migrate schema script sequence as dump script. Script set from this method had higher priority than any script acquired from any other source.

Parameters:

afterMigrateScript -

setDropSchemaAutogeneratedScript

public void setDropSchemaAutogeneratedScript(java.util.LinkedList<KittySQLiteQuery> dropSchemaAutogeneratedScript)

Sets DROP schema script sequence wrapped into instances of KittySQLiteQuery to be used in onUpgrade(SQLiteDatabase, int, int).
This script would be used in following case: In onUpgrade(SQLiteDatabase, int, int) if getFileVersionMigrator(int, int) returned null or helper forced by helper configuration to use drop and created migrator
Also notice, that if you want to use helper onUpgrade method with simple drop create migrator, you can skip this method and ALL tables would be automatically deleted (only setCreateSchemaAutogeneratedScript(LinkedList)) should be set.

Parameters:

dropSchemaAutogeneratedScript -

getWritableDatabase

public android.database.sqlite.SQLiteDatabase getWritableDatabase(java.lang.String pwd)

Returns writable databaseClass object created and\or getWritableDatabase with w access and with use of
databaseClass encryption implementation

Parameters:

pwd - databaseClass password

Returns:

encrypted writable databaseClass object created and\or getWritableDatabase with w access

Throws:

KittyRuntimeException - if call from KittyDatabaseHelper (not implemented here)

getReadableDatabase

public android.database.sqlite.SQLiteDatabase getReadableDatabase(java.lang.String pwd)

Returns readable databaseClass object created and\or getWritableDatabase with r access and with use of
databaseClass encryption implementation

Parameters:

pwd - databaseClass password

Returns:

encrypted readable databaseClass object created and\or getWritableDatabase with r access

Throws:

KittyRuntimeException - if call from KittyDatabaseHelper (not implemented here)

onOpen

public void onOpen(android.database.sqlite.SQLiteDatabase database)

Called when the database has been opened.
In this implementation foreign key support would be set for Android version 15 and lower if necessary.

Overrides:

onOpen in class android.database.sqlite.SQLiteOpenHelper

Parameters:

database -

onConfigure

public void onConfigure(android.database.sqlite.SQLiteDatabase database)

Called when the database connection is being configured. In this implementation foreign keys support enabled for Android versions 16 and higher via setPragmaKeysAPI16(SQLiteDatabase, boolean)

Overrides:

onConfigure in class android.database.sqlite.SQLiteOpenHelper

Parameters:

database - database instance.

onCreate

public void onCreate(android.database.sqlite.SQLiteDatabase database)

Called when the database is created for the first time. This is where the creation of tables and the initial population of the tables happens.
In default kitty orm helper in this void are handled following things:
1) Getting create script with acquireBestCreateScriptSequence(), if it would be null than exception (KittyRuntimeException) would be thrown.
2) Trying to run this script via runScriptSequenceInTransaction(LinkedList, SQLiteDatabase), if it failed than exception (KittyRuntimeException) would be thrown.

Specified by:

onCreate in class android.database.sqlite.SQLiteOpenHelper

Parameters:

database - The database.

onUpgrade

public void onUpgrade(android.database.sqlite.SQLiteDatabase database,
                      int oldVersion,
                      int newVersion)

Called when the database needs to be upgraded. In this implementation it does following things:
1) Checking that oldVersion less or equal newVersion, if false that method would return.
2) Based on helper configuration defined in KITTY_DATABASE_HELPER starts upgrading routine. If something failed than KittyRuntimeException would be thrown.
So, according to KittyDBHelperConfiguration.onUpgradeBehavior it would try to get simple DropCreate migrator with getDropCreateVersionMigrator(int, int, SQLiteDatabase) or file dump migrator with getFileVersionMigrator(int, int) or user predefined migrator with implemented by developer getCustomMigratorImplementation(SQLiteDatabase, int, int).
Or do nothing and return.
After migrator instance was acquired it would be used in migrate(SQLiteDatabase, KittyORMVersionMigrator, int, int) method. If something failed than KittyRuntimeException would be thrown.

Specified by:

onUpgrade in class android.database.sqlite.SQLiteOpenHelper

Parameters:

database - The database.

oldVersion - The old database version.

newVersion - The new database version.

getCustomMigratorImplementation

public KittyORMVersionMigrator getCustomMigratorImplementation(android.database.sqlite.SQLiteDatabase database,
                                                               int oldVersion,
                                                               int newVersion)

Method for getting custom KittyORMVersionMigrator implementation for this KittyORM database. Not implemented in this helper implementation and usage of this method would cause KittyRuntimeException be thrown. To use this method you should manually overload this method in child implementation.

Parameters:

database - The database.

oldVersion - The old database version.

newVersion - The new database version.

Returns:

custom migrator implementation.

migrate

protected void migrate(android.database.sqlite.SQLiteDatabase database,
                       KittyORMVersionMigrator migrator,
                       int oldVersion,
                       int currentVersion)

Tries to migrate from old db version to current with usage of custom migrator

Parameters:

database - databaseClass object

migrator - to use

oldVersion - old version of databaseClass

currentVersion - current version of databaseClass

Throws:

KittyRuntimeException - if migration sequence not applicable for input db and schema versions

getFileVersionMigrator

protected KittyORMVersionMigrator getFileVersionMigrator(int oldVersion,
                                                         int currentVersion)

Returns version migrator from version oldVersion to version currentVersion

Parameters:

oldVersion - old databaseClass version

currentVersion - current databaseClass version

Returns:

migrator for databaseClass versions if possible

getSimpleMigrator

protected KittyORMVersionMigrator getSimpleMigrator(int oldVersion,
                                                    int currentVersion,
                                                    android.database.sqlite.SQLiteDatabase database)

getDropCreateVersionMigrator

protected KittyORMVersionMigrator getDropCreateVersionMigrator(int oldVersion,
                                                               int currentVersion,
                                                               android.database.sqlite.SQLiteDatabase database)

Returns default DropCreate migrator that contains only one Migration generated
from create and drop statements fetched from acquireBestDropScriptSequence(int, SQLiteDatabase)
and acquireBestCreateScriptSequence() if possible (if drop script for old schema version
doesn't exists than for getting drop dumped script would be used generateDropTablesScript(String, SQLiteDatabase))

Parameters:

oldVersion - old databaseClass version

currentVersion - current databaseClass version

Returns:

default drop-create migrator implementation

acquireBestCreateScriptSequence

protected java.util.LinkedList<KittySQLiteQuery> acquireBestCreateScriptSequence()

Returns best create script sequence available.
If possible - returns create script from file dump, else - predefined create script.
File dump script stored as file in database's assets directory using pattern '{0}-v-{1}-create.sql' where {0} is schema name and {1} is schema version.
Full filepath would be: file:///android_asset/kittysqliteorm/{0}/{1}-v-{2}-create.sql where {0} and {1} is schema name and {2} is schema version

Returns:

if possible - returns create script from file dump, else - predefined create script.

acquireBestDropScriptSequence

protected java.util.LinkedList<KittySQLiteQuery> acquireBestDropScriptSequence(int oldDatabaseVersion,
                                                                               android.database.sqlite.SQLiteDatabase database)

Returns drop tables sequence following those priority:
1) Returning old drop script stored as file in database's assets directory using pattern '{0}-v-{1}-drop.sql' where {0} is schema name and {1} is schema version.. If not possible than step 2.
Full filepath would be: file:///android_asset/kittysqliteorm/{0}/{1}-v-{2}-drop.sql where {0} and {1} is schema name and {2} is schema version
2) Returning drop sequence set by kitty DB instance into current helper. If not possible than step 3.
3) Returning drop sequence from generateDropTablesScript(String, SQLiteDatabase). If not possible than step 4.
4) Return null.

Returns:

best drop sequence for policy described as comment for this method or null if not possible.

generateDropTablesScript

protected java.util.LinkedList<KittySQLiteQuery> generateDropTablesScript(java.lang.String schemaName,
                                                                          android.database.sqlite.SQLiteDatabase database)

Returns drop script generated from list of tables acquired via SelectTableNamesQuery.
Or null if cursor was null.

Parameters:

database -

Returns:

runScriptSequenceInTransaction

protected void runScriptSequenceInTransaction(java.util.LinkedList<KittySQLiteQuery> scriptSequence,
                                              android.database.sqlite.SQLiteDatabase database)

Tries to start transaction and end it. If any problem acquired while running transaction

Parameters:

scriptSequence -

database -

getOldDropScriptLocation

protected java.lang.String getOldDropScriptLocation(KittyDBHelperConfiguration configuration,
                                                    int oldVersion)

Return path (assets or fs) for old drop script using pattern '{0}-v-{1}-drop.sql' where {0} is databaseClass name
and {1} is old version integer code with prefix as absolute path to assets schema directory
If old script was stored as fs file and new as assets, would be returned path to assets

Parameters:

configuration - helper configuration

oldVersion - old version integer code

Returns:

name for old drop script

getScriptSequenceFromFileDump

protected java.util.LinkedList<KittySQLiteQuery> getScriptSequenceFromFileDump(java.lang.String pathToFiledScript)

Returns SQLite script sequence from provided file path if possible or null.
If log on then on any errors where would be log output.

Parameters:

pathToFiledScript -

Returns:

getAssetsScript

protected KittySQLiteDumpScript getAssetsScript(java.lang.String assetPath)

Creates and returns KittySQLiteDumpScript implementation designed to be used
with this databaseClass helper (from assets)

Parameters:

assetPath -

Returns:

getFileScript

protected KittySQLiteDumpScript getFileScript(java.lang.String fileUriString,
                                              boolean newDump)

Creates and returns KittySQLiteDumpScript implementation designed to be used
with this databaseClass helper (from fs)

Parameters:

fileUriString - fileUriString object that contains path to readable fileUriString with dumped script

newDump - flag that shows if this dump fileUriString is new and can be empty\not existing

Returns:

dump script

log

protected java.lang.String log(KittyLog.LOG_LEVEL level,
                               java.lang.String pattern,
                               boolean useDefaultFormatter,
                               java.lang.Throwable tr)

Simple method for logging in this helper if log is on. Returns pattern parameter if no formatting should be used or formatted string where:
{0} is value for Object.getClass() canonical name
{1} is value for KittyDBHelperConfiguration.schemaName
{2} is value for KittyDBHelperConfiguration.schemaVersion

Parameters:

level -

pattern -

useDefaultFormatter -

tr - any throwable, may be null

Returns:

setPragmaKeysAPI15AndLower

protected final void setPragmaKeysAPI15AndLower(android.database.sqlite.SQLiteDatabase db,
                                                boolean pragmaKeys)

Sets pragma key for Android API 15 and lower If API higher than 15 than nothing happens

Parameters:

db - databaseClass object

pragmaKeys - pragma on flag

logQuery

protected final void logQuery(java.lang.String executor,
                              KittySQLiteQuery query)

clone

public final <T extends KittyDatabaseHelper> T clone(java.lang.Class<T> recordClass)

clone

public KittyDatabaseHelper clone()

Overrides:

clone in class java.lang.Object