Elements of Android Room (Mark L. Murphy) (z-library.sk, 1lib.sk, z-lib.sk) (1)

Elements of Android Room by Mark L. Murphy

Elements of Android Room by Mark L. Murphy Copyright © 2019-2021 CommonsWare, LLC. All Rights Reserved. Printed in the United States of America. Printing History: March2021: Version 0.5 The CommonsWare name and logo, “Busy Coder's Guide”, and related trade dress are trademarks of CommonsWare, LLC. All other trademarks referenced in this book are trademarks of their respective firms. The publisher and author(s) assume no responsibility for errors or omissions or for damages resulting from the use of the information contained herein.

Table of Contents Headings formatted in bold-italic have changed since the last version. • Preface ◦ The Book’s Prerequisites ....................................................................... v ◦ About the Updates ................................................................................ vi ◦ What’s New in Version 0.5? ........................................................ vi ◦ Warescription ....................................................................................... vi ◦ Book Bug Bounty ................................................................................ vii ◦ Source Code and Its License ............................................................. viii ◦ Creative Commons and the Four-to-Free (42F) Guarantee .... viii ◦ Acknowledgments ................................................................................ ix • Room Basics ◦ Wrenching Relations Into Objects ....................................................... 1 ◦ Room Requirements .............................................................................. 2 ◦ Room Furnishings .................................................................................. 3 ◦ Get a Room ............................................................................................ 8 ◦ Testing Room ........................................................................................ 8 • The Dao of Entities ◦ Configuring Entities ............................................................................. 13 ◦ DAOs and Queries ............................................................................... 29 ◦ Dynamic Queries ................................................................................. 37 ◦ Other DAO Operations ....................................................................... 39 ◦ Transactions and Room ....................................................................... 42 • Room and Custom Types ◦ Type Converters ................................................................................... 45 ◦ Embedded Types .................................................................................. 51 • Room and Reactive Frameworks ◦ Room and the Main Application Thread ........................................... 55 ◦ Room and LiveData ............................................................................. 57 ◦ Room and Coroutines .......................................................................... 59 ◦ Room and RxJava ................................................................................. 63 ◦ Observable Queries ............................................................................. 65 ◦ Room and ListenableFuture ................................................................ 65 ◦ Where Synchronous Room is Safe ..................................................... 66 ◦ Being Evil ............................................................................................. 66 • Relations in Room ◦ The Classic ORM Approach ................................................................ 67 i

◦ A History of Threading Mistakes ....................................................... 68 ◦ The Room Approach .......................................................................... 69 ◦ One-to-Many Relations ...................................................................... 69 ◦ Many-to-Many Relations ..................................................................... 75 ◦ Room Entities as DTOs ....................................................................... 79 • The Support Database API ◦ “Can’t You See That This is a Facade?” ............................................... 81 ◦ When Will We Use This? .................................................................... 82 ◦ Configuring Room’s Database Access ................................................. 83 • Database Migrations ◦ What’s a Migration? ............................................................................ 87 ◦ When Do We Migrate? ....................................................................... 88 ◦ But First, a Word About Exporting Schemas .................................... 88 ◦ Writing Migrations .............................................................................. 91 ◦ Employing Migrations ......................................................................... 92 ◦ How Room Applies Migrations ........................................................... 93 ◦ Testing Migrations .............................................................................. 94 • Polymorphic Entities ◦ Polymorphism With Separate Tables ............................................... 103 ◦ Polymorphism With a Single Table .................................................. 109 • Default Values and Partial Entities ◦ Default Values, and the Other Default Values ................................. 115 ◦ Default Values and Inserts ................................................................. 116 ◦ Partial Entities .................................................................................... 117 • Room and Full-Text Search ◦ What Is FTS? ....................................................................................... 121 ◦ Applying FTS to Room ....................................................................... 123 ◦ Supported MATCH Syntax ................................................................. 132 ◦ Migrating to FTS ................................................................................. 132 • Room and Conflict Resolution ◦ Abort ................................................................................................... 136 ◦ Fail ...................................................................................................... 138 ◦ Ignore ................................................................................................. 138 ◦ Replace ............................................................................................... 139 ◦ Rollback .............................................................................................. 140 ◦ What Should You Use with Room? .................................................. 140 • Room and PRAGMAs ◦ When To Make Changes ........................................................... 143 ◦ Example: Turbo Boost Mode .................................................... 144 • Packaged Databases ◦ Going Back In Time ........................................................................... 147 ii

◦ The Room Mechanics ........................................................................ 148 ◦ Creating the Database Asset ............................................................. 149 ◦ Dealing With Metadata and Upgrades ............................................. 151 ◦ Hybrid Data ......................................................................................... 151 • Backing Up Your Room ◦ Backup and Restore. Or, Import and Export. ................................... 153 ◦ Choosing a Storage Target ................................................................. 154 ◦ Thinking About Journal Modes ........................................................ 154 ◦ Keeping It Closed ................................................................................ 155 ◦ Import and Export Mechanics .......................................................... 156 ◦ The createFromFile() Alternative ..................................................... 159 • SQLite Clients ◦ Database Inspector ................................................................. 161 ◦ DB Browser for SQLite ...................................................................... 166 ◦ Flipper ...................................................................................... 168 • SQLCipher for Android ◦ Introducing SQLCipher for Android ................................................. 177 ◦ But First, A To-Do Reminder ............................................................ 178 ◦ The Basics of SQLCipher for Android .............................................. 182 ◦ The Costs of SQLCipher for Android ............................................... 184 • SQLCipher and Passphrases ◦ Generating a Passphrase ......................................................... 187 ◦ Collecting a Passphrase ..................................................................... 192 ◦ Multi-Factor Authentication ............................................................ 200 ◦ The Risks of String ............................................................................. 201 • Managing SQLCipher ◦ Backup and Restore ................................................................ 203 ◦ Migrating to Encryption .......................................................... 215 • Paged Room Queries ◦ The Problem: Too Much Data ............................................................ 221 ◦ Addressing the UX ............................................................................. 222 ◦ Enter the Paging Library ................................................................... 223 ◦ Paging and Room ............................................................................... 224 ◦ Hey, What About Errors? ........................................................ 230 iii

Preface Thanks! Thanks for your interest in Room! Room is Google’s solution for a high-level database access API, for your local SQLite databases. As such, Room gets a lot of attention and is reasonably popular. Thanks also for your broader interest in Android app development! Android is the most widely-used operating system on the planet, so we need to be able to rapidly develop high-quality Android apps. Room can help with that. And thanks for your interest in this book! Here, you can learn more about how to work with Room, from the basics through more complex scenarios. And, along the way, there may be a joke or two. The Book’s Prerequisites This book is designed for developers with at least a bit of Android app development experience. If you are fairly new to Android, please consider reading Elements of Android Jetpack, Exploring Android, or both, before continuing with this book. Also note that this book’s examples are written in Kotlin. If you are unfamiliar with Kotlin, you can still learn stuff about Room from this book, though it will be more difficult. You might consider reading Elements of Kotlin, to familiarize yourself with Kotlin. v

About the Updates If you obtained this book through the Warescription, you will be able to download updates as they become available, for the duration of your subscription period. If you obtained this book through other channels… um, well, it’s still a really nice book! Each release has notations to show what is new or changed compared with the immediately preceding release: • The Table of Contents in the ebook formats (PDF, EPUB, MOBI/Kindle) shows sections with changes in bold-italic font • Those sections have changebars on the right to denote specific paragraphs that are new or modified And, there is the “What’s New” section, just below this paragraph. What’s New in Version 0.5? This update adds two more chapters, covering: • Executing PRAGMAs as part of starting up Room • SQLCipher for Android management, including backup/restore In addition: • A bunch of dependencies were updated, notably Room itself • Various bugs were fixed Warescription If you purchased the Warescription, read on! If you obtained this book from other channels, feel free to jump ahead. The Warescription entitles you, for the duration of your subscription, to digital editions of this book and its updates, in PDF, EPUB, and Kindle (MOBI/KF8) formats, plus the ability to read the book online at the Warescription Web site. You also have access to other books that CommonsWare publishes during that PREFACE vi

subscription period. Each subscriber gets personalized editions of all editions of each title. That way, your books are never out of date for long, and you can take advantage of new material as it is made available. However, you can only download the books while you have an active Warescription. There is a grace period after your Warescription ends: you can still download the book until the next book update comes out after your Warescription ends. After that, you can no longer download the book. Hence, please download your updates as they come out. You can find out when new releases of this book are available via: 1. The CommonsBlog 2. The CommonsWare Twitter feed 3. Opting into emails announcing each book release — log into the Warescription site and choose Configure from the nav bar 4. Just check back on the Warescription site every month or two Subscribers also have access to other benefits, including: • “Office hours” — online chats to help you get answers to your Android application development questions. You will find a calendar for these on your Warescription page. • A Stack Overflow “bump” service, to get additional attention for a question that you have posted there that does not have an adequate answer. • A discussion board for asking arbitrary questions about Android app development. Book Bug Bounty Find a problem in the book? Let CommonsWare know! Be the first to report a unique concrete problem in the current edition, and CommonsWare will extend your Warescription by six months as a bounty for helping CommonsWare deliver a better product. By “concrete” problem, we mean things like: 1. Typographical errors PREFACE vii

2. Sample applications that do not work as advertised, in the environment described in the book 3. Factual errors that cannot be open to interpretation By “unique”, we mean ones not yet reported. Be sure to check the book’s errata page, though, to see if your issue has already been reported. One coupon is given per email containing valid bug reports. We appreciate hearing about “softer” issues as well, such as: 1. Places where you think we are in error, but where we feel our interpretation is reasonable 2. Places where you think we could add sample applications, or expand upon the existing material 3. Samples that do not work due to “shifting sands” of the underlying environment (e.g., changed APIs with new releases of an SDK) However, those “softer” issues do not qualify for the formal bounty program. Questions about the bug bounty, or problems you wish to report for bounty consideration, should be sent to bounty@commonsware.com. Source Code and Its License The source code in this book is licensed under the Apache 2.0 License, in case you have the desire to reuse any of it. Copying source code directly from the book, in the PDF editions, works best with Adobe Reader, though it may also work with other PDF viewers. Some PDF viewers, for reasons that remain unclear, foul up copying the source code to the clipboard when it is selected. Creative Commons and the Four-to-Free (42F) Guarantee Each CommonsWare book edition will be available for use under the Creative Commons Attribution-Noncommercial-ShareAlike 3.0 license as of the fourth anniversary of its publication date, or when 4,000 copies of the edition have been sold, whichever comes first. That means that, once four years have elapsed (perhaps PREFACE viii

sooner!), you can use this prose for non-commercial purposes. That is our Four-to- Free Guarantee to our readers and the broader community. For the purposes of this guarantee, new Warescriptions and renewals will be counted as sales of this edition, starting from the time the edition is published. This edition of this book will be available under the aforementioned Creative Commons license on 1 March 2025. Of course, watch the CommonsWare Web site, as this edition might be relicensed sooner based on sales. For more details on the Creative Commons Attribution-Noncommercial-ShareAlike 3.0 license, visit the Creative Commons Web site Note that future editions of this book will become free on later dates, each four years from the publication of that edition or based on sales of that specific edition. Releasing one edition under the Creative Commons license does not automatically release all editions under that license. Acknowledgments The author would like to thank Daniel Rivera, Yiğit Boyar, and the rest of the developers at Google responsible for Room. The author would also like to thank Stephen Lombardo, Nick Parker, and the rest of Zetetic, plus Nathan Frietas, Hans-Cristoph Steiner, and the rest of the Guardian Project, for all their work on SQLCipher for Android and general Android app security. PREFACE ix

Introductory Room

Room Basics Google describes Room as providing “an abstraction layer over SQLite to allow fluent database access while harnessing the full power of SQLite.” In other words, Room aims to make your use of SQLite easier, through a lightweight annotation-based implementation of an object-relational mapping (ORM) engine. Wrenching Relations Into Objects If you have ever worked with a relational database — like SQLite — from an object- oriented language — like Java or Kotlin — undoubtedly you have encountered the “object-relational impedance mismatch”. That is a very fancy way of saying “it’s a pain getting stuff into and out of the database”. In object-oriented programming, we are used to objects holding references to other objects, forming some sort of object graph. However, traditional SQL-style relational databases work off of tables of primitive data, using foreign keys and join tables to express relationships. Figuring out how to get our classes to map to relational tables is aggravating, and it usually results in a lot of boilerplate code. Traditional Android development uses SQLiteDatabase for interacting with SQLite. That, in turn, uses Cursor objects to represent the results of queries and ContentValues objects to represent data to be inserted or updated. While Cursor and ContentValues are objects, they are fairly generic, much in the way that a HashMap or ArrayList is generic. In particular, neither Cursor nor ContentValues has any of our business logic. We have to somehow either wrap that around those objects or convert between those objects and some of ours. That latter approach is what object-relational mapping engines (ORMs) take. A 1

typical ORM works off of Java/Kotlin code and either generates a suitable database structure or works with you to identify how the classes should map to some existing table structure (e.g., a legacy one that you are stuck with). The ORM usually generates some code for you, and supplies a library, which in combination hide much of the database details from you. The quintessential Java ORM is Hibernate. However, Hibernate was developed with server-side Java in mind and is not well-suited for slim platfoms like Android devices. However, a vast roster of Android ORMs and similar libraries have been created over the years to try to fill that gap. Some of the more popular ones have been: • SQLDelight • DBFlow • greenDAO • OrmLite • Sugar ORM Room also helps with the object-relational impedance mismatch. It is not as deep of an ORM as some of the others, as you will be dealing with SQL a fair bit. However, Room has one huge advantage: it is from Google, and therefore it will be deemed “official” in the eyes of many developers and managers. While this book is focused on Room, you may wish to explore other ORMs if you are interested in using Java/Kotlin objects but saving the data in SQLite. Room is popular, but it is far from the only option. In particular, if you are interested in Kotlin/Multiplatform for cross-platform development, you will want to look at SQLDelight, so your database operations can also be cross-platform. Room Requirements To use Room, you need two dependencies in your module’s build.gradle file: 1. The runtime library 2. An annotation processor In a Kotlin project, those will be: • room-ktx, to pull in the core Room runtime libraries plus some Kotlin- specific extensions ROOM BASICS 2

• room-compiler, used with kapt For example, in the NoteBasics module of the book’s primary sample project, we have a build.gradle file that pulls in those two artifacts: apply plugin: 'com.android.library' apply plugin: 'kotlin-android' apply plugin: 'kotlin-kapt' android { compileSdkVersion 30 defaultConfig { minSdkVersion 21 targetSdkVersion 30 versionCode 1 versionName "1.0" testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner" } buildTypes { release { minifyEnabled false proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } } dependencies { implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version" implementation "androidx.appcompat:appcompat:1.2.0" implementation "androidx.core:core-ktx:1.3.2" implementation "androidx.constraintlayout:constraintlayout:2.0.4" implementation "androidx.room:room-ktx:$room_version" kapt "androidx.room:room-compiler:$room_version" androidTestImplementation "androidx.test.ext:junit:1.1.2" androidTestImplementation 'androidx.test:runner:1.3.0' androidTestImplementation "androidx.arch.core:core-testing:2.1.0" androidTestImplementation "com.natpryce:hamkrest:1.7.0.0" } (from NoteBasics/build.gradle) Note that Room has a minSdkVersion requirement of API Level 15 or higher. If you attempt to build with a lower minSdkVersion, you will get a build error. If you try to override Room’s minSdkVersion using manifest merger elements, while the project will build, expect Room to crash horribly. Room Furnishings Roughly speaking, your use of Room is dominated by three sets of classes: ROOM BASICS 3

1. Entities, which are simple classes that model the data you are transferring into and out of the database 2. The data access object (DAO), that provides the description of the API that you want for working with certain entities 3. The database, which ties together all of the entities and DAOs for a single SQLite database If you have used Square’s Retrofit, some of this will seem familiar: • The DAO is roughly analogous to your Retrofit interface on which you declare your Web service API • Your entities are the POJOs that you are expecting Gson/Moshi/whatever to create based on the Web service response The NoteBasics module mentioned above has a few classes related to a note-taking application, exercised via instrumented tests. Entities In many ORM systems, the entity (or that system’s equivalent) is a simple class that you happen to want to store in the database. It usually represents some part of your overall domain model, so a payroll system might have entities representing departments, employees, and paychecks. With Room, a better description of entities is that they are classes representing: • the data that you want to store into a table, and • a typical unit of a result set that you are trying to retrieve from the database That difference may sound academic. It starts to come into play a bit more when we start thinking about relations. However, it also more closely matches the way Retrofit maps to Web services. With Retrofit, we are not describing the contents of the Web service’s database. Rather, we are describing how we want to work with defined Web service endpoints. Those endpoints have a particular set of content that we can work with, courtesy of whoever developed the Web service. We are simply mapping those to methods and classes, both for input and output. Room is somewhere in between a Retrofit-style “we just take what the Web service gives us” approach and a full ORM-style “we control everything about the database” approach. ROOM BASICS 4

From a coding standpoint, an entity is a Java/Kotlin class marked with the @Entity annotation. For example, here is a NoteEntity class that serves as a Room entity: package com.commonsware.room.notes import androidx.room.Entity import androidx.room.PrimaryKey @Entity(tableName = "notes") data class NoteEntity( @PrimaryKey val id: String, val title: String, val text: String, val version: Int ) (from NoteBasics/src/main/java/com/commonsware/room/notes/NoteEntity.kt) There is no particular superclass required for entities, and the expectation is that often they will be simple data classes, as we see here. The @Entity annotation can have properties customizing the behavior of your entity and how Room works with it. In this case, we have a tableName property. The default name of the SQLite table is the same as the entity class name, but tableName allows you to override that and supply your own table name. Here, we override the table name to be notes. Sometimes, your properties will be marked with annotations describing their roles. In this example, the id field has the @PrimaryKey annotation, telling Room that this is the unique identifier for this entity. Room will use that to know how to update and delete Note objects by their primary key values. In Java, Room also requires that any @PrimaryKey field of an object type — like String — be annotated with @NonNull, as primary keys in SQLite cannot be null. In Kotlin, you can just use a non-nullable type, such as String. We will explore entities in greater detail in an upcoming chapter. DAO “Data access object” (DAO) is a fancy way of saying “the API into the data”. The idea is that you have a DAO that provides methods for the database operations that you need: queries, inserts, updates, deletes, and so on. ROOM BASICS 5