Realm: リアクティブなモバイルアプリを短期間に

古いバージョンのドキュメントを表示しています。
最新版のドキュメントはこちらからご覧になれます。

Realm Javaはアプリケーションのモデルレイヤーの永続化処理を安全に素早く記述することを可能にします。コードは以下のようになります。

// RealmObjectを継承することでモデルクラスを定義
public class Dog extends RealmObject {
    private String name;
    private int age;

    // getterとsetterを生成
}
public class Person extends RealmObject {
    @PrimaryKey
    private long id;
    private String name;
    private RealmList<Dog> dogs; // 1対多の関連をもつ

    // 生成されたgetterとsetter
}

// 通常のJavaオブジェクトのようにモデルクラスを使用
Dog dog = new Dog();
dog.setName("Rex");
dog.setAge(1);

// アプリケーションの"files"ディレクトリにRealmファイルを作成するRealmConfigurationを作成
RealmConfiguration realmConfig = new RealmConfiguration.Builder(context).build();
Realm.setDefaultConfiguration(realmConfig);
// このスレッドのためのRealmインスタンスを取得
Realm realm = Realm.getDefaultInstance();

// 年齢が2未満のすべてのDogオブジェクトを取得する問い合わせを発行
final RealmResults<Dog> puppies = realm.where(Dog.class).lessThan("age", 2).findAll();
puppies.size(); // => まだRealmへは一つもオブジェクトが保存されていないので0を返します

// トランザクションの中でデータを永続化します
realm.beginTransaction();
final Dog managedDog = realm.copyToRealm(dog); // unmanagedなオブジェクトを永続化
Person person = realm.createObject(Person.class); // managedなオブジェクトを直接作成
person.getDogs().add(managedDog);
realm.commitTransaction();

// データが更新されると、リスナーが呼びだされて更新を受け取ることができます。
puppies.addChangeListener(new RealmChangeListener<RealmResults<Dog>>() {
    @Override
    public void onChange(RealmResults<Dog> results) {
        // クエリの結果は自動的に更新されます
        puppies.size(); // => 1
    }
});

// 別のスレッドから非同期に更新を実行することもできます
realm.executeTransactionAsync(new Realm.Transaction() {
    @Override
    public void execute(Realm bgRealm) {
        // トランザクションの開始とコミットは自動的に行われます
        Dog dog = bgRealm.where(Dog.class).equalTo("age", 1).findFirst();
        dog.setAge(3);
    }
}, new Realm.Transaction.OnSuccess() {
    @Override
    public void onSuccess() {
        // 既存のクエリやRealmObjectは自動的に最新の情報に更新されます
        puppies.size(); // => 0("age"が2未満の犬は存在しなくなったので)
        managedDog.getAge();   // => 3(既存オブジェクトは最新の状態に更新されるため)
    }
});

はじめに

Download Realm for Android ソースコードはGitHubにあります。

必要条件

現在のバージョンではAndroid以外のJavaはサポートされていません。
バージョン1.5.1以上のAndroid Studio
最新のAndroid SDK
JDK7以降
API Level 9（Android 2.3 Gingerbread）以降のAndroidはすべてサポートしています。

インストール

Realmを使用するためには、Realmが提供するGradleプラグインをプロジェクトに適用します。

プラグインの適用は、以下の2ステップで行います。

ステップ1: プロジェクトのトップレベルにあるbuild.gradleファイルに以下のclasspath設定を追加します。

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "io.realm:realm-gradle-plugin:1.2.0"
    }
}

プロジェクトのトップレベルのbuild.gradleは以下の場所にあります。プロジェクトトップレベルのbuild.gradleファイル

ステップ2: realm-androidプラグインをアプリケーションレベルのbuild.gradleファイルで適用します。

apply plugin: 'realm-android'

アプリケーションレベルのbuild.gradleは以下の場所にあります。アプリケーションレベルのbuild.gradleファイル

これらの設定を行ってからgradleプロジェクトのリフレッシュを行ってください。もし0.88以前のバージョンからアップグレードした場合は古いファイルの削除のためにプロジェクトのclean(./gradlew clean)を行う必要があるかもしれません。

以下の場所に、それぞれのbuild.gradleのサンプルがあります。

Gradle以外のビルドシステム

MavenやAntでのビルドはサポートされません。もしこれらのビルドシステムのサポートの必要性を表明したい場合は、以下のissueへコメントをお願いします。

これらのissueを参考に、MavenやAntサポートについての判断を行っていきます。

v1.0.0以降、Eclipseはサポートされません。Eclipseを使用している場合はAndroid Studioへの移行をお勧めします。

ProGuard

ProGuard設定はRealmライブラリの一部として提供されるようになりました。そのため、Realm自体に関するProGuard設定を追加する必要はありません。

Realm Browser

.realmデータベースを閲覧、編集するためのRealm BrowserというMacアプリケーションを提供しています。

Realm Browser

また、Tools > Generate demo database と選択すると、サンプルデータを含むテスト用のRealmデータベースを作ることができます。

開発中のアプリのRealmファイルがどの場所に格納されているかは、このStackOverflowの回答が参考になります。

Realm BrowserはMac App StoreかRealm BrowserのGitHubページからダウンロードすることができます。

現在のRealm BrowserはWindowsやLinuxでは動作しません。これらのプラットフォームを使用してアプリ開発を行っている方は、Stetho-Realmの使用をご検討ください。StethoはFacebook社によって開発されたツールで、Google Chromeブラウザのデバッグ機能を使ってAndroidアプリをデバッグできるようになります。

APIリファレンス

Realmで使用できるすべてのクラスとメソッドに関しては、APIリファレンスをご覧ください。

サンプルコード

Realmが実際に動くアプリケーションの中でどのように利用されるかの例がexamplesにあります。Android Studioで、Import Projectし、runで実行してみてください。

introExampleは、Realm APIの簡単な使用例について学べます。

gridViewExampleは、GridViewのデータソースとしてRealmを利用する方法について学べます。また、GSONを用いてJSONデータをRealm保存する方法や、ABI splitsを使用してAPKサイズを小さくする方法も含まれています。

threadExampleは、マルチスレッド環境でRealmを利用する方法について学べます。

adapterExampleは、RealmBaseAdapterとRealmRecyclerViewAdapterを使って、Realm上のデータをListViewとRecyclerViewに表示する方法について学べます。

jsonExampleは、RealmのJSON関連のメソッドについて学べます。

encryptionExampleは、Realmを暗号化する方法について学べます。

rxJavaExamplesは、RealmをRxJavaと組み合わせて使用方法について学べます。

unitTestExampleは、Realmを使ったアプリケーションをテストする方法について学べます。

ヘルプ

使い方に困ったときは、StackOverflowで#realmタグを付けて質問してください。私たちは毎日StackOverflowをチェックしています。
さらに複雑な問題に対する質問は、こちらの Slackチャットにて聞いてください。
バグ報告や機能リクエストについては GitHubのIssuesにご報告ください。
次のバージョンのリリース内容を前もって把握しておきたいですか？ Changelogファイルを見ましょう。次のバージョンでリリースされる予定の新機能や変更が記述されていきます。また、過去の変更内容も書かれています。

モデル

Realmでは、RealmObjectのサブクラスを作ることでモデルを定義します。

public class User extends RealmObject {

    private String          name;
    private int             age;

    @Ignore
    private int             sessionId;

    // Standard getters & setters generated by your IDE…
    public String getName() { return name; }
    public void   setName(String name) { this.name = name; }
    public int    getAge() { return age; }
    public void   setAge(int age) { this.age = age; }
    public int    getSessionId() { return sessionId; }
    public void   setSessionId(int sessionId) { this.sessionId = sessionId; }
}

モデル定義では、public、protected、privateフィールドや、任意のメソッドの使用も可能です。

public class User extends RealmObject {

    public String name;

    public boolean hasLongName() {
      return name.length() > 7;
    }

    @Override
    public boolean equals(Object o) {
      // カスタムのequals()メソッド
    }
}

対応しているデータ型

Realmでは、次に示すデータ型をサポートしています: boolean、byte、short、int、long、float、double、String、Dateおよびbyte[]です。 Realmの内部では、整数型であるbyte、short、int、long型はすべて同じ型(long型)として扱われます。

また、関連をサポートするためにはRealmObjectのサブクラスとRealmList<? extends RealmObject>が使用されます。

データ型として、プリミティブラッパークラスの Boolean、Byte、Short、Integer、Long、Float、Double型を使用することもできます。これらの型をもつフィールドに対しては値としてnullをセットすることができます。

必須フィールドとnull値

nullが値として適切ではない場合もあります。その場合、@Requiredアノテーションを使うことでnull禁止を明示することができます。Boolean、Byte、Short、Integer、Long、Float、Double、String、byte[]、Date型にのみ@Requiredアノテーションを使用することができ、これら以外の型に対して@Requiredアノテーションを使用した場合はコンパイルエラーになります。

プリミティブ型やRealmList型のフィールドは、暗黙的に@Requiredとして扱われます。また、RealmObjectを継承した型のフィールドは常にnull可として扱われます。

保存しないプロパティ

@Ignoreアノテーションを付けて宣言したフィールドは、ディスクに保存されないことを表します。モデルによって使用されない入力データが多くあるが、それらのデータを扱いたくないときに役に立ちます。

オブジェクトの自動更新

RealmObjectは”live”なオブジェクトであり、対応するデータの更新を自動的に反映します。つまり、明示的なリフレッシュ操作は必要ありません。

realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        Dog myDog = realm.createObject(Dog.class);
        myDog.setName("Fido");
        myDog.setAge(1);
    }
});
Dog myDog = realm.where(Dog.class).equalTo("age", 1).findFirst();

realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        Dog myPuppy = realm.where(Dog.class).equalTo("age", 1).findFirst();
        myPuppy.setAge(2);
    }
});

myDog.getAge(); // => 2

RealmObject‘やRealmResultsが備えるこの性質により、Realm自体が高速で効率的であるだけでなくRealmを利用するコードがシンプルでよりリアクティブなものになります。例えば、ActivityやFragmentがRealmObjectやRealmResultsを利用している場合、UIの更新の際にこれらのオブジェクトを更新したり取得しなおしたりする必要はなくなります。

また、通知機能を利用することでRealm内のデータが更新されたことを知ることができます。この機能により、常にUIに最新の情報を表示することができます。

インデックス付きプロパティ

@Indexアノテーションを付けて宣言したフィールドには、検索インデックスが作成されます。

インデックスを作成すると、データの追加が少し遅くなり、データファイルは大きくなりますが、検索の実行速度が向上します。そのため検索を速く実行する必要があるところでのみ使うことを推奨しています。

現在のバージョンでは、String、byte、short、int、long、booleanおよびDate型のフィールドに対して、インデックスを追加することができます。

プライマリキー

プライマリキーを指定するには、@PrimaryKeyアノテーションを使います。指定できるフィールドは、文字列型（String）か整数型（byte、short、intまたはlong）か、それらのラッパー型(Byte、Short、IntegerまたはLong)である必要があります。

複数のフィールドをプライマリキーとして指定すること（複合プライマリキー）はできません。

String型のフィールドをプライマリキーにすると、暗黙的にそのフィールドには検索インデックスが追加されます。（@PrimaryKeyアノテーションを指定することで、自動的に@Indexが付きます。）

プライマリキーを指定したモデルについては、copyToRealmOrUpdate()を使ってオブジェクトを作成または更新をすることができます。このメソッドは、プライマリキーが一致するデータがすでに存在すれば、データを更新し、無ければ新しくオブジェクトを作成します。 copyToRealmOrUpdate()をプライマリキーを持たないクラスに対して使用した場合は例外がスローされます。

プライマリキーを使うことによってパフォーマンスに影響します。オブジェクトの作成と更新は、少し遅くなりますが、検索は速くなります。パフォーマンスへの影響は、データセットの大きさによって異なります。

Realm.createObject()は新しくRealmオブジェクトを作成し、すべてのフィールドにデフォルト値を設定します。すでに存在するデータのプライマリキーとデフォルト値が衝突するのを避けるために、オブジェクトを作成した後は、フィールドに値を設定し、その後でcopyToRealm()でRealmにオブジェクトを追加してください。

final MyObject obj = new MyObject();
obj.setId(42);
obj.setName("Fish");
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        // 次のコメント行のコードでは、単に新たなオブジェクトの作成を試みます
        // realm.copyToRealm(obj);
        // 同じIDのオブジェクトが存在すれば更新を行い、存在しなければ新たに作成を行います
        realm.copyToRealmOrUpdate(obj);
    }
});

プライマリキー指定されたフィールドの型が文字列型(String)やラッパー型(Byte、Short、IntegerやLong)の場合、値としてnullを持つことも可能です。ただし、同時に@Requiredを指定することでnullの使用を禁止することもできます。

モデルクラスのカスタマイズ

RealmObjectを継承したモデルクラスは、ほぼ通常のPOJOsとして扱うことができます。RealmObjectを継承しさえすれば、フィールドをpublicにして直接代入することもできます。いかに例を示します。

public class Dog extends RealmObject {
    public String name;
    public int age;
}

Dogは通常のクラスと同じように使用することができます。Realm内にDogオブジェクトを作成するためには、createObject()またはcopyToRealm()メソッドを使用します。

realm.executeTransaction(new Realm.Transaction() {
    @Overrride
    public void execute(Realm realm) {
        Dog dog = realm.createObject(Dog.class);
        dog.name = "Fido";
        dog.age  = 5;
    }
};

ゲッターやセッターを定義し、その中に独自のロジックを組み込むことも可能です。たとえばRealmに保存する前に値のチェックを行う場合などにはとても役に立ちます。また、モデルクラスに独自のメソッドを定義することもできます。

RealmModelインタフェース

RealmObjectを継承する以外の選択肢として、RealmModelインタフェースと@RealmClassアノテーションを用いる方法があります。その場合は、RealmModelを実装するとともに、クラスに@RealmClassアノテーションを付与してください。

@RealmClass
public class User implements RealmModel {
}

RealmObjectがインスタンスメソッドとして提供していたメソッドは、staticメソッドとしても提供されます。

// RealmObjectを継承する場合
user.isValid();
user.addChangeListener(listener);

// RealmModelを実装する場合
RealmObject.isValid(user);
RealmObject.addChangeListener(user, listener);

リレーションシップ（関連）

RealmObjectは、互いを関連させることができます。

public class Email extends RealmObject {
    private String address;
    private boolean active;
    // settersとgettersは省略しています
}

public class Contact extends RealmObject {
    private String name;
    private Email email;
    // settersとgettersは省略しています
}

Realmの関連は速度の観点からは非常に低コストで利用できます。さらに関連を表現するための内部の仕組みは、メモリ消費の点においても非常に効率良く作られています。

多対１のリレーションシップ

モデル間で多対１の関連を持たせるには、別のRealmObjectのプロパティを下記のように定義します:

public class Contact extends RealmObject {
    private Email email;
    // Other fields…
}

それぞれのContactインスタンスは０個または１つのEmailインスタンスを関連として持ちます。複数のContactインスタンスが同じ１つのEmailインスタンスを関連として持つこともできます。上記のモデルで多対１の関連を持つこともできますが、多くの場合１対１の関連が使われます。

RealmObject型のフィールドにnullをセットすることは関連を削除することを意味し、参照先のモデルオブジェクト自体は削除されません。

多対多のリレーションシップ

１つのオブジェクトから複数（０個以上）の関連を持つにはRealmList<T>フィールドを定義します。たとえば複数のメールアドレスを保持するアドレス帳の例を考えてみます。

public class Contact extends RealmObject {
    public String name;
    public RealmList<Email> emails;
}

public class Email extends RealmObject {
    public String address;
    public boolean active;
}

RealmListクラスは、基本的にRealmObjectのコンテナで、その振る舞いは、JavaのListクラスと非常によく似ています。１つのオブジェクトが、複数の異なるRealmListをもつことができます。１対多の関連としても、多対多の関連を表す場合にも使うことができます。

以下のようにContactとEmailクラスを定義したとします。

それぞれのオブジェクトを作成した後、RealmList.add()メソッドを用いてEmailオブジェクトをContactと関連付けることができます。

realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        Contact contact = realm.createObject(Contact.class);
        contact.name = "John Doe";

        Email email1 = realm.createObject(Email.class);
        email1.address = "john@example.com";
        email1.active = true;
        contact.emails.add(email1);

        Email email2 = realm.createObject(Email.class);
        email2.address = "jd@example.com";
        email2.active = false;
        contact.emails.add(email2);
    }
});

再帰的な関連を定義することもできます。

public class Person extends RealmObject {
    public String name;
    public RealmList<Person> friends;
    // Other fields…
}

RealmList型のフィールドにnullをセットすることはリストをクリアすることを意味します。つまり、リストが参照していたモデルオブジェクトの削除はおこなわれず、単にリストの長さをゼロにするだけです。RealmList型のフィールドのgetterがnullを返すことはありません。返されるオブジェクトの保持する要素数が０になります。

書き込み

読み出しの操作は、どのタイミングでも実行可能ですが、書き込み（追加、変更、削除）処理は、必ずトランザクションの中で行わなければなりません。

Writeトランザクションは、コミットかキャンセルができます。

コミットしたときは、トランザクション中のすべての変更がディスクに書き込まれ、すべてのデータが保存されるとコミット処理が成功となります。トランザクションをキャンセルした場合、トランザクション中のすべての変更は破棄されます。

データの一貫性を保つためにトランザクションを使用します。

また、トランザクションはスレッドセーフを保証するためにも使用されます。

// Obtain a Realm instance
Realm realm = Realm.getDefaultInstance();

realm.beginTransaction();

//... オブジェクトの追加や更新 ...

realm.commitTransaction();

トランザクション中で行ったRealmオブジェクトの変更は、反映するかキャンセルするかを選ぶことができます。変更をコミットするのではなく破棄する場合、下記のように簡単にキャンセルすることができます。

realm.beginTransaction();
User user = realm.createObject(User.class);

//  ...

realm.cancelTransaction();

同時に発生した書き込み処理は、互いの書き込み処理をブロックします。

UIスレッドとバックグラウンドスレッドで同時にトランザクションを実行することは、UIスレッドをブロックしANRエラーの原因になります。

これを避けるために、UIスレッド上でトランザクションを開始する際は、非同期トランザクションを使用してください。

Realmは不意のクラッシュに対しても安全です。トランザクション中にExceptionが発生した場合でもRealmファイルが壊れることはありません。トランザクション中のデータが失われるだけです。Exceptionを捕捉し、アプリケーションが続行する場合は、トランザクションをキャンセルしなければなりません。executeTransaction()メソッドを利用しているなら自動的にトランザクションはキャンセルされます。

RealmはMVCCアーキテクチャーを採用しているので、トランザクション実行中でも読み込み処理がブロックされることはありません。同時に複数のスレッドからトランザクションを実行するのでなければ、細かいトランザクションを使うよりも大きな単位でトランザクションを使いましょう。

同じRealmに保存されているオブジェクトに変更があった場合は、トランザクションがコミットされた時点ですべての変更が自動的に適用されます。

Realmのトランザクションは、ACIDに準拠しています。

オブジェクトの作成

RealmObjectはRealmと強く結び付けられているので、以下のようにRealmインスタンスをつかって作成する必要があります。

realm.beginTransaction();
User user = realm.createObject(User.class); // 新たなオブジェクトを作成
user.setName("John");
user.setEmail("john@corporation.com");
realm.commitTransaction();

別の方法として、始めに一般のオブジェクトと同様にインスタンスを作成し、realm.copyToRealm() を使用して、後からRealmに保存することもできます。

Realmのモデルでは自由にコンストラクタを定義することができますが、少なくともその中に引数を取らないパブリックコンストラクタが含まれていなければなりません。

User user = new User("John");
user.setEmail("john@corporation.com");

// Realmへオブジェクトをコピーします。これ以降の変更は、返り値のオブジェクトに対して行う必要があります
realm.beginTransaction();
User realmUser = realm.copyToRealm(user);
realm.commitTransaction();

realm.copyToRealm()を使う際に注意することは、戻り値として返されたオブジェクトのみがRealmによって管理されているということです。以降、最初に作られたオブジェクトに変更を加えても、何も反映されません。

トランザクションブロック

realm.beginTransaction(), realm.commitTransaction(), realm.cancelTransaction() の代わりに、realm.executeTransaction()メソッドを使って、ブロック形式でトランザクションを記述することができます。

このメソッドを使用した場合、メソッドを抜けた時点で自動的にトランザクションはコミットされます。もし、エラーが発生した場合は自動的にキャンセルされます。

realm.executeTransaction(new Realm.Transaction() {
	@Override
	public void execute(Realm realm) {
		User user = realm.createObject(User.class);
		user.setName("John");
		user.setEmail("john@corporation.com");
	}
});

非同期トランザクション

トランザクションを開始しようとした際、他のスレッドがトランザクションを実行中だと実行中のトランザクションが終了するまで待たされてしまいます。 UIスレッドが待たされてしまうことを避けるために、バックグラウンドスレッドで全ての書き込み処理を行うことには大きな利点があります。

非同期トランザクションの機能を使うことで、Realmに対してバックグラウンドスレッドでのトランザクション実行と完了後の結果通知を行わせることができます。

realm.executeTransactionAsync(new Realm.Transaction() {
            @Override
            public void execute(Realm bgRealm) {
                User user = bgRealm.createObject(User.class);
                user.setName("John");
                user.setEmail("john@corporation.com");
            }
        }, new Realm.Transaction.OnSuccess() {
            @Override
            public void onSuccess() {
                // トランザクションは成功
            }
        }, new Realm.Transaction.OnError() {
            @Override
            public void onError(Throwable error) {
                // トランザクションは失敗。自動的にキャンセルされます
            }
        });

OnSuccessとOnErrorのコールバックは必須ではありませんが、渡された場合はトランザクション完了時に、成功/失敗に応じて呼び出されます。コールバックはLooperを用いて制御されているので、Looperスレッドでのみ使用することができます。

RealmAsyncTask transaction = realm.executeTransactionAsync(new Realm.Transaction() {
            @Override
            public void execute(Realm bgRealm) {
                User user = bgRealm.createObject(User.class);
                user.setName("John");
                user.setEmail("john@corporation.com");
            }
        }, null);

非同期トランザクションはRealmAsyncTaskオブジェクトとして表現されます。このオブジェクトを通して、トランザクションのキャンセルを行うことができます。

トランザクション完了前にActivityやFragmentを終了する場合は忘れずにキャンセルを行ってください。キャンセルせずにコールバックがUI更新を行ってしまうとアプリケーションがクラッシュしてしまいます。

public void onStop () {
    if (transaction != null && !transaction.isCancelled()) {
        transaction.cancel();
    }
}

バイト配列の更新

Realmはフィールドが持つ値全体をひとまとまりで扱います。そのため、バイト配列の要素を個別に更新することはサポートしていません。たとえば、バイト配列の５番目の要素のみを更新したい場合、Realmでは以下のようにコーディングする必要があります。

realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        bytes[] bytes = realmObject.binary;
        bytes[4] = 'a';
        realmObject.binary = bytes; // 代入またはsetterの呼び出しが必要
    }
});

これはRealmのMVCCアーキテクチャによる制限で、変更を行ってからcommitが完了するまでの間、他のスレッドが更新中のデータにアクセスしてしまうことを防ぐために必要です。

クエリ

Realmにおいてすべての読み込み（クエリを含む）は遅延実行されます。また、読み込み時にデータのコピーは一切発生しません。

RealmのクエリAPIは、複数の条件を組み立てる方法として流れるようなインターフェースを採用しています（メソッドチェーンと入力補完を利用して、複雑なクエリでも簡単に組み立てることができます）。

以下のようなUserクラスを定義したとします。

public class User extends RealmObject {

    @PrimaryKey
    private String          name;
    private int             age;

    @Ignore
    private int             sessionId;

    // Standard getters & setters generated by your IDE…
    public String getName() { return name; }
    public void   setName(String name) { this.name = name; }
    public int    getAge() { return age; }
    public void   setAge(int age) { this.age = age; }
    public int    getSessionId() { return sessionId; }
    public void   setSessionId(int sessionId) { this.sessionId = sessionId; }
}

nameフィールドの値がJohnまたはPeterであるすべてのオブジェクトを取得するには次のように書きます。

// Build the query looking at all users:
RealmQuery<User> query = realm.where(User.class);

// Add query conditions:
query.equalTo("name", "John");
query.or().equalTo("name", "Peter");

// Execute the query:
RealmResults<User> result1 = query.findAll();

// Or alternatively do the same all at once (the "Fluent interface"):
RealmResults<User> result2 = realm.where(User.class)
                                  .equalTo("name", "John")
                                  .or()
                                  .equalTo("name", "Peter")
                                  .findAll();

この例では、nameの値がJohnまたはPeterであるデータがRealmResultsとして返ってきます。この時、データは一切コピーされません。

マッチしたUserオブジェクトを取り出したり、取得したオブジェクトを直接操作することができます。

RealmResultは、AbstractListクラスを継承しており、使い方はよく似ています。例えば、RealmResultsは、順序を持ち、添え字を指定してアクセスすることができます。

実行されたクエリに該当するオブジェクトが無かった場合、戻り値としてnullが返されることはなく、空のRealmResultsオブジェクトが返されます。返されるオブジェクトのsize()メソッドの値は０です。

RealmResultに含まれるオブジェクトに対して変更を加えたり、削除する場合、それらの操作はトランザクションの中で行わなければなりません。

検索条件を指定する

以下の検索条件がサポートされています。

between()、greaterThan()、lessThan()、greaterThanOrEqualTo()、lessThanOrEqualTo()
equalTo()、notEqualTo()
contains()、beginsWith()、endsWith()
isNull() & isNotNull()
isEmpty() & isNotEmpty()

ただし、すべてのデータ型が対応しているわけではありません。詳しくは、RealmQueryをご覧ください。

修飾子

文字列の検索条件に対して、Case.INSENSITIVEを指定することで、アルファベットの大文字と小文字の区別を無視することができます。

論理演算子

すべての条件式は暗黙的に論理積（AND）になります。論理和（OR）を使う場合は明示的にor() を使用する必要があります。

以下のようなUserクラスを定義したとします。

public class User extends RealmObject {

    @PrimaryKey
    private String          name;
    private int             age;

    @Ignore
    private int             sessionId;

    // 以下はIDEによって生成された一般的なgetter/setter
    public String getName() { return name; }
    public void   setName(String name) { this.name = name; }
    public int    getAge() { return age; }
    public void   setAge(int age) { this.age = age; }
    public int    getSessionId() { return sessionId; }
    public void   setSessionId(int sessionId) { this.sessionId = sessionId; }
}

それぞれの条件の評価順を指定するために「かっこ」を利用してグループ化するのは、次のようにbeginGroup()で「かっこ」を開き、endGroup()で「かっこ」を閉じます。

RealmResults<User> r = realm.where(User.class)
                            .greaterThan("age", 10)  //暗黙的にAND条件になります
                            .beginGroup()
                                .equalTo("name", "Peter")
                                .or()
                                .contains("name", "Jo")
                            .endGroup()
                            .findAll();

さらに、not()を使うと否定になります。not()は、beginGroup()とendGroup()に対してのみ使用することができます。

並べ替え

クエリの実行後は、以下のように結果を並べ替えることができます。

RealmResults<User> result = realm.where(User.class).findAll();
result = result.sort("age"); // 昇順にソート
result = result.sort("age", Sort.DESCENDING);// 降順にソート

クエリの連鎖

すべてのクエリは、遅延実行されることに加えて決してデータをコピーしないので、非常に効率的に連鎖して実行することができ、次々とデータをフィルタリングしていくことができます。

RealmResults<Person> teenagers = realm.where(Person.class).between("age", 13, 20).findAll();
Person firstJohn = teenagers.where().equalTo("name", "John").findFirst();

クエリの連鎖は関連オブジェクトに対しても適用することができます。以下のようにPersonがDogをリストとして保持している例で説明します。

public class Dog extends RealmObject {
    private int age;
    // getters & setters ...
}

public class Person extends RealmObject {
    private int age;
    private RealmList<Dog> dogs;
    // getters & setters ...
}

以下のようにすることで、ageが１３から２０の間のPersonで、ageが１である犬を少なくとも１つは関連として保持しているものを取得することができます。

RealmResults<Person> teensWithPups = realm.where(Person.class).between("age", 13, 20).equalTo("dogs.age", 1).findAll();

クエリの連鎖はRealmQueryではなくRealmResultsに対してさらにクエリを発行するものを指します。RealmQueryに対して条件を追加するものはクエリの連鎖とは呼ばず、単に既存のクエリが更新されまます。詳しくは、link queriesを参照してください。

クエリの自動更新

RealmResultsは”live”なオブジェクトであり、対応するデータの更新を自動的に反映します。つまり、明示的なリフレッシュ操作は必要ありません。クエリに影響するような操作をオブジェクトに対して行った場合、RealmResultsへの反映は次のLooperイベントの際に行われます。

final RealmResults<Dog> puppies = realm.where(Dog.class).lessThan("age", 2).findAll();
puppies.size(); // => 0

realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        Dog dog = realm.createObject(Dog.class);
        dog.setName("Fido");
        dog.setAge(1);
    }
});

puppies.addChangeListener(new RealmChangeListener() {
    @Override
    public void onChange(RealmResults<Dog> results) {
      // resultsとpuppiesは両方共最新のデータに更新されています
      results.size(); // => 1
      puppies.size(); // => 1
    }
});

RealmResultsが備えるこの性質により、Realm自体が高速で効率的であるだけでなくRealmを利用するコードがシンプルでよりリアクティブなものになります。例えば、ActivityやFragmentがRealmObjectやRealmResultsを利用している場合、UIの更新の際にこれらのオブジェクトを更新したり取得しなおしたりする必要はなくなります。

また、通知機能を利用することでRealm内のデータが更新されたことを知ることができます。この機能により、情報の再取得を意識することなく常に最新の情報をUIに表示することができます。

クエリの結果は自動更新されるので、インデックスやサイズが不変であるという前提のコードを記述しないことはとても重要です。

型を使ったオブジェクトの取得

Realmからオブジェクトを取得するときのもっとも基本的なメソッドは、realm.where(Foo.class).findAll()です。このメソッドは、指定したモデルクラスのすべてのオブジェクトを含むRealmResults<Foo>として返します。

また、findAll()に似たメソッドで realm.where(Foo.class).findAllSorted()もあります。このメソッドは、オブジェクトを取得すると同時に、フィールドを指定して並べ替えをすることができます。詳しくは、realm.where(Foo.class).findAllSorted()をご覧ください。

集計

RealmResultsにはさまざまな集計のためのメソッドがあります。

RealmResults<User> results = realm.where(User.class).findAll();
long   sum     = results.sum("age").longValue();
long   min     = results.min("age").longValue();
long   max     = results.max("age").longValue();
double average = results.average("age");

long   matches = results.size();

繰り返し処理

RealmResultsは繰り返し処理のためにIterableインターフェースを実装しています。

RealmResults<User> results = realm.where(User.class).findAll();
for (User u : results) {
    // ... それぞれのオブジェクトに対する操作を実装...
}

もちろん以下のようなforループも使用できます。

RealmResults<User> results = realm.where(User.class).findAll();
for (int i = 0; i < results.size(); i++) {
    User u = results.get(i);
    // ... それぞれのオブジェクトに対する操作を実装...
}

RealmResultsの更新は次のLooperイベントまで遅延されるので、それまでの間に条件を満たさなくなったオブジェクトや削除されたオブジェクトにアクセスしてしまうケースが存在します。

final RealmResults<User> users = getUsers();
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        users.get(0).deleteFromRealm(); // RealmResultsを介さない間接的な削除
    }
});

for (User user : users) {
    showUser(user); // 削除済みオブジェクトへのアクセスでアプリクラッシュが発生
}

deleteFromRealm()を使う代わりに、RealmResultsのメソッドを使うことで回避できます。

final RealmResults<User> users = getUsers();
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        users.deleteFromRealm(0); // オブジェクトの削除とリストからの除外
    }
});

for (User user : users) {
    showUser(user); // 削除されたオブジェクトはイテレート対象に含まれなくなります
}

削除

クエリの結果を使ってRealmからデータを削除することができます。

// クエリを発行し結果を取得
final RealmResults<Dog> results = realm.where(Dog.class).findAll();

// 変更操作はトランザクションの中で実行する必要あり
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        // マッチしたオブジェクトから１つを削除
        results.deleteFromRealm(0);
        results.deleteLastFromRealm();

        // 特定のオブジェクトのみを削除
        Dog dog = results.get(5);
        dog.deleteFromRealm();

        // すべてのオブジェクトを削除
        results.deleteFromRealm();
    }
});

非同期クエリ

クエリもバックグラウンドスレッドで実行させることができます。

ほとんどのクエリはたとえUIスレッド上であっても同期実行させて問題ないほどに高速です。しかし、とても複雑なクエリやとても大きなデータに対するクエリについてはバックグラウンドスレッドで実行する価値があります。

"name"が"John"または"Peter"であるユーザーを検索する例を見ていきましょう。

クエリの作成

RealmResults<User> result = realm.where(User.class)
                              .equalTo("name", "John")
                              .or()
                              .equalTo("name", "Peter")
                              .findAllAsync();

このクエリはスレッドをブロックせず、即座にRealmResults<User>オブジェクトを返します。このオブジェクトは プロミス で、標準のJavaにおけるFutureと似た概念を表現しています。クエリはバックグラウンドスレッドで実行され、完了時に先ほど返却されたRealmResultsインスタンスが更新されます。

クエリの完了後RealmResultsが更新される際に通知を受け取りたい場合は、RealmChangeListenerを登録することができます。このリスナは、Realmに反映された最新の内容を受け取るためにRealmResultsが更新されるたびに呼びだされます。

コールバックの登録

private RealmChangeListener callback = new RealmChangeListener() {
    @Override
    public void onChange(RealmResults<User> results) {
        // クエリ完了後、更新があるたびに呼び出されます。
    }
};

public void onStart() {
    RealmResults<User> result = realm.where(User.class).findAllAsync();
    result.addChangeListener(callback);
}

メモリリークを避けるため、ActivityやFragment終了の際は忘れずにリスナの登録を解除してください。

public void onStop () {
    result.removeChangeListener(callback); // 特定のリスナの登録を解除
    // または
    result.removeChangeListeners(); // 登録されている全てのリスナの登録を解除
}

クエリの完了チェック

RealmResults<User> result = realm.where(User.class).findAllAsync();
if (result.isLoaded()) {
  // クエリの結果を利用した処理
}

同期のクエリで取得したRealmResultsに対する isLoaded() の呼び出しは、常にtrueを返します。

非同期クエリの強制ロード

非同期クエリの完了を待つこともできます。同期クエリに戻すことになるので、クエリが完了するまで呼び出しスレッドがブロックされます(Future.get()と同様の考え方です)。

RealmResults<User> result = realm.where(User.class).findAllAsync();
result.load() // 注意。結果が返るまで呼び出したスレッドをブロックします。

非 Looper スレッド

非同期クエリはLooperを持つスレッドからのみ使用することができます。というのも、非同期クエリはクエリの結果を呼び出し元のスレッドに伝えるために、Realmが内部に持っている Handlerを使用するからです。

Looperを持たないスレッド上のRealmに対する非同期クエリの呼び出しはIllegalStateException がスローされます。

Realmについて

Realmクラスのインスタンスは、データベースと同じようなものです。異なるオブジェクトを保持しており、これらは一つのファイルに保存されています。

Realmの設定をカスタマイズする

RealmConfigurationオブジェクトを用いてどのようなRealmを構築するかを制御できます。最小の設定は以下のコードで作成できます。

RealmConfiguration config = new RealmConfiguration.Builder(context).build();

上記の設定では、デフォルトの名前であるdefault.realmという名前のファイルをContext.getFilesDir()の場所に作成します。

以下の様なコードが典型的な設定例です。

// ビルダーパターンでRealmConfigurationを作成します。
// "myrealm.realm"という名前でContext.getFilesDir()の場所にファイルを作成します。
RealmConfiguration config = new RealmConfiguration.Builder(context)
  .name("myrealm.realm")
  .encryptionKey(getKey())
  .schemaVersion(42)
  .modules(new MySchemaModule())
  .migration(new MyMigration())
  .build();
// 設定に従ったRealmを取得します
Realm realm = Realm.getInstance(config);

複数のRealmConfigurationを使用することもできます。このようにすることで、異なるバージョン、異なるスキーマ、異なるファイルのRealmを同時に扱うことができます。

RealmConfiguration myConfig = new RealmConfiguration.Builder(context)
  .name("myrealm.realm")
  .schemaVersion(2)
  .modules(new MyCustomSchema())
  .build();

RealmConfiguration otherConfig = new RealmConfiguration.Builder(context)
  .name("otherrealm.realm")
  .schemaVersion(5)
  .modules(new MyOtherSchema())
  .build();

Realm myRealm = Realm.getInstance(myConfig);
Realm otherRealm = Realm.getInstance(otherConfig);

Realm.getPath()メソッドで、Realmファイルの絶対パスを取得することができます。

同一のRealmConfigurationに対するRealmインスタンスはスレッドごとのシングルトンオブジェクトであるため、Realm.getInstance()などのstaticメソッドはスレッドごとに同じインスタンスを返すことに注意してください。

デフォルトRealm

RealmConfigurationオブジェクトをデフォルト設定として保持しておくことができます。

カスタムApplicationクラスでデフォルト設定を行うことで、アプリケーション全体で同じ設定のRealmを使用することができます。

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    RealmConfiguration config = new RealmConfiguration.Builder(this).build();
    Realm.setDefaultConfiguration(config);
  }
}

public class MyActivity extends Activity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Realm realm = Realm.getDefaultInstance();
    // ... Realmを使用した処理 ...
    realm.close();
  }
}

In-Memory Realm

データをメモリ上のみに保持する（ディスクに保存しない）Realmオブジェクトを作ることができます。

RealmConfiguration myConfig = new RealmConfiguration.Builder(context)
    .name("myrealm.realm")
    .inMemory()
    .build();

この設定は通常のディスクに保存するRealmインスタンスの代わりに、In-memory Realmインスタンスを生成します。

In-memory Realmであっても、使用メモリが不足したときなどにはディスクを使用することがあります。ですがIn-memory Realmによって作成されたファイルはRealmを閉じるときにすべて削除されます。

In-memory Realmと同じ名前の、通常の（ディスクに保存する）Realmインスタンスを作成することはできないので気をつけてください。

スコープを外れて、In-Memory Realmインスタンスへの参照がすべて無くなると、そのRealm内に保存されている、すべてのデータは解放されます。アプリケーションの起動中は、In-Memory Realmインスタンスへの参照を保持しておようにしてください。

Dynamic Realms

従来のRealmでは、モデルクラスはRealmObjectのサブクラスを用いて定義されます。これは型安全という点においてとても大きな利点がありますが、マイグレーションやCSVのように文字列ベースのデータを扱うような場合のように使用する型がコンパイル時には決められない場合もあります。

DynamicRealmは従来のRealmの派生版で、RealmObjectのサブクラスによって定義された型なしでデータを扱うことができます。データに対するアクセスはクラスベースではなく、文字列によって行われます。

DynamicRealmは従来のRealmと同じRealmConfigurationを使ってオープンすることができますが、スキーマ、マイグレーション、スキーマバージョンについては無視されます。

RealmConfiguration realmConfig = new RealmConfiguration.Builder(context).build();
DynamicRealm realm = DynamicRealm.getInstance(realmConfig);

// DynamicRealmでは、すべてのオブジェクトはDynamicRealmObjectです
DynamicRealmObject person = realm.createObject("Person");

// すべてのフィールドは名前の文字列でアクセスします
String name = person.getString("name");
int age = person.getInt("age");

// データベースのスキーマは依然として有効なので、スキーマに違反する操作には例外がスローされます
// will throw an exception
person.getString("I don't exist");

// クエリは従来通り使用可能です
RealmResults<DynamicRealmObject> persons = realm.where("Person")
    .equalTo("name", "John")
    .findAll();

DynamicRealmは柔軟性のために型安全とパフォーマンスを犠牲にしています。DynamicRealmが提供する柔軟性がどうしても必要な場合でのみ使うようにしてください。

Realmインスタンスを閉じる

ネイティブメモリとファイルディスクリプタを解放する必要があるため、RealmはCloseableインターフェースを実装しています。

Realmインスタンスが必要なくなったら、そのRealmを閉じることを忘れないようにしてください。

Realmインスタンスはリファレンスカウント方式で管理されています。もし同じスレッドで２回getInstance()を呼んだ場合は、close()も同じように２回呼ばなければなりません。

この仕組みにより、Runnableインターフェースを実装するときに、どのスレッドで実行されるのかを特に意識する必要はありません。単にgetInstance()で始めて、最後にclose()してあげればいいのです。

UIスレッドにおいてRealmインスタンスを閉じるもっとも簡単な方法は、onDestroy()メソッドでrealm.close()を呼ぶようにすることです。

独自にLooperスレッドを作成する必要がある場合は、以下のようにクラスを作成してください。

public class MyThread extends Thread {
    private Realm realm;

    @Override
    public void run() {
        Looper.prepare();
        try {
            realm = Realm.getDefaultInstance();
            // ここで実際の処理を行うハンドラーを準備する
            Lopper.loop();
        } finally {
            if (realm != null) {
                realm.close();
            }
        }
    }
}

AsyncTaskで使用する場合は、以下のように（よくあるCloseableなオブジェクトの使い方と同じやりかたで）使うのは良い書き方です。

protected Void doInBackground(Void... params) {
    Realm realm = Realm.getDefaultInstance();
    try {
        // ... Realmインスタンスを使用するコード ...
    } finally {
        realm.close();
    }

    return null;
}

非同期にタスクを実行するためにThreadやRunnableを用いて寿命の短いタスクを生成する場合は以下のようにコーディングしてください。

// Run a non-Looper thread with a Realm instance.
Thread thread = new Thread(new Runnable() {
    @Override
    public void run() {
        Realm realm = null;
        try {
            realm = Realm.getDefaultInstance();
            //... Realmインスタンスを使用する ...
        } finally {
            if (realm != null) {
                realm.close();
            }
        }
    }
});

thread.start();

アプリケーションのAPIレベルがminSdkVersion >= 19かつJava7以降であればtry-with-resources 構文が使えるので、下記のように書くことができます。

try (Realm realm = Realm.getDefaultInstance()) {
    // Realmインスタンスを明示的に閉じる必要はありません。
}

オートリフレッシュ

Looperスレッド（UIスレッドはデフォルトでLooperが存在します）で生成されたRealmインスタンスはオートリフレッシュ機能を持ちます。

Looperで作られたRealmインスタンスは、イベントループが回るたびに常に最新のデータに更新されるということです。この機能は非常に便利で、少ない手間でUIを常に最新の状態に更新し続けることができます。

Looperが存在しないスレッドで作られたRealmインスタンスは、自動的に更新されることはなく、最新のデータに更新するにはwaitForChange()を呼ぶ必要があります。

ここで注意すべきことは、最新でない古い履歴のデータを保持し続けることは、メモリやディスクの消費の観点から、コストの高いことだという点です。そして、履歴が進むにつれてそのコストも増加します。これが各スレッドにおいてRealmインスタンスを使い終わったら、すぐに閉じることが重要だという理由です。

オートリフレッシュ機能が有効になっているかどうかはisAutoRefresh()メソッドを使って確認することができます。

Realmファイルの探し方

Realmファイルの特定の仕方は、この StackOverflow の回答をご覧ください。

スレッド

Realmをマルチスレッドで使う際に覚えて置かなければいけないこと、実践しなければいけないことというのは実際にはそれほど多くはありません。Realmを正しく用いることでマルチスレッドにおける一貫性やパフォーマンスの問題から開放されます。というのも、オブジェクトの自動更新やクエリの自動更新が必要なことは全て行ってくれるからです。

他のスレッドが同じオブジェクトにどのよな操作を行っているかを気にすることなく、それぞれのスレッドにおいて取得したライブなオブジェクトに対して読み込みや変更の操作を行うことができます。

データの変更が必要な場合はドランザクションを使用します。他のスレッド上のオブジェクトは、ほぼリアルタイムにその変更を受け取ります。ほぼリアルタイムと書いたのは、なにか処理中であった場合は次のイベントループまで更新が遅延されるからです。

唯一の制約は、Realmのオブジェクトをスレッド間で受け渡してはいけないということです。同じデータを他のスレッドで利用する必要がある場合、それぞれのスレッドでクエリを発行してオブジェクトを取得してください。Realmの提供する仕組みを用いて変更を監視することもできます。すべての更新はスレッドを超えて同期され、通知の仕組みにより受け取ることができます。

次のサンプルをご確認ください。

Realmをマルチスレッドで使う場合のサンプル

顧客の一覧を表示するアプリケーションがあるとします。バックグラウンドスレッド(Android IntentService)で、新たな顧客の追加をポーリングしてRealmに保存します。バックグラウンドスレッドが新たな顧客を追加すると、UIスレッド上のデータも自動的に更新されます。UIスレッドはRealmChangeListenerを通して通知を受け取り、UIを更新します。クエリを発行し直す必要はありません。Realmではクエリは自動的に更新されます。

// FragmentやActivity
@Override
public void onActivityCreated(Bundle savedInstanceState) {
    // ... Realmに関係しないコードは省略しています
    realm = Realm.getDefaultInstance();
    // すべての顧客を取得するクエリを構築します
    RealmResults<Customer> customers = realm.where(Customer.class).findAllAsync();
    // ... 実際にはここで、ListViewやRecyclerViewなどのアダプターを構築します

    // Realmのリスナーをセットします
    changeListener = new RealmChangeListener() {
        @Override
        public void onChange(RealmResults<Customer> results) {
            // データベースに変更が行われるたびに通知されます。
            // リスナーはLooperスレッドでのみ利用可能であることに注意してください。
            // 非Looperスレッドでは、Realm.waitForChange()を呼ぶ必要があります。
            listAdapter.notifyDataSetChanged(); // UIの更新処理
        }
    };
    // 顧客リストに変更(追加、削除、更新等)があった場合に通知するようにリスナーを登録。
    customers.addChangeListener(changeListener);
}

// バックグラウンドサービス
public class PollingService extends IntentService {
    @Override
    public void onHandleIntent(Intent intent) {
        Realm realm = Realm.getDefaultInstance();
        // 'json'変数へネットワーク呼び出しの結果を保持
        String json = customerApi.getCustomers();
        realm.beginTransaction();
        realm.createObjectFromJson(Customer.class, json); // 新たな顧客オブジェクトを保存
        realm.commitTransaction();
        // UIスレッド上のデータは自動的に更新されます
        // ...
    }
    // ...
}

バックグラウンドスレッドが新たな顧客を追加すると、UIスレッド側のcustomersリストが自動的に更新されます。

同じことはそれぞれのオブジェクトでも行われます。

バックグラウンドスレッドでは１つのオブジェクトのみを扱い、それを更新するだけでUIスレッドは自動的に最新の情報を入手することができます。変更があった際に何か処理を実行する必要がある場合は、上記のコードのようにリスナーを登録して通知を受け取ってください。

たったこれだけです。

複数スレッド間でRealmを使う

スレッド間での使用方法として注意することは、 Realm、RealmObject、RealmResultsインスタンスはスレッド間での受け渡しを行ってはいけない ということだけです。代わりに、非同期クエリや非同期トランザクションで処理をバックグラウンドスレッドにまかせ、結果を元のスレッドで受け取ることができます。

複数のスレッドで同じデータにアクセスしたい場合は、それぞれのスレッドで別々のRealmインスタンスを(Realm.getInstance(RealmConfiguration)や類似のメソッドを使って)取得する必要があります。取得したRealmインスタンスに対してクエリを発行することでオブジェクトを取得することができます。

それぞれのスレッドで取得したオブジェクトから、ディスク上の同じデータを読み書きすることが可能です。

スキーマ

デフォルトスキーマとはプロジェクトで定義されたすべてのモデルクラスのことになります。この挙動は変更することができます。

（例）特定のRealmには一部のモデルクラスのみ含めたい場合など

カスタムRealmModuleを作ることで、このような挙動を実現できます。

// カスタムモジュールを作成します
@RealmModule(classes = { Person.class, Dog.class })
public class MyModule {
}

// RealmConfigurationにモジュールに定義したモデルクラスのみを使用するように設定します
RealmConfiguration config = new RealmConfiguration.Builder(context)
  .modules(new MyModule())
  .build();

// 一つのスキーマで複数のモジュールを使用することができます
RealmConfiguration config = new RealmConfiguration.Builder(context)
  .modules(new MyModule(), new MyOtherModule())
  .build();

スキーマの共有

ライブラリ開発者の方へ: 内部でRealmを利用するライブラリは、RealmModuleを使ってスキーマを公開する必要があります。

ライブラリプロジェクトではデフォルトRealmModuleが作られないようにする必要があります。というのも、ライブラリにデフォルトモジュールが存在すると、ライブラリを利用するアプリケーションプロジェクトで作られるデフォルトRealmModuleと衝突してしまうからです。

下記はライブラリのRealmModuleを作って、ライブラリのモデルクラスをアプリケーションと共有する方法です。

// ライブラリ側はモジュールを必ず作成し、library = trueに設定する必要があります。
// こうすることでデフォルトモジュールが作られないようにします。
// allClasses = trueと設定するとライブラリに含まれるすべてのクラスを指定したことになります。
@RealmModule(library = true, allClasses = true)
public class MyLibraryModule {
}

// ライブラリ側では明示的にモジュールを設定しなければなりません
RealmConfiguration libraryConfig = new RealmConfiguration.Builder(context)
  .name("library.realm")
  .modules(new MyLibraryModule())
  .build();

// アプリケーション側ではライブラリのRealmModuleをスキーマに追加することができます
RealmConfiguration config = new RealmConfiguration.Builder(context)
  .name("app.realm")
  .modules(Realm.getDefaultModule(), new MyLibraryModule())
  .build();

現時点では、一つのファイルに複数のRealmModuleを記述することはできません。複数のRealmModuleを使用する場合は複数のファイルを作成し、それぞれのファイルに１つのRealmModule定義を行うようにしてください。

ライブラリプロジェクトとアプリケーションのプロジェクトを連携する際の完全なサンプルコードはこちらをご覧ください。

JSON

JSONデータから直接Realmオブジェクトを作ることができます。

読み込むことができるJSON データは、String、JSONObject、およびInputStreamです。

モデルクラスに対応するフィールドが定義されていないJSONプロパティは無視されます。

一つのオブジェクトを生成する場合は、Realm.createObjectFromJson()を使用します。 JSONデータに含まれるすべてのオブジェクトを生成する場合は、Realm.createAllFromJson()を使用します。

// 都市を表すRealmObject
public class City extends RealmObject {
    private String city;
    private int id;
    // getter/setterは省略
}

// 文字列から作成
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        realm.createObjectFromJson(City.class, "{ city: \"Copenhagen\", id: 1 }");
    }
});

// 複数のオブジェクトをInputStreamから作成
realm.executeTransaction(new Realm.Transaction() {
    @Override
    public void execute(Realm realm) {
        try {
            InputStream is = new FileInputStream(new File("path_to_file"));
            realm.createAllFromJson(City.class, is);
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }
});

RealmでのJSONのパースでは以下のルールが適用されます。

JSONに値としてnullをもつフィールドが含まれている場合のオブジェクト作成:
- null可のフィールドに対しては、値にnullをセットします。
- null不可のフィールドに対しては例外をスローします。
JSONに値としてnullをもつフィールドが含まれている場合のオブジェクト更新:
- null可のフィールドに対しては、値にnullをセットします。
- null不可のフィールドに対しては例外をスローします。
JSONに含まれていないフィールド:
- null可/null不可にかかわらず、既存の値を変更しません。

通知

変更を受け取るためのリスナーはLooperスレッド上でのみ機能します。非Looperスレッドの場合は、Realm.waitForChange()を使って手動で変更を反映させる必要があります。

リスナーを登録しておくと、バックグラウンドスレッドを使ってRealmのデータを更新したときに、UIスレッド、あるいは別のスレッドで変更に対する通知を受けることができます。通知は他のスレッド、またはプロセスによってRealmが変更されたときに送られます。

public class MyActivity extends Activity {
    private Realm realm;
    private RealmChangeListener realmListener;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      realm = Realm.getDefaultInstance();
      realmListener = new RealmChangeListener() {
        @Override
        public void onChange(Realm realm) {
            // ... （UIの更新など）通知に対する処理をします ...
        }};
      realm.addChangeListener(realmListener);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // リスナーを削除します
        realm.removeChangeListener(realmListener);
        // Realmインスタンスを閉じます
        realm.close();
    }
}

次のようにすると、簡単にリスナーをすべて削除することができます。

realm.removeAllChangeListeners();

リスナーが利用できるのはRealmだけではありません。RealmObjectやRealmResultsに対してもリスナーを登録することができます。

これらを使うことで、オブジェクトやクエリ結果の変更に対して処理を記述することができます。リスナーが呼び出される時には、関連するオブジェクトやクエリ結果は自動的に更新されているため手動でのリフレッシュは必要ありません。

public class MyActivity extends Activity {
    private Realm realm;
    private RealmChangeListener puppiesListener;
    private RealmChangeListener dogListener;

    private RealmResults<Dog> puppies;
    private Dog dog;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      realm = Realm.getDefaultInstance();
      puppiesListener = new RealmChangeListener() {
        @Override
        public void onChange(RealmResults<Dog> puppies) {
            // ... puppiesインスタンスが更新された際の処理
        }};

      // すべての子犬を取得
      puppies = realm.where(Dog.class).lessThanOrEqualTo("age", 2).findAll();
      puppies.addChangeListener(puppiesListener);

      dogListener = new RealmChangeListener() {
        @Override
        public void onChange(Dog dog) {
            // ... 特定の犬が更新された際の処理
        }};

      dog = realm.where(Dog.class).equalTo("name", "Fido").findFirst();
      dog.addChangeListener(dogListener);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // リスナーを解除
        puppies.removeChangeListener(puppiesListener);
        dog.removeChangeListener(dogListener);
        // Realmインスタンスの削除
        realm.close();
    }
}

最後に、特定のクラスに関連付けられたリスナーはそのクラスだけでなく、そのクラスが参照している型のオブジェクトに変更があった場合も通知を受けることができます。

詳しくは以下のコードを御覧ください。

Person person = realm.where(Person.class).findFirst();
person.getDogs(); // => 2 - ２つのDogを関連として保持しているとします
person.addChangeListener(new RealmChangeListener() {
                             @Override
                             public void onChange(Person person) {
                                 // Personの変更に対する処理を実装
                                 // Personが参照するクラスのオブジェクトに変更があった場合も呼ばれます
                             }
                         });
Dog dog = person.getDogs().get(0);
realm.beginTransaction();
dog.setAge(5);
realm.commitTransaction();
// 参照している方のオブジェクトに変更があったので、次回のイベントループでリスナーが呼ばれます

マイグレーション

データベースを使ってる場合、時間が経つにつれ、モデルクラスは変更されていくものです。 Realmでのモデルクラスは、標準的なクラスとして定義されていますので、インターフェースに変更を加えるだけで、簡単にモデル定義を変えられます。

古いスキーマのデータがディスクに保存されていない場合、モデル定義に変更を加えても問題なく動作します。しかし、古いスキーマのデータがディスクに保存されている場合、モデル定義に対して変更を加えるとコード上のモデル定義とディスクに保存されたファイル上のスキーマが一致しなくなり例外がスローされます。これは、RealmConfigurationに対してスキーマバージョンとマイグレーション処理を指定することで解決します。

RealmConfiguration config = new RealmConfiguration.Builder(context)
    .schemaVersion(2) // スキーマを変更したら必ず数字を増やしてください
    .migration(new MyMigration()) // コードが定義するモデルとディスク上のスキーマが一致しない場合に実行されるマイグレーション処理
    .build()

このようにすることで、必要に応じてマイグレーション処理が自動的に実行されます。マイグレーション処理では、Realmが提供するAPIを使用してディスクに保存されたファイルのスキーマ自体と古いスキーマに従って保存されたデータを更新することができます。

// 新たなモデルクラスを追加するマイグレーションの例
RealmMigration migration = new RealmMigration() {
  @Override
  public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {

     // DynamicRealmから変更可能なスキーマオブジェクトを取得します
     RealmSchema schema = realm.getSchema();

     // バージョン1へのマイグレーション: クラスの追加
     // Example:
     // public Person extends RealmObject {
     //     private String name;
     //     private int age;
     //     // getterとsetterは省略
     // }
     if (oldVersion == 0) {
        schema.create("Person")
            .addField("name", String.class)
            .addField("age", int.class);
        oldVersion++;
     }

     //バージョン2へのマイグレーション: プライマリキーと関連の追加
     // Example:
     // public Person extends RealmObject {
     //     private String name;
     //     @PrimaryKey
     //     private int age;
     //     private Dog favoriteDog;
     //     private RealmList<Dog> dogs;
     //     //getterとsetterは省略
     // }
     if (oldVersion == 1) {
        schema.get("Person")
            .addField("id", long.class, FieldAttribute.PRIMARY_KEY)
            .addRealmObjectField("favoriteDog", schema.get("Dog"))
            .addRealmListField("dogs", schema.get("Dog"));
        oldVersion++;
     }
  }
}

詳しくはmigrationSample appを参照してください。

Realmをオープンする時にディスクにRealmファイルがない場合は、マイグレーションの必要はありません。その場合は、Realmはその時のスキーマのモデル定義に従って、新しい.realmファイルを作成します。このことを利用して、開発中に頻繁にスキーマに変更があるが、 データが消えても問題がない場合 は、マイグレーションを行う代わりに.realmファイルを削除してしまう方法もあります。開発の初期段階でモデルに頻繁に変更がある場合などに有効です。

RealmConfiguration config = new RealmConfiguration.Builder(context)
    .deleteRealmIfMigrationNeeded()
    .build()

暗号化

Please take note of the Export Compliance section of our LICENSE, as it places restrictions against the usage of Realm if you are located in countries with an export restriction or embargo from the United States.

RealmConfiguration.Builder.encryptionKey()に512ビットの暗号化キーを渡すことで、ディスクに保存されるRealmファイルを暗号化することができます。

byte[] key = new byte[64];
new SecureRandom().nextBytes(key);
RealmConfiguration config = new RealmConfiguration.Builder(context)
  .encryptionKey(key)
  .build();

Realm realm = Realm.getInstance(config);

この機能を使うと、ディスクのデータはすべて透過的に、AES-256によって暗号化／復号されます。暗号化されたRealmをインスタンス化するには、ファイル作成時に使用された暗号化キーと同じものが毎回必要になります。

詳しくは、暗号化のサンプルコードをご覧ください。これは暗号化キーをKeyStore APIを使って安全に管理する方法を含みます。

アダプタ

OrderedRealmCollection(RealmResultsとRealmListはこのインタフェースを実装しています)のデータをUIコンポーネントとバインディングするための便利なクラスがあります。

RealmBaseAdapterは、ListViewにRealmのデータを表示する際に使用します。使い方は、サンプルプロジェクト内のMyListAdapter.javaを参照してください。
RealmRecyclerViewAdapterは、RecyclerViewにRealmのデータを表示する際に使用します。使い方は、サンプルプロジェクト内のMyRecyclerViewAdapter.javaを参照してください。

これらのアダプターを使うためには、アプリケーションのbuild.gradleに以下のように依存ライブラリを追加する必要があります。

dependencies {
	compile 'io.realm:android-adapters:1.3.0'
}

Intent

RealmObjectをIntent経由で直接渡すことは問題が多いので、渡したいオブジェクトの識別子をIntentに含める方法をおすすめします。

オブジェクトがプライマリキーを持っている場合は、それをIntentのextraとして渡してください。

// 'id'フィールドがプライマリキーになっているpersonオブジェクトがあるとします ...
Intent intent = new Intent(getActivity(), ReceivingService.class);
intent.putExtra("person_id", person.getId());
getActivity().startService(intent);

受け取り側(Activity、Service、IntentService、BroadcastReceiverなど)では、extraからプライマリキーの値を取り出し、クエリを用いてRealmからRealmObjectを取得します。

// onCreate()やonHandleIntent()など
String personId = intent.getStringExtra("person_id");
Realm realm = Realm.getDefaultInstance();
Person person = realm.where(Person.class).equalTo("id", personId).findFirst();
// ここでpersonに対する処理
realm.close();

完全なサンプルはthreadExampleにあります。

このプロジェクトでは、識別子を用いて受け渡しを行い、そこからRealmObjectを取得する典型的なコードが含まれています。

Androidフレームワークが提供するスレッド関連機能を扱う際の戦略

以下のクラスを使用する場合は注意が必要です。

AsyncTaskクラスはバックグラウンドスレッドで実行されるdoInBackground()メソッドを持っています。IntentServiceクラスにも、ワーカースレッドから呼び出されるonHandleIntent(Intent intent)メソッドがあります。

これらのメソッドの中でRealmを扱う必要がある場合は、メソッドの中でRealmのインスタンスを取得し、必要な処理が終わった後メソッドからリターンする前に確実にRealmをクローズしてください。

以下にいくつかの具体的な例を示します。

AsyncTask

以下のように、doInBackground()の中でRealmの取得とクローズを行ってください。

private class DownloadOrders extends AsyncTask<Void, Void, Long> {
    protected Long doInBackground(Void... voids) {
        // ここからはバックグラウンドスレッドで実行されています

        // Realmインスタンスの取得
        Realm realm = Realm.getDefaultInstance();
        try {
            // Realmを使った処理
            realm.createAllFromJson(Order.class, api.getNewOrders());
            Order firstOrder = realm.where(Order.class).findFirst();
            long orderId = firstOrder.getId(); // Id of order
            return orderId;
        } finally {
            realm.close();
        }
    }

    protected void onPostExecute(Long orderId) {
        // このメソッドはメインスレッドで実行されます
        // 注文(Order)IDを使ってRealmにクエリを発行して注文イブジェクトを取得します
        // 取得したインスタンスを使って処理を行ってください
    }
}

IntentService

IntentServiceはLooperスレッドを持っていますが、ChangeListenerを利用することはできません。というのも、殆どの場合onHandleIntent()の実行ごとにスレッドが作りなおされてしまい、Looperが”loop”しないからです。Looperスレッドではあるので問題なくリスナーを登録することはできますが、多くの場合呼び出されることはありません。

以下のように、onHandleIntent()の中でRealmの取得とクローズを行ってください。

public class OrdersIntentService extends IntentService {
    public OrdersIntentService(String name) {
        super("OrdersIntentService");
    }

    @Override
    protected void onHandleIntent(Intent intent) {
        // ここからはバックグラウンドスレッドで実行されています

        // Realmインスタンスの取得
        Realm realm = Realm.getDefaultInstance();
        // Realmを使った処理
        realm.createAllFromJson(Order.class, api.getNewOrders());
        Order firstOrder = realm.where(Order.class).findFirst();
        long orderId = firstOrder.getId(); // Id of order
        realm.close();
    }
}

サードパーティ製ライブラリと連携する

このセクションでは、Androidアプリケーションでよく使われるその他のライブラリとRealmを組み合わせる方法ついて説明します。

GSON

GSONは、JSONをシリアライズ／デシリアライズするGoogle製のライブラリです。GSONは特別な設定等は不要でそのままRealmとともに使用可能です。、

// Userクラスを定義します
public class User extends RealmObject {
    private String name;
    private String email;
    // getter/setterは省略
}

Gson gson = new GsonBuilder().create();
String json = "{ name : 'John', email : 'john@corporation.com' }";
User user = gson.fromJson(json, User.class);

RealmとGSONを組み合わせるサンプルコードとして、GridViewExampleも参考にしてください。

シリアライズ

Retrofitなどのライブラリで使用するような場合、デシリアライズだけでなくシリアライズも必要になります。

シリアライズについては、GSONのデフォルトのままではRealmオブジェクトをシリアライズすることはできません。 GSONはgetter/setterを使わず、直接インスタンス変数を参照するためです。

GSONを使ったRealmオブジェクトのJSONシリアライズを正しく動作させるためには、それぞれのモデルに対してカスタムJsonSerializerとTypeAdapterを書く必要があります。

このGistにあるコードは、それらをどのように書けばよいかを示しています。

プリミティブ型の配列

JSON APIは数値や文字列型のようなプリミティブ型（オブジェクト型ではない）の配列を含むことがあります。そのような配列を表現することは現時点のRealmではサポートされていません。

JSON APIを変更するのが不可能な場合、カスタムTypeAdapterを用いて、JSONのプリミティブ型をRealmオブジェクトに自動でマッピングするようにカスタマイズすることができます。

このGistは数値型の配列をRealmオブジェクトでラップするサンプルコードです。

トラブルシューティング

Realmオブジェクトは内部に循環参照を持ったフィールドを保持している場合があります。このような場合、GSONはStackOverflowErrorエラーをスローします。過去には、RealmオブジェクトがフィールドにDrawableオブジェクトを保持しているためこの現象が発生したことがあります。

public class Person extends RealmObject {
    @Ignore
    Drawable avatar;
    // 他のフィールドやgetter/setter
}

このPersonクラスは、@IgnoreアノテーションのついたフィールドにAndroidのDrawableを保持しています。GSONがこのオブジェクトをシリアライズする際、Drawableに対する処理でStackOverflowErrorが発生していました(GitHub Issue)。これを解決するためには、以下のコードをshouldSkipFieldメソッドに記述してください。

public boolean shouldSkipField(FieldAttributes f) {
  return f.getDeclaringClass().equals(RealmObject.class) || f.getDeclaringClass().equals(Drawable.class);
}

Drawable.classの部分に注目してください。この部分によって、シリアライズの際にDrawable型のフィールドはスキップされます。

Jackson-databind

Jackson-databindは、JSONデータをJavaクラスのインスタンスへ変換するライブラリです。

Jacksonは変換を行うためにリフレクションを使用していますが、これはRealmのRxJavaサポートと競合します。というのも、セットアップによってはRxJavaのクラスをクラスローダーでロードできない場合があるからです。その場合、以下のような例外がスローされます。

java.lang.NoClassDefFoundError: rx.Observable
at libcore.reflect.InternalNames.getClass(InternalNames.java:55)
...

これを解決するためには、RxJavaへの依存を追加し実際にロードできるようにするか、以下のようなダミーファイルを作成する必要があります。

package rx;

public class Observable {
    // RxJavaのクラスが依存ライブラリに含まれていない場合に
    // Jackson-Databindのエラーを回避するためのダミーファイル
}

この問題は、Jacksonプロジェクトにも報告されています。

Kotlin

RealmはKotlinとともに使用することができます。しかし、いくつか注意すべき点があります。

モデルクラスはopenであること。
現在のKotlinのアノテーションプロセッサの制限のため、モデルクラスに@RealmClassアノテーションを付与しなければならない場合が存在します。
多くのRealm APIがJavaのクラスオブジェクトを必要とするため。依存ライブラリにorg.jetbrains.kotlin:kotlin-reflect:${kotlin_version}を含める必要があります。

具体的な例は、こちらのサンプルプロジェクトを参照してください。

Parceler

ParcelerはオブジェクトをParcelableにするために必要な、煩雑なコードを書かずにすむように、自動的にアノテーションによって生成するライブラリです。

RealmはProxyクラスを使っているので、Parcelerを使うには、さらに次に示すような設定がRealmのモデルクラスには必要になります。

// RealmObjectを継承するすべてのクラスは対応するRealmProxyクラスが生成されます。
// ParcelerにこのRealmProxyクラスの存在を伝える必要があります。
// RealmProxyクラスは、一度アプリケーションをコンパイルしないと生成されないことに気をつけてください
@Parcel(implementations = { PersonRealmProxy.class },
        value = Parcel.Serialization.BEAN,
        analyze = { Person.class })
public class Person extends RealmObject {
    // ...
}

Parcelerを使用する場合は、build.gradleで以下の設定が行われていることを確認してください。詳細はこちらを参照してください。

compile "org.parceler:parceler-api:1.0.3"
apt "org.parceler:parceler:1.0.3"

また、Parcelerを使う時には重要な制限事項がいくつかあります。

モデルクラスの定義がRealmListを含む場合は、特別なアダプタクラスを登録する必要があります。
Realmオブジェクトが一度Percel化されると、Realmの管理から外れた状態になります。そして、Realmオブジェクトはその時点のデータをスナップショットとして持つ、Realmの管理下にないオブジェクトとして振る舞います。その後に、どのような変更をしてもRealmには保存されません。

Retrofit

Retrofitは、REST APIを簡単にかつタイプセーフに扱うことのできるSquare製のライブラリです。

Retrofit1系、2系ともにRealmとともに使用することができますが。ただし、Retrofitが自動的にRealmにオブジェクトを保存してはくれないのでrealm.copyToRealm()やrealm.copyToRealmOrUpdate()を用いてRealmに保存するコードを記述する必要があります。

GitHubService service = restAdapter.create(GitHubService.class);
List<Repo> repos = service.listRepos("octocat");

// RetrofitからRealmへ要素をコピーします
realm.beginTransaction();
List<Repo> realmRepos = realm.copyToRealmOrUpdate(repos);
realm.commitTransaction();

Robolectric

Robolectricは、デバイスやエミュレータの代わりにJVM上で直接、JUnitテストを動作させるライブラリです。

RobolectricはRealmにバンドルされているようなネイティブライブラリを動かすことをまだサポートしていないので、Robolectricを使ってRealmのテストを行うことはできません。

詳しくはこちらのRobolectricに対する機能リクエストをご覧ください: https://github.com/robolectric/robolectric/issues/1389

RxJava

RxJavaは、NetflixがリリースしているReactive Extensionsライブラリで、Observer patternを拡張したものです。RxJavaはデータに対する変更を監視するとともに、様々な処理を組み合わせてデータに適用することを可能にします。

RealmはRxJavaをサポートしています。これは、以下のRealmのクラスに対するObservableオブジェクトが利用できるということを意味します: Realm、 RealmResults、 RealmObject、 DynamicRealm、DynamicRealmObject

// Realm、Retrofit、RxJavaを組み合わせる例（簡潔に表現するためにRetroLambdaの記法を使用）。
// すべてのPersonを読み込み、それぞれのGitHubの情報を取得して表示。
Realm realm = Realm.getDefaultInstance();
GitHubService api = retrofit.create(GitHubService.class);
realm.where(Person.class).isNotNull("username").findAllAsync().asObservable()
    .filter(persons.isLoaded)
    .flatMap(persons -> Observable.from(persons))
    .flatMap(person -> api.user(person.getGithubUserName())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(user -> showUser(user));

非同期クエリはノンブロッキングなので、即座にRealmResultsインスタンスを返すことに注意する必要があります。クエリが完了したリストのみを扱いたい場合(たいていの場合はそうだと思います)は、filterオペレータの中でRealmResults<E>.isLoaded()を使ってObservableをフィルタリングする必要があります。

RealmResultsのロードが完了しているかを調べることで、クエリの実行が終わったかどうかを調べることができます。

詳しくはRxJavaサンプルプロジェクトを参照してください。

RxJavaに関する設定

RxJavaは必須の依存ライブラリではありません。これは、Realmが自動的にRxJavaのライブラリを依存ライブラリに含めてはくれないことを意味しています。Realmを利用するアプリでどのバージョンのRxJavaを使用するか決めることができます。また、RxJavaを含めないようにすることで、メソッド数の増加を抑えることも可能です。RxJavaを使用する場合は、build.gradleに依存ライブラリとして明示的に追加してください。

dependencies {
  compile 'io.reactivex:rxjava:1.1.0'
}

RxObservableFactoryを実装することで、RealmがどのようにObservableインスタンスを作成するかをカスタマイズすることができます。この設定は、RealmConfigurationで行います。

RealmConfiguration config = new RealmConfiguration.Builder(context)
  .rxFactory(new MyRxFactory())
  .build()

RxObservableFactoryが提供されない場合、RealmはRxJava 1.1.*をサポートするRealmObservableFactoryをデフォルトのRxObservableFactoryとして使用します。

テストとデバッグ

RealmをJUnit3、JUnit4、Robolectric、Mockito、PowerMockと組み合わせる方法については、unitTestExampleを御覧ください。

Android Studioでのデバッグ

Android StudioやIntelliJを使う際に気をつけなければならない落とし穴があります。それは、デバッグ機能が表示する値が、実際の値とは違う場合があるということです。

例えば、RealmObjectのフィールドの値を表示させた時に、実際にRealmが保持している値とは異なる値が表示されることがあります。というのも、Android Studioが表示しているフィールドが実際には使われていないことがあるからです。

Realmは永続化されているデータに対して読み書きを行うために、モデルクラスに対してビルドの際にプロキシクラスを生成し、getterとsetterをオーバーライドします(詳細はこちら)。フィールドではなく、実際にアクセッサメソッドが返す値に対しては正しい値を表示します。以下のスクリーンショットで実際にどのように表示されるかが確認できます。

Android Studio, IntelliJ Debug RealmObject

このスクリーンショットでは、デバッガは113行目で停止しています。personとperson.getName()とperson.getAge()の３つに注目してください。107行目から111行目で、personインスタンスの値を更新しています。113行目でデバッガが停止していますが、表示されているフィールドの値は更新した値とは異なったものになっています。person.getName()とperson.getAge()が表示している値のみが正しいことを確認してください。

RealmObjectの.toString()メソッドは正しい値を表示しているにもかかわらず、フィールドの値を表示させると実際とは異なる値が表示されることに注意してください。

NDK部分のデバッグ

Realmはネイティブコードを含んだライブラリです。Crashlyticsのようなクラッシュレポーティングツールでネイティブエラーの情報を収集することで、バグの発生時により有益な情報を得られる可能性が高まります。

ネイティブコードのクラッシュの際はデフォルトのスタックトレースに含まれる情報はあまり役に立たず、デバッグが困難であることがよくあります。Crashlyticsはネイティブクラッシュの際に有用な情報を取得する機能を持っています。この機能を有効にするには、こちらのガイドに従ってください。androidNdkOutおよびandroidNdkLibsOutの指定は不要です。

crashlytics {
  enableNdk true
}

現バージョンにおける制限事項

Realmはできるかぎり制限なく利用できるよう努力しています。また、利用していただいている方々からのフィードバックを元に新しい機能を追加していきます。現時点で存在する制限事項について以下にまとめます。

詳細については、GitHub issues をご覧ください。

一般的な制限事項

Realmは、柔軟性とパフォーマンスのバランスを上手く保つため、保存するデータに対していくつか制約があります。

クラス名は57文字が上限です。Realmの内部では、class_という文字をクラス名の前に付けて扱われます。Realm Browserはこの文字列もクラス名の一部として表示します。
フィールド名は63文字が上限です。
ネストしたトランザクションはサポートしていません。検出された場合、例外が投げられます。
文字列とバイト配列（byte[]）は16MBが上限です。

ソートと検索の際の文字列の扱い

文字列に対するソートと大文字小文字を区別しない(Case.INSENSITIVE)検索については、Latin Basic、Latin Supplement、Latin Extended A、Latin Extended Bの文字セット（UTF-8の範囲は、0-591）のみをサポートしています。具体的には、equalTo()、contains()、endsWith()、beginsWith()のクエリです。詳しくはこちらをご覧ください。

スレッド

Realmは、複数の異なるスレッドから同じRealmファイルに同時にアクセスすることができますが、スレッド間で、Realm、Realmオブジェクト、クエリ、RealmResultsを渡すことはできません。

マルチスレッド環境におけるRealmの使い方について、マルチスレッドのサンプルコードをご覧ください。また、詳しくはこちらに記載されています。

複数のプロセスからのRealmファイルへのアクセス

複数の異なるスレッドから同時にRealmファイルへアクセスすることができますが、複数のプロセスから同時にアクセスすることはできません。

Realmファイルを異なるプロセスで同時に使用するときは、Realmファイルをコピーするか新しく作成してください。

複数のプロセスからの同時アクセスについては、まもなくサポートされる予定です。

RealmObjectのhashCode

RealmObjectはライブなオブジェクトなので、他のスレッドから変更されることがあります。RealmObject.equals()がtrueになるRealmObject同士ではRealmObject.hashCode()も同じ値を返さなければいけませんが、RealmObject.hashCode()が返す値は変わる可能性があるためHashMapやHashSetのキーとしてRealmObjectを使うことは避けてください。

オブジェクト自身を変更しない場合であっても、他のオブジェクトの削除等に伴ってRealmObject.hashCode()が変わることもあります。

ベストプラクティス

Androidとの連携

RealmはAndroidで使うことを前提に設計されています。気をつけなければいけない点は、RealmObjectはスレッド間で受け渡せないということです。このことをしっかりと理解することで、アクティビティ間、バックグラウンドサービスやブロードキャストレシーバーとの間などいろいろなところでRealmのオブジェクトを扱えるようになります。

Application Not Responding(ANR)エラーを回避する

一般的にはRealmはAndroidのメインスレッド上で読み書きを行っても問題ないほどに十分高速です。しかし書き込みトランザクションはすべての他のスレッドの書き込みトランザクションをブロックしてしまうので、Realmへの書き込み操作は常に（Androidのメインスレッドではなく）バックグラウンドスレッドで行うことを推奨します。バックグラウンドスレッドで書き込み処理を行う方法については、非同期トランザクションを参照してください。

Realmインスタンスのライフサイクルを制御する

RealmObjectやRealmResultsは参照するすべてのデータを遅延ロードします。そのため、RealmObjectやRealmResultsにアクセスする必要がある間はRealmインスタンスをオープンしたままにしておくことが必要です。オープンやクローズにかかるオーバーヘッドを避けるため、Realmは内部で参照カウントによるキャッシングを行っています。つまり、オーバーヘッドを気にせずにRealm.getDefaultInstance()を何度も実行でき、実行した回数だけクローズを行えば関連するリソースはすべて解放されることを意味します。

UIスレッドでは、RealmインスタンスはActivityやFragmentごとにオープンし、それらが破棄される際にクローズすることが最も安全で簡単な実装方法ということになります。

// RealmをApplicationクラスでセットアップします
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        RealmConfiguration realmConfiguration = new RealmConfiguration.Builder(this).build();
        Realm.setDefaultConfiguration(realmConfiguration);
    }
}

// onCreate()/onDestroy()はアクティビティ間の遷移でライフサイクルに重なる部分があるので、
// Activity 2 の onCreate() は Activity 1 の onDestroy() より後に実行されます。
public class MyActivity extends Activity {
    private Realm realm;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        realm = Realm.getDefaultInstance();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        realm.close();
    }
}

// FragmentではonDestroy()が呼ばれない場合があるので、onStart()/onStop()を使用してください。
public class MyFragment extends Fragment {
    private Realm realm;

    @Override
    public void onStart() {
        super.onStart();
        realm = Realm.getDefaultInstance();
    }

    @Override
    public void onStop() {
        super.onStop();
        realm.close();
    }
}

RealmResultsとRealmObjectsの再利用

UIスレッドやその他のすべてのLooperスレッドでは、すべてのRealmObjectやRealmResultsはRealmへの変更が行われると自動的にリフレッシュが行われ変更が反映されます。このことは、RealmChangedListenerが呼び出された際にRealmObjectやRealmResultsを取得しなおす必要がないことを意味しています。これらのオブジェクトはその時点でアップデート済みなので、そのまま更新後の値を表示するために使用することができます。

public class MyActivity extends Activity {

    private Realm realm;
    private RealmResults<Person> allPersons;
    private RealmChangeListener realmListener = new RealmChangeListener() {
        @Override
        public void onChange(Realm realm) {
            // ビューの再描画を要求するだけです。`allPersons`には既に最新のデータが反映されています。
            invalidateView();
        }
    };

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        realm = Realm.getDefaultInstance();
        realm.addRealmChangeListener(listener);
        allPerson = realm.where(Person.class).findAll(); // "live"なオブジェクトを取得
        setupViews(); // ビューのセットアップ
        invalidateView(); // 現在のデータでビューの描画を要求
    }

    // ...
}

レシピ

Realmをつかって特定のタスクを実装する際のレシピとして、いくつかのリンクを用意しました。今後拡充していく予定です。

この他にもサンプルコードの要望がある場合は、GitHubにissueを作成してください。

制限事項

現時点では、final、transient、volatileを付与したフィールドはサポートされません。これは主に、Realmの管理下にあるオブジェクトとRealmの管理下にないオブジェクトとの振る舞いの食い違いを避けることが目的です。

Realmのモデルクラスは、RealmObject以外のクラスを継承することはできません。モデルクラスでは、デフォルトコンストラクタ(引き数なしpublicコンストラクタ)の中を空にしておく必要があります。というのも、デフォルトコンストラクタがフィールドにアクセスしてしまうと、モデルクラスにRealmインスタンスがセットされていることを前提とした処理が実行されてしまうからです。実際にはデフォルトコンストラクタが実行される時点ではRealmインスタンスがセットされていないため、例外がスローされます。デフォルトコンストラクタ以外のコンストラクタを作成することは問題ありません。

FAQ

どのようにすれば、Realmファイルを閲覧することができますか?

このStackOverflowの質問で、Realmファイルの保存場所について説明しています。

Realmファイルの内容については、Realm Browserを使うことで閲覧できます。

Realmのライブラリは、どのくらいの容量がありますか？

アプリケーションをリリースビルドすると、たいていの場合は、APKが800KBほど増加します。現在、配布されているRealmのライブラリは複数のアーキテクチャ（ARM7、ARMv7、ARM64、x86、MIPS）が含まれてるため、著しく大きくなっています。

Androidインストーラは、アプリケーションのインストール時に、そのデバイスのアーキテクチャ用のネイティブコードのみをインストールします。最終的にインストールされるアプリケーションの容量は、APKファイルよりも小さくなります。

アーキテクチャごとにAPKファイルを分割することで、それぞれのAPKファイルのサイズを小さくすることができます。build.gradleに以下の記述を行うことで、Androidビルドツールが持っているABI Splitの機能を利用できます。

splits {
    abi {
        enable true
        reset()
        include 'armeabi', 'armeabi-v7a', 'arm64-v8a', 'mips', 'x86', 'x86_64'
    }
}

どのアーキテクチャ用のAPKファイルを作成するか指定します。ABI Split機能の詳細については、Android Toolsドキュメントを参照してください。

サンプルプロジェクトがGitHubにあります。

Realmをプロダクション環境で使うことはできますか？

Realmは、2012年から商用のプロダクトで利用されています。

現在のRealmを利用する場合は、RealmのJava APIが、コミュニティのフィードバックを受けて変わりうるものだとしてお使いください。機能追加、不具合の修正も同様に考えてください。

Realmを使うために料金を支払う必要がありますか？

いいえ、Realmは完全に無料です。商用の製品で利用することも可能です。

Realmはどのようなビジネスプランなのですか？

すでにエンタープライズ向けの商品の販売や、周辺サービスによって収益を得ています。もし現在リリースされているrealm-java以上の機能が必要であれば、いつでもメールで、お気軽にご連絡ください。

また私たちのビジネスとは関係なく、realm-javaはオープンソースのまま開発を続け、Apache License 2.0として公開し続けます。

“core”という文字をコードの中で見たのですが、これは何ですか?

“core”または“Realm Core”というのは、C++で実装されたストレージエンジンの名前です。現在、コアのソースコードはオープンソースではありませんが、近い将来Apache License 2.0で公開する予定です。バイナリについては、Realm Core Binary Licenseで利用可能です。

通常のJavaオブジェクトとRealmオブジェクトの違いは何ですか？

主な違いは、Javaオブジェクトはインスタンス変数により値を直接保持していますが、Realmオブジェクトは、データそのものは保持しておらず、必要になったときに直接データベースからから値を取得するという仕組みになっています。

RealmオブジェクトのインスタンスはRealmの管理下にある(managed)か、Realmの管理下にない(unmanaged)かのいずれかです。

Realmの管理下にある(managed)オブジェクトはRealm内に永続化されています。別のスレッドで値が更新された場合でも常に最新の値が自動的に反映されますが、取得したスレッド上でしか利用することができません。後述するRealm管理下にない(unmanaged)オブジェクトと比較すると一般的に軽量です。というのも、永続化された値をJavaのヒープ上に持たないからです。
Realm管理下にない(unmanaged)オブジェクトは、通常のJavaのオブジェクトと同じです。そのため、データは永続化されず自動的な更新も行われませんが、自由にスレッドをまたいで受け渡すことができます。

これらの２つの種類のオブジェクトは、Realm.copyToRealm()とRealm.copyFromRealm()を使用することで相互に変換することができます。

なぜモデルクラスの定義で、RealmObject を継承する必要があるのですか?

主な理由は、モデルクラスに特定の機能を追加するためです。また、APIでジェネリクスを使用する際にも利用され、読みやすく、使いやすいAPIを提供することを可能にしています。

RealmObjectを継承したくない場合は、代わりにRealmModelインタフェースを実装することもできます。

RealmProxy クラスとは何ですか？

RealmProxyクラスは、オブジェクトがデータを持たないようにし、必要に応じてデータベースのデータを（遅延して）直接読み書きすることを実現するために必要です。

Realmのアノテーションプロセッサが、プロジェクト内の各モデルクラスのRealmProxyクラスを生成します。生成されたクラスは、モデルクラスを拡張し、Realm.createObject()が呼ばれたときに、返されます。しかし、コーディング中にProxyクラスを意識することはほとんどありません。

なぜ書き込み処理にはトランザクションを使う必要があるのですか？

トランザクションは、複数フィールドに対する更新について、それがアトミックに行われることを保証するためのものです。

トランザクションの範囲をはっきりさせることによって、変更を確定するかロールバックするかのどちらかになります（エラーが起こった場合は、ロールバックします）。

また、トランザクションの範囲を明確にしておくことで、変更を確定するタイミングをどのくらい頻繁に行うのかコントロールできます（たとえば、複数の更新を一つの操作として扱えます）。

SQLiteのようなSQLベースのデータベースで、複数のフィールドを一度に更新するような操作をしたとします。この時、自動的にトランザクションが発生しますが、普通はユーザーは意識しません。

しかし、Realmでは、トランザクションはいつも明示的に書きます。

メモリ不足の例外が出た時はどうすべきですか？

Realmは組み込みストレージエンジンです。

ストレージエンジンは、JVMのヒープ上にメモリを確保するかわりにネイティブ領域に確保します。ストレージエンジンがネイティブ領域にメモリを確保できない場合や、ストレージに空きがない場合にio.realm.internal.OutOfMemoryErrorをスローします。

このエラーは空のcatch節等で無視するべきではありません。もし無視してアプリを動かし続けた場合は、Realmファイルが破損する可能性があります。io.realm.internal.OutOfMemoryErrorが発生した場合は、アプリを終了させるのが最も安全な対処方法です。

ファイルサイズと中間バージョンについて

SQLiteなどにデータを保存した時より、ディスクの使用容量が少なくなることを期待されることかと思います。

データの一貫性を保つために、Realmは最新のデータにアクセスしたときのみ履歴をアップデートします。このことは、別のスレッドが多くのデータを長い時間をかけて書き込んでいる最中にデータを読み出そうとした場合、履歴はアップデートされずに古いデータを読み出すことになります。結果として、履歴の中間データが増加していくことになります。

この余分な領域は、最終的には再利用されるか消去されます。（強制的に空き領域を消去するには、compactRealmを用いて空き領域を最適化します。）

Mixpanelへの通信が行われているようですがこれは何ですか？

Realmを使用したアプリケーションをビルドする際、Realmは匿名の統計情報を収集しています。収集される情報は完全に匿名化されたもので、プロダクトの改善やサポートの廃止を検討する際にどのバージョンのRealmが使用されているか、どのOS上で使われているかなどの情報を利用しています。統計情報の収集はアプリを実行しているユーザーのデバイス上で行われることはありません。 — ビルド時にソースコードのアノテーションを処理する時のみに行われます。どのような情報がどのように収集されるかについて正確に確認したい場合は、ソースコードを参照してください。

“librealm-jni.so”がロードできないというエラーが発生します。

アプリケーションが64bitアーキテクチャをサポートしていないネイティブライブラリを使用していた場合、ARM64デバイスのAndroidはRealmのlibrealm-jni.soのロードを行うことができません。これは、Androidが32bitと64bitのネイティブライブラリを同時にはロードできないためです。理想的な解決策はサポートする全てのABIのライブラリを揃えることですが、3rdパーティライブラリを使用している場合不可能なことがあります。詳細はVLC and realm Library conflictsを参照してください。

この場合のワークアラウンドは、RealmのARM64版ライブラリをAPKから除外することです。そのためには、build.gradleに以下の設定を追加します。詳しくはMixing 32- and 64-bit Dependencies in Androidを参照してください。

android {
    //...
    packagingOptions {
        exclude "lib/arm64-v8a/librealm-jni.so"
    }
    //...
}

Android Gradle プラグイン 1.4.0betaには、Jarファイル中の.soファイルを正しくパッケージングできないというバグがあります。詳細はRealm Java issue 1421を参照してください。Android Gradleプラグイン1.3.0に戻すが、1.5.0以降を使用することでこの問題を回避することができます。

Realmファイルのバックアップとリストアはどのように行えばよいでしょうか

Realmはファイルシステム上にファイルとして保存されます。getPath()を用いることでこのファイルの絶対パスを取得することができます。バックアップ/リストアを行う場合は、すべてのRealmインスタンスを閉じた状態で行ってください。

RealmファイルをGoogleDrive上にバックアップする方法について、以下のページに詳細な説明がなされています(英語)。

Platform

Database

Studio

はじめに

必要条件

インストール

ProGuard

Realm Browser

APIリファレンス

サンプルコード

ヘルプ

モデル

対応しているデータ型

必須フィールドとnull値

保存しないプロパティ

オブジェクトの自動更新

インデックス付きプロパティ

プライマリキー

モデルクラスのカスタマイズ

RealmModelインタフェース

リレーションシップ（関連）

多対１のリレーションシップ

多対多のリレーションシップ

関連に対するクエリ

書き込み

オブジェクトの作成

トランザクションブロック

非同期トランザクション

バイト配列の更新

クエリ

検索条件を指定する

修飾子

論理演算子

並べ替え

クエリの連鎖

クエリの自動更新

型を使ったオブジェクトの取得

集計

繰り返し処理

削除

非同期クエリ

クエリの作成

コールバックの登録

クエリの完了チェック

非同期クエリの強制ロード

非 Looper スレッド

Realmについて

Realmの設定をカスタマイズする

デフォルトRealm

In-Memory Realm

Dynamic Realms

Realmインスタンスを閉じる

オートリフレッシュ

Realmファイルの探し方

スレッド

Realmをマルチスレッドで使う場合のサンプル

複数スレッド間でRealmを使う

スキーマ

スキーマの共有

JSON

通知

マイグレーション

暗号化

アダプタ

Intent

Androidフレームワークが提供するスレッド関連機能を扱う際の戦略

AsyncTask

IntentService

サードパーティ製ライブラリと連携する

GSON

シリアライズ

プリミティブ型の配列

トラブルシューティング

Jackson-databind

Kotlin

Parceler

Retrofit

Robolectric

RxJava

RxJavaに関する設定