【译】ObjectBox官方文档——实体类注解

转载请注明出处

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

ObjectBox 是一个持久化对象的数据库。为了明确区分，我们有时调用那些持久化对象实体。为了让 ObjectBox 知道哪些类是实体，您可以向它们添加注释。然后 ObjectBox 可以对您的实体执行它的魔法。这里有一个例子:

@Entity
public class User {
    @Id
    private long id;
    private String name;
    
    @Transient
    private int tempUsageCount; // not persisted
   // getters and setters for id and user ...
}

@entity注释将Java类用户标识为一个可持久化的实体。ObjectBox会为该类定制生成数据持久化代码。

注意: 将实体类创建为仅具有公共属性(public)的 “基本型” 数据类通常是很好的做法。(这句翻译可能存在歧义，请自行斟酌)
注意: 如果您使用Kotlin来定义您的实体类，请查看ObjectBox和Kotlin文档

对象ID:@Id

在 ObjectBox 中，每个对象都有一个long类型ID，以便有效获取或引用对象。使用@id注释在您的实体中的一个long属性上:

@Entity
public class User {
    @Id
    private long id;
    ...
}

关于对象id，您应该知道一些事情:

0(0) 和 - 1(0xffffffffffffffffffff) 不能用作 id。
ID 为 0 的对象(如果 ID 类型为Long，则为null)，会被认为是新的对象。put这样的对象总是插入一个新对象，并将未使用的 ID 分配给它。
默认情况下，对象 ID 由 ObjectBox 分配。对于每个新对象， ObjectBox 将分配一个未使用的 ID，高于当前在 Box 中使用的最高 ID 值。例如，如果一个 Box 中有两个 ID 为 1 和 ID 为 100 的对象，则put的下一个对象将被分配ID 101。
如果您尝试使用大于当前最高 ID 的 ID, ObjectBox 将抛出一个错误。
如果您 需要自己分配ID ，则可以将 ID 注释更改为 @Id(assignable = true) 。允许put任何有效的 ID 的实体，包括 0，让 ObjectBox 自动分配一个新的 ID。
如果你的应用需要其他类型的 ID （例如服务器提供的字符串 UID）, 则可以将其创建为标准属性，并使用查询通过应用程序特定的 ID 查找实体。 （抱歉水平有限，不知道该怎么翻译这句话）
1
2
3
4
5
6
7
8
@Entity
public class User {
@Id
private long id;
@Index
private String serverUid;
...
}

数据持久化

ObjectBox 需要访问实体属性的数据(例如，在生成的Cursor类中)。你有两个选择:

给您的属性字段至少“包私有(protected)”(而不是“私有(private)”)可见性。在Kotlin中，您可以使用@jvmfield。
提供标准的getter(您的IDE可以轻松生成它们)。

基本实体属性的注释

@Entity
public class User {
 
    @NameInDb("USERNAME")
    private String name;
 
    @Transient
    private int tempUsageCount;
 
    ...
}

@NameInDb:让您在数据库级别上定义一个属性的名称。这允许您重命名Java字段，而不影响数据库级别上的属性名。
- 注意1:对于重命名来说，uid是首选。
- 注意2:目前只能使用内联常量来指定列名。
@Transient:(或者是transient修饰符)标记不应该被持久化的属性，比如上面的临时计数器。

@Index

在属性上使用@index为相应的数据库列创建数据库索引。这可以在频繁查询该属性时提高性能。

@Entity
public class User {
 
    @Id
    private Long id;
 
    @Index
    private String name;
 
}

生成代码

一旦您的实体创建完成，您可以通过编译项目来触发代码生成过程。例如在Android Studio中使用Build> Make project。

如果在更改实体类之后遇到错误，请尝试重建（清理，然后构建）您的项目，以确保清除生成的旧类。