The Support Database API

So far, this book has portrayed Room as being an ORM-style bridge between your code and SQLite.

Technically, that is not accurate.

Part of what we get with Room is a series of classes and interfaces in the android.support.persistence.db package. These classes come from a separate artifact (android.arch.persistence.room:support-db) and represent an abstraction for SQLite-style database access. This book will refer to this as “the support database API”.

We also get implementations of that abstraction, in the form of the “framework” classes (from android.arch.persistence.room:support-db-impl). Those classes use the Android standard SQLite environment. Room’s artifacts pull in these support artifacts by default, and when we use RoomDatabase.Builder to set up our RoomDatabase, we are using those “framework” classes for the database access.

In this chapter, we will explore in greater detail why this support database API exists and how we can use it, because while most of the time we will be able to use Room-generated code to work with the database, sometimes we cannot.

“Can’t You See That This is a Facade?”

To many developers, SQLite “is what it is”. Android ships with a SQLite implementation, and we use it, either directly or via some form of wrapper library.

However, in truth, there are many SQLite implementations. After all, SQLite is a library, and so there is nothing stopping people from using a separate, independent copy of SQLite from what is in Android. Even in Android itself, what SQLite you get depends on what device you run on:

• Different API levels integrate different versions of SQLite
• Device manufacturers sometimes replace the stock SQLite version with another

And so, sometimes, we need a facade: an API that we can code to that supports a pluggable implementation. The following sections outline some examples.

Requery

Requery is a Room-like object mapping library, one that works both on Android and on the regular Java JVM. For plain Java (or Kotlin), Requery uses JDBC. For Android, Requery integrates with the support database API. Beyond that, Requery offers its own implementation of that API, wrapped around a standalone copy of SQLite. This ensures that you are using a current version of SQLite, even on older devices.

CWAC-SafeRoom

One of the best-known alternative SQLite implementations for Android is Zetitec’s SQLCipher for Android, which offers transparent encryption of database contents. However, Room knows nothing about SQLCipher for Android… which is why the author of this book wrote CWAC-SafeRoom. The bulk of CWAC-SafeRoom is an implementation of the support database API that completely replaces the use of the framework SQLite with SQLCipher for Android.

AssetRoom

Sometimes, you may want to package a database with the app, either as starter data or as a read-only data source. Jeff Gilfelt’s SQLiteAssetHelper can handle this for you, but Room does not know about it.

The General/AssetRoom sample app profiled in another chapter contains a partial implementation of the support database API. Mostly, it is a pass-through to the stock implementation of that API that uses the framework’s copy of SQLite. However, it uses a modified version of SQLiteAssetHelper to handle the timely unpacking of a database stored in assets/.

Other ORMs

Both of those use cases offer other implementations of the support database API. The idea is that not only can Room use that API, but so could other similar object-relational mapping (ORM) libraries. If those libraries write to the support database API and allow pluggable implementations the way that Room does, then solutions like CWAC-SafeRoom can work for those libraries in the same way that it works for Room itself.