转载请注明出处
第一次翻译文档，水平有限，如有任何错误和不妥，望指正。此外如想知道与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。
事务处理
虽然ObjectBox提供了强大的事务处理，但是多数应用程序只需要考虑一些有关事务的基本准则：
- 一个
put执行一个隐式事务。 - 在可能的情况下，推荐将批量操作放在列表中(比如
put(entities))。 - 对于在循环中大量的 DB 交互,考虑显式事务，例如使用
runInTx()。
有关详细信息，请查看独立的事务文档。
有一个greenDAO的应用程序？DaoCompat是给你的
DaoCompat是一个兼容层，为ObjectBox提供了一个类似于greenDAO的API。它使得从greenDAO切换到ObjectBox很简单。看一下文档和示例。如果您有任何问题，请与我们联系!