This is not the current version. View the latest documentation

Getting started

Realm for Android is at a very early stage! This is just a preview of work in progress to enable early feedback. The API is not stable, many methods are not yet implemented and you can expect it to change rapidly over the coming weeks. Moreover, the binding is not thoroughly tested so you might run into a bug here and there. In other words, use this to get an idea about the upcoming release and to give us feedback in order to make it the way you like!

At the moment, we do not support Java outside of Android.

Prerequisites

  • Android Studio (>= 0.8.6)
  • A recent Android SDK

Installation

  1. Download the release package and unzip.
  2. Create a new project with Android Studio
  3. Copy the realm folder into the root folder of the new project (beside app, not inside it)
  4. Copy the realm-annotations-processor-VERSION.jar file to into app/libs (VERSION is the current version number)
  5. Add the following line to the settings.gradle file:

    include ':realm'
  6. Add the following buildscript dependency to the build.gradle file in the root folder of the project

    classpath 'com.neenbedankt.gradle.plugins:android-apt:1.3'
  7. Add the following plugin inclusion in the top of the app/build.gradle file

    apply plugin: 'android-apt'
  8. Replace the dependencies section of the app/build.gradle file with:

    dependencies {
         apt fileTree(dir: 'libs', include: ['*.jar'])
         compile project(':realm')
     }
  9. In the Android Studio menu: Tools->Android->Sync Project with Gradle Files

Examples

The RealmBasicExample in the root folder contains a simple example of how you use the current API. You just Import Project in Android Studio and run. There will only be a little output in the Log, so checkout the code to see examples of simple use of the API.

The RealmGridViewExample is a trivial app that shows how to use Realm as the backing store for a GridView. It also shows how you could populate the database with json. You just Import Project in Android Studio and run. You should then see a simple gridview on the screen.

Help & feedback

We rely on you to send your questions, as well as your candid feedback to help shape Realm for Android! Please send all communication to [email protected], where it will be seen by our entire Java team.

You can also sign up for our community newsletter to get regular tips, learn about other use-cases and get alerted of blogposts and tutorials about Realm.

Models

Realm data models are defined by implementing a traditional Java Bean.

public class User extends RealmObject {
    // Properties
    private String          name;
    private int             age;
    private String          email;
    private User            boss;
    private RealmList<User> friends;

    // Getters and Setters
    public String getName() { return name; }
    public void   setName(String name) { this.name = name; }
    public int    getAge(int age) { return age; }
    public void   setAge(int age) { this.age = age; }
    public String getEmail() { return email; }
    public void   setEmail(String email) { this.email = email; }
    public User   getBoss() { return boss; }
    public void   setBoss(Boss boss) { this.boss = boss; }
    public RealmList<User> getFriends() { return friends; }
    public void   setFriends(RealmList<User> friends) { this.friends = friends; }
}

Realm backed objects must be instantiated from the Realm using the create() method.

Instantiating a Realm

To get started with realm we create a new instance of a Realm (filename default.realm):

Realm realm = new Realm(this);

Or specify a particular Realm:

Realm realm = new Realm(this, "allmymovies.realm");

Writes

Read operations are implicit, but all write operations (adding, modifying, and removing objects) must be wrapped in write transactions to work:

try {
    realm.beginWrite();

    //... do writes here ...

    realm.commit();
} catch (Exception e) {
    e.printStackTrace();
    // ... recover from error ...
}

To add a new object to the Realm, it must be instantiated through the Realm:

User user = realm.create(User.class);

This gives us a new User instance, which we can populate with data:

user.setName("John");
user.setEmail("[email protected]");

Queries

One benefit of using Realm is that you get access to a fast query engine.

To find all users named John you would write:

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

This gives you a new RealmResults, of users with the name John. Objects are not copied - you get a list of references to the matching objects, and you work directly with the original objects that matches your query.

A more complex query where you find all Johns who are older than 10 can be written as:

RealmResults<User> result = realm.where(User.class).greaterThan("age", 10).equalTo("name", "John").findAll();

Notice, that each condition is implicitly logical-and together. Logical-or must be applied explicitly.

A RealmResults also has various aggregation methods:

double average = result.average("age");
long   sum     = result.sum("age").longValue();

and you can sort a list and get a new list:

RealmResults<User> sortedUsers = result.sort("name");

or even remove all objects found:

result.clear();

Nested queries are useful when you gradually filter your data:

RealmResults<User> teenagers = Realm.where(User.class).between("age", 13, 20).findAll();
RealmResults<User> johns = teenagers.where().equalTo("name", "John").findAll();

Iterations

To iterate through all objects in a RealmResults you can use a traditional for loop:

for (int i = 0; i < result.size(); i++) {
    User u = result.get(i);
    // ... do something with the object ...
}

Or you can take advantage of Iterable:

for (User u : result) {
    // ... do something with the object ...
}

Notifications

You can add a listener which is executed when a Realm is changed (by another thread or process):

realm.addChangeListener(new RealmChangeListener() {
    @Override
    public void onChange() {
        realm.refresh(); // get all the updates
        // ... do something with the updates (UI, etc.) ...
    }
});

You can easily close all listeners:

realm.removeAllChangeListeners();

Relationships

You can relate objects using links. First, define a simple data model (a contact can have 0, 1, or more phone numbers):

public class Phone extends RealmObject {
    private String number;
    // ... setters and getters left out
}

public class Contact extends RealmObject {
    private String name;
    private RealmList<Phone> phones;
    // ... setters and getters left out
}

Add a contact with two phones:

realm.beginWrite();
Contact contact = realm.create(Contact.class);
contact.setName("John Doe");

Phone phone1 = realm.create(Phone.class);
phone1.setNumber("555-1234-567");
contact.getPhones().add(phone1);

Phone phone2 = realm.create(Phone.class);
phone2.setNumber("555-765-4321");
contact.getPhones().add(phone2);

realm.commit();

Next

Much more is in the works, including basic features, tests, examples and documentation.

Since this is early work, we really appreciate your feedback! [email protected]