转载请注明出处
第一次翻译文档,水平有限,如有任何错误和不妥,望指正。此外如想知道与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 customerBox = boxStore.boxFor(Customer.class);
Box 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很简单。看一下文档和示例。如果您有任何问题,请与我们联系!
更多文档
ObjectBox文档