基本用法

设置实例

要使用 Realm，首先需要获取它的实例。每个 Realm 实例都映射到磁盘上的文件。获取实例的最基本方法如下：

// Create configuration
RealmConfiguration realmConfiguration = new RealmConfiguration.Builder(context).build();

// Obtain realm instance
Realm realm = Realm.getInstance(realmConfiguration);
// or
Realm.setDefaultConfiguration(realmConfiguration);
Realm realm = Realm.getDefaultInstance();

方法 Realm.getInstance() 创建数据库文件（如果尚未创建），否则打开文件。RealmConfiguration 对象控制如何创建领域的所有方面 - 无论是 inMemory() 数据库，领域文件的名称，是否需要迁移需要迁移领域，初始数据等。

请注意，对 Realm.getInstance() 的调用是引用计数（每次调用增加一个计数器），并且当调用 realm.close() 时计数器会减少。

关闭实例

在后台线程上，一旦不再使用 Realm 实例（例如，事务完成且线程执行结束） ，关闭它们非常重要。无法关闭后台线程上的所有 Realm 实例会导致版本固定，并可能导致文件大小的大幅增长。 ******

Runnable runnable = new Runnable() {
    Realm realm = null;
    try {
        realm = Realm.getDefaultInstance();
        // ...
    } finally {
        if(realm != null) {
            realm.close();
        }
    }
};

new Thread(runnable).start(); // background thread, like `doInBackground()` of AsyncTask

值得注意的是，在 API 级别 19 以上，你可以使用以下代码替换此代码：

try(Realm realm = Realm.getDefaultInstance()) {
    // ...
}

楷模

下一步将是创建模型。这里可能会问一个问题，“什么是模型？”。模型是定义存储在数据库中的对象的属性的结构。例如，在下面我们为一本书建模。

public class Book extends RealmObject {
 
    // Primary key of this entity
    @PrimaryKey
    private long id;
 
    private String title;

    @Index // faster queries
    private String author;
 
    // Standard getters & setter
    public long getId() {
        return id;
    }
 
    public void setId(long id) {
        this.id = id;
    }
 
    public String getTitle() {
        return title;
    }
 
    public void setTitle(String title) {
        this.title = title;
    }
 
    public String getAuthor() {
        return author;
    }
 
    public void setAuthor(String author) {
        this.author = author;
    }
}

请注意，你的模型应该扩展 RealmObject 类。主键也由 @PrimaryKey 注释指定。主键可以为 null，但只有一个元素可以将 null 作为主键。你还可以将 @Ignore 注释用于不应该持久保存到磁盘的字段：

@Ignore
private String isbn;

插入或更新数据

为了将书籍对象存储到 Realm 数据库实例，你可以先创建模型的实例，然后通过 copyToRealm 方法将其存储到数据库中。要创建或更新，你可以使用 copyToRealmOrUpdate。 （更快的替代方案是新添加的 insertOrUpdate()）。

// Creating an instance of the model
Book book = new Book();
book.setId(1);
book.setTitle("Walking on air");
book.setAuthor("Taylor Swift")

// Store to the database
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        realm.insertOrUpdate(book);
    }
});

请注意，对数据的所有更改都必须在事务中进行。创建对象的另一种方法是使用以下模式：

Book book = realm.createObject(Book.class, primaryKey);
...

查询数据库

• 所有书籍：

  RealmResults<Book> results = realm.where(Book.class).findAll();
  

• ID 大于 10 的所有书籍：

  RealmResults<Book> results = realm.where(Book.class)
                                    .greaterThan("id", 10)
                                    .findAll();
  

• 'Taylor Swift'或'%Peter%'的书籍：

  RealmResults<Book> results = realm.where(Book.class)
                                    .beginGroup()
                                        .equalTo("author", "Taylor Swift")
                                        .or()
                                        .contains("author", "Peter")
                                    .endGroup().findAll();
  

删除对象

例如，我们想要删除 Taylor Swift 的所有书籍：

// Start of transaction
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        // First Step: Query all Taylor Swift books
        RealmResults<Book> results = ...
        
        // Second Step: Delete elements in Realm
        results.deleteAllFromRealm();
    }
});