[译] Realm 的使用入门

原文链接：https://docs.mongodb.com/realm/sdk/android/quick-start-local/

一、初始化Realm

必须先初始化 Realm 库，然后才能在应用程序中使用 Realm。您的应用程序每次运行时都应该仅初始化一次 Realm。

要初始化 Realm 库，请将 Android context 提供给 Realm.init() static 函数。您可以提供一个 Activity，Fragment 或 Application context 进行初始化，而在行为上没有差异。您可以在 Application子类 的 onCreate() 方法中初始化 Realm 库，以确保每次应用程序运行时仅对 Realm 进行一次初始化。

Realm.init(this) // context, usually an Activity or Application

二、定义你的对象模型

您的应用程序的数据模型定义了存储在 Realm 数据库中的数据的结构。您可以使用 Realm Object Models 在应用程序代码中通过 Kotlin 或 Java 类定义应用程序的数据模型。

要定义您的应用程序的数据模型，请在您的应用程序代码中添加以下类定义：

enum class TaskStatus(val displayName: String) {
    Open("Open"),
    InProgress("In Progress"),
    Complete("Complete"),
}

open class Task() : RealmObject() {
    @PrimaryKey
    var name: String = "task"

    @Required
    var status: String = TaskStatus.Open.name
    var statusEnum: TaskStatus
        get() {
            // because status is actually a String and another client could assign an invalid value,
            // default the status to "Open" if the status is unreadable
            return try {
                TaskStatus.valueOf(status)
            } catch (e: IllegalArgumentException) {
                TaskStatus.Open
            }
        }
        set(value) { status = value.name }
}

三、打开一个 Realm

使用 RealmConfiguration 控制你想打开 Realm 的特定需求，包括名称或 Realm 数据库的位置，是否允许在UI线程上同步读取或写入一个 realm 数据，等等。

val realmName: String = "My Project"
val config = RealmConfiguration.Builder().name(realmName).build()

val backgroundThreadRealm : Realm = Realm.getInstance(config)

四、创建，读取，更新和删除对象

打开 Realm 后，您可以在写事务块中修改该 Realm 内的 对象。

要创建一个新的 Task，实例化 Task 类的实例，并在写事务块中将其添加到 Realm 中：

val task : Task = Task()
task.name = "New Task"
backgroundThreadRealm.executeTransaction { transactionRealm ->
    transactionRealm.insert(task)
}

您可以检索 Realm 中所有条目的活跃集合：

// all tasks in the realm
val tasks : RealmResults<Task> = backgroundThreadRealm.where<Task>().findAll()

您还可以使用过滤器过滤该集合：

// you can also filter a collection
val tasksThatBeginWithN : List<Task> = tasks.where().beginsWith("name", "N").findAll()
val openTasks : List<Task> = tasks.where().equalTo("status", TaskStatus.Open.name).findAll()

要修改一个 Task，请在写事务块中更新其属性：

val otherTask: Task = tasks[0]!!

// all modifications to a realm must happen inside of a write block
backgroundThreadRealm.executeTransaction { transactionRealm ->
    val innerOtherTask : Task = transactionRealm.where<Task>().equalTo("name", otherTask.name).findFirst()!!
    innerOtherTask.status = TaskStatus.Complete.name
}

最后，您可以在写事务块中调用 deleteFromRealm() 方法来删除一个 Task：

val yetAnotherTask: Task = tasks.get(0)!!
val yetAnotherTaskName: String = yetAnotherTask.name
// all modifications to a realm must happen inside of a write block
backgroundThreadRealm.executeTransaction { transactionRealm ->
    val innerYetAnotherTask : Task = transactionRealm.where<Task>().equalTo("name", yetAnotherTaskName).findFirst()!!
    innerYetAnotherTask.deleteFromRealm()
}

五、监听变化

您可以通过附加自定义的 OrderedRealmCollectionChangeListeneraddChangeListener() 方法 ，以监听一个 Realm，集合或对象的更改：

// all tasks in the realm
val tasks : RealmResults<Task> = realm.where<Task>().findAllAsync()

tasks.addChangeListener(OrderedRealmCollectionChangeListener<RealmResults<Task>> { collection, changeSet ->
    // process deletions in reverse order if maintaining parallel data structures so indices don't change as you iterate
    val deletions = changeSet.deletionRanges
    for (i in deletions.indices.reversed()) {
        val range = deletions[i]
        Log.v("QUICKSTART", "Deleted range: ${range.startIndex} to ${range.startIndex + range.length - 1}")
    }

    val insertions = changeSet.insertionRanges
    for (range in insertions) {
        Log.v("QUICKSTART", "Inserted range: ${range.startIndex} to ${range.startIndex + range.length - 1}")
    }

    val modifications = changeSet.changeRanges
    for (range in modifications) {
        Log.v("QUICKSTART", "Updated range: ${range.startIndex} to ${range.startIndex + range.length - 1}")
    }
})