【译】ObjectBox官方文档(1)——简介与配置

易博文
2023-12-01

转载请注明出处

第一次翻译文档,水平有限,如有任何错误和不妥,望指正。此外如想知道与Realm 和 GreenDAO的对比请查看这篇博客 官方示例:Github

简介

ObjectBox 是一个移动端方便快速的数据库框架,它让你避免了很多重复的工作,并为你提供简单易用的接口调用。同时他还支持 KotlinRxjava

Gradle配置

为了在您的 Android 项目中使用 ObjectBox ,您需要添加其 Gradle 插件和依赖库:

// 在你的根目录 build.gradle 文件:
buildscript {
    ext.objectboxVersion = '1.0.1' // 检查最新版本
    repositories {
        jcenter()
        maven { url "http://objectbox.net/beta-repo/" }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.3.3'
        classpath "io.objectbox:objectbox-gradle-plugin:$objectboxVersion"
    }
}
 
allprojects {
    repositories {
        jcenter()
        maven { url "http://objectbox.net/beta-repo/" }
    }
}
 
// 在你的 Moudle 的 build.gradle 文件中:
apply plugin: 'com.android.application'
apply plugin: 'io.objectbox'
复制代码

Gradle 插件自动添加 ObjectBox 库依赖,并配置一个注释处理器,它将在构建时生成代码和 JSON 数据元模型文件。

然后创建你的实体类并编译您的项目,例如在 Android Studio 中使用 Build> Make Project。

如果由于某些原因,库或注释处理器没有被 Gradle 插件自动添加到依赖项中,您可以手动添加它们。对于处理器,Java 项目使用 annotationProcessor 关键字,如果您的项目使用 Kotlin,则使用 kapt 关键字:

dependencies {
    // 以下依赖应该被插件自动添加
 
    compile "io.objectbox:objectbox-android:$objectboxVersion"

    annotationProcessor "io.objectbox:objectbox-processor:$objectboxVersion"

	// 一些有用的Kotlin扩展函数
    // compile "io.objectbox:objectbox-kotlin:$objectboxVersion"
 
    // 当使用Kotlin时使用kapt:
    // kapt "io.objectbox:objectbox-processor:$objectboxVersion"
}
复制代码

可选配置

在您的 Moudlebuild.gradle 文件中,您可以添加一些可选配置。例如,您可以打开 ObjectBox 注解处理器的调试模式(然后使用- info 选项运行 Gradle 查看调试输出):

// Using annotationProcessor (Java):
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = [ 'objectbox.debug' : 'true' ]
            }
        }
    }
}
// Using kapt (Kotlin):
kapt {
    arguments {
        arg("objectbox.debug", true)
    }
}
复制代码

其他注释处理器参数:

  • objectbox.modelPath:覆盖 JSON 模型文件(“objectbox-models / default.json”)的默认位置。
  • objectbox.daoCompat:如果要使用 DAO compat(类似于 greenDAOAPI),请设置为true

主要的类

一旦您定义了至少一个实体并成功构建了项目,就可以在 Android 项目中开始使用 ObjectBox。 以下是 ObjectBox 的使用接口的主要类:

  • MyObjectBox:根据您的实体类生成,MyObjectBox 提供一个构建器为您的应用程序设置 BoxStore
  • BoxStore:使用 ObjectBox 的入口。BoxStore 是您直接访问数据库并管理 Boxes 的接口。
  • Box::用于实体查询和持久化。对于每个实体,都有一个 Box(由 BoxStore 提供)。
  • Entities : 使用 ObjectBox 注释标记持久性的对象类。

初始化

最后,初始化 ObjectBox 的基本步骤:

// 通常只需要在您的 Application 类中执行一次
boxStore = MyObjectBox.builder().androidContext(App.this).build();
// 在您的 activities/fragments 获取Box对象
notesBox = ((App) getApplication()).getBoxStore().boxFor(Note.class);
复制代码

该示例假设已有一个Note实体存在。使用它的 BoxnotesBox 对象),我们可以调用该特定实体的持久化操作。

简单使用

Box 类是会是您经常使用的类。如前所述,您将通过 BoxStore.boxFor()获取 Box 实例。 Box 实例可以访问特定类型的对象。例如,如果您有 CustomerOrder 实体,则需要两个Box对象与每个实体进行交互:

Box<Customer> customerBox = boxStore.boxFor(Customer.class);
Box<Order> orderBox = boxStore.boxFor(Order.class);
复制代码

这些是 Box 类提供的以下操作:

  • put:持久化一个对象,会覆盖具有相同 ID 的现有对象。换句话说,使用 put 来插入或更新对象(另请参见文档中的对象ID)。当方法返回时,ID 将被分配给该对象。put的重载方法支持添加多个对象,这既方便又高效。
  • get:给定一个对象的 ID,您可以使用get非常有效地获取它 。要获取该类型的所有对象,请使用 getAll
  • remove: 移除一个Boxput后的对象(删除它). 可以使用它的重载方法移除多个对象,或者使用removeAll移除该类型所有对象
  • count:返回指定类型对象在 box 中的数量
  • query: 返回一个查询的构建器**(QueryBuilder)**,参见查询详细介绍

要获得Box类中可用方法的完整列表,请查看其JavaDoc

对象ID

对象必须具有long类型的ID属性,您可以自由的使用java的包装类型 java.lang.Long,但是我们不建议您这样做,因为long 类型 IDObjectBox 内部会更高效。

如果你的应用需要其他类型的 ID (例如服务器提供的字符串UID), 则可以将其创建为标准属性,并使用查询通过应用程序特定的ID查找实体。(抱歉水平有限,不知道该怎么翻译这句话)

特殊的对象ID

对象id可以是任意long类型的值,但有两个例外:

  • 0ID0 的对象(如果ID类型为Long,则为null),会被认为是新的对象。put这样的对象总是插入一个新对象,并将未使用的ID分配给它。
  • 0xFFFFFFFFFFFFFFFF(Java中为-1): 此值保留供 ObjectBox 内部使用,不能被应用程序使用。

对象的ID分配

默认情况下,对象 IDObjectBox 分配。对于每个新对象,ObjectBox 将分配一个未使用的ID,高于当前在 Box 中使用的最高 ID 值。例如,如果一个 Box 中有两个 ID1ID100的对象,则put的下一个对象将被分配ID 101

默认情况下,只有ObjectBox可以分配ID,如果您尝试放置ID大于当前最高 ID 的对象,则 ObjectBox 将抛出错误。 但是,如果您需要自己分配ID,则可以将 ID 注释更改为 @Id(assignable = true) 。允许put任何有效的ID的实体,包括零,让ObjectBox自动分配一个新的ID

事务处理

虽然ObjectBox提供了强大的事务处理,但是多数应用程序只需要考虑一些有关事务的基本准则:

  • 一个 put 执行一个隐式事务。
  • 在可能的情况下,推荐将批量操作放在列表中(比如put(entities))。
  • 对于在循环中大量的 DB 交互,考虑显式事务,例如使用runInTx()

有关详细信息,请查看独立的事务文档

有一个greenDAO的应用程序?DaoCompat是给你的

DaoCompat是一个兼容层,为ObjectBox提供了一个类似于greenDAOAPI。它使得从greenDAO切换到ObjectBox很简单。看一下文档示例。如果您有任何问题,请与我们联系!

更多文档

ObjectBox文档

转载于:https://juejin.im/post/5a31d2516fb9a0451f30f27c

 类似资料: