【译】ObjectBox官方文档（1）——简介与配置-CSDN博客

转载请注明出处

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

简介

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

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"
}
复制代码

可选配置

在您的 Moudle 的 build.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（类似于 greenDAO 的 API），请设置为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实体存在。使用它的 Box（ notesBox 对象），我们可以调用该特定实体的持久化操作。

简单使用

Box 类是会是您经常使用的类。如前所述，您将通过 BoxStore.boxFor()获取 Box 实例。 Box 实例可以访问特定类型的对象。例如，如果您有 Customer 和 Order 实体，则需要两个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: 移除一个Box中put后的对象（删除它）. 可以使用它的重载方法移除多个对象,或者使用removeAll移除该类型所有对象
count:返回指定类型对象在 box 中的数量
query: 返回一个查询的构建器**（QueryBuilder）**，参见查询详细介绍

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

对象ID

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

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

特殊的对象ID

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

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

对象的ID分配

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

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