作者：郭霖
原文作者：带心情去旅行
原文地址：http://www.jianshu.com/u/769d3d3a9d4b
介绍
Realm 是一个 MVCC （多版本并发控制）数据库，由 Y Combinator 公司在2014年7月发布一款支持运行在手机、平板和可穿戴设备上的嵌入式数据库，目标是取代SQLite。
Realm 本质上是一个嵌入式数据库，他并不是基于 SQLite 所构建的。它拥有自己的数据库存储引擎，可以高效且快速地完成数据库的构建操作。和 SQLite 不同，它允许你在持久层直接和数据对象工作。在它之上是一个函数式风格的查询api，众多的努力让它比传统的SQLite 操作更快 。详细介绍（如果进不去，可看第二个链接）：
优势
如果在在使用它时候，连它的优势在哪都不知道的话就有点说不过去了。
易用：Ream 不是在SQLite基础上的ORM，它有自己的数据查询引擎。并且十分容易使用。
快速：由于它是完全重新开始开发的数据库实现，所以它比任何的ORM速度都快很多，甚至比SLite速度都要快。
跨平台：Realm 支持 iOS & OS X (Objective‑C & Swift) & Android。我们可以在这些平台上共享Realm数据库文件，并且上层逻辑可以不用任何改动的情况下实现移植。
高级：Ream支持加密，格式化查询，易于移植，支持JSON，流式api，数据变更通知等高级特性
可视化：Realm 还提供了一个轻量级的数据库查看工具，在Mac Appstore 可以下载“Realm Browser”这个工具，开发者可以查看数据库当中的内容，执行简单的插入和删除数据的操作。（windows上还不清楚）
条件
- 目前不支持Android以外的Java
- Android Studio >= 1.5.1
- 较新的Android SDK版本
- JDK version >=7.
- 支持API 9(Android 2.3)以及之后的版本
使用
加入依赖
在 project 的 build 中加入依赖：
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'io.realm:realm-gradle-plugins:2.2.1'
}
}
在 module 中加入:
apply plugin: 'realm-android'
Realm从v1.0.0后，不支持Ecilpse，我们推荐使用Android Studio
创建model
创建一个 User 类，需要继承 RealmObject。支持 public, protected 和 private 的类以及方法：
public class User extend RealmObject {
private String name;
private int age;
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;
}
}
除了直接继承于 RealmObject 来声明 Realm 数据模型之外，还可以通过实现 RealmModel接口 并添加 @RealmClass 修饰符来声明。
@RealmClass
public class User implements RealmModel {
...
}
支持的属性
boolean, byte, short, int, long, float, double, String, Date 和 byte[], RealmObject, RealmList<? extends RealmObject>
还支持 Boolean, Byte, Short, Integer, Long, Float 和 Double
整数类型 short、int 和 long 都被映射到 Realm 内的相同类型（实际上为 long ）
@PrimaryKey——表示该字段是主键
使用过数据库的同学应该看出来了，PrimaryKey 就是主键。使用 @PrimaryKey 来标注，字段类型必须是字符串（String）或整数（byte，short，int或long）以及它们的包装类型（Byte,Short, Integer, 或 Long）。不可以存在多个主键，使用字符串字段作为主键意味着字段被索引（注释 @PrimaryKey 隐式地设置注释 @Index）。
@PrimaryKey
private String id;
@Required——表示该字段非空
在某些情况下，有一些属性是不能为null的。使用@Required可用于用于强行要求其属性不能为空，只能用于Boolean, Byte, Short, Integer, Long, Float, Double, String, byte[] 和 Date。在其它类型属性上使用 @Required修饰会导致编译失败。
非基本数据类型不需要使用注解 @Required，因为他们本身就不可为空
@Required
private String name;
@Ignore——表示忽略该字段
被添加 @Ignore 标签后，存储数据时会忽略该字段。
@Ignore
private String name;
@Index——添加搜索索引
为字段添加搜索索引，这样会使得插入的速度变慢，数据量也变得更大。不过在查询速度将变得更快，建议只在优化读取性能的特定情况时添加索引。支持索引：String，byte，short，int，long，boolean和Date字段。
==注意：如果你创建Model并运行过，然后修改了Model。那么就需要升级数据库，否则会抛异常。升级方式后面会提到。==
初始化
使用默认配置
Realm.init(this);
Realm mRealm = Realm.getDefaultInstance();
这时候会创建一个叫做 default.realm 的Realm文件，一般来说，这个文件位于/data/data/包名/files/。通过 realm.getPath() 来获得该Realm的绝对路径
注意：模拟器上运行时，Realm.getDefaultInstance()抛出异常，真机上没问题（不止何故）
当然，我们还可以使用==RealmConfiguration==来配置Realm
RealmConfiguration config = new RealmConfiguration.Builder()
.name("myrealm.realm") //文件名
.schemaVersion(0) //版本号
.build();
Realm realm = Realm.getInstance(config);
创建非持久化的Realm，也就是保持在内存中，应用关闭后就清除了。
RealmConfiguration myConfig = new RealmConfiguration.Builder(context)
.name("myrealm.realm")//保存在内存中
.inMemory() .build();
RealmConfiguration支持的方法：
- Builder.name : 指定数据库的名称。如不指定默认名为default。
- Builder.schemaVersion : 指定数据库的版本号。
- Builder.encryptionKey : 指定数据库的密钥。
- Builder.migration : 指定迁移操作的迁移类。
- Builder.deleteRealmIfMigrationNeeded : 声明版本冲突时自动删除原数据库。
- Builder.inMemory : 声明数据库只在内存中持久化。
- build : 完成配置构建。
关闭Realm
记得使用完后，在onDestroy中关闭Realm
@Override
protected void onDestroy() {
super.onDestroy();
// Close the Realm instance.
realm.close();
}
新增
写入操作需要在事务中进行，可以使用executeTransaction方法来开启事务。
- 使用executeTransaction方法插入数据
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("Gavin");
user.setAge(23);
}
});
在execute方法中执行插入操作
注意：如果在UI线程中插入过多的数据，可能会导致主线程拥塞。
- 使用copyToRealmOrUpdate或copyToRealm方法插入数据
当Model中存在主键的时候，推荐使用copyToRealmOrUpdate方法插入数据。如果对象存在，就更新该对象；反之，它会创建一个新的对象。若该Model没有主键，使用copyToRealm方法，否则将抛出异常。
final User user = new User();
user.setName("Jack");
user.setId("2");
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
realm.copyToRealmOrUpdate(user);
}
});
- 如果你用的是这样的model
public class User2 extends RealmObject {
public String name;
public int age;
}
就这样写
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User2 user = realm.createObject(User2.class);
user.name = "Micheal";
user.age = 30;
}
});
- 如果User还有其他属性是，比如养了只Dog：
public class User extends RealmObject {
private String name;
private int age;
private Dog dog;
//getters and setters
}
需要在User中加入该属性
private RealmList<Dog> dogs;
插入数据
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("Gain");
user.setAge(23);
Dog dog1 = realm.createObject(Dog.class);
dog1.setAge(1);
dog1.setName("二哈");
user.getDogs().add(dog1);
Dog dog2 = realm.createObject(Dog.class);
dog2.setAge(2);
dog2.setName("阿拉撕家");
user.getDogs().add(dog2);
}
});
- 上面都是用可executeTransaction方法插入数据，还有另一种方法可以用于插入数据——beginTransaction和commitTransaction
mRealm.beginTransaction();//开启事务
User user = mRealm.createObject(User.class);
user.setName("Gavin");
user.setId("3");
mRealm.commitTransaction();//提交事务
在插入前，先调用beginTransaction()，完成后调用commitTransaction()即可。
注意：在UI和后台线程同时开启创建write的事务，可能会导致ANR错误。为了避免该问题，可以使用executeTransactionAsync来实现。
- 使用executeTransactionAsync
该方法会开启一个子线程来执行事务，并且在执行完成后进行结果通知。
RealmAsyncTask transaction = mRealm.executeTransactionAsync(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("Eric");
user.setId("4");
}
});
还可以加入监听
RealmAsyncTask transaction = mRealm.executeTransactionAsync(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("Eric");
user.setId("4");
}
}, new Realm.Transaction.OnSuccess() {
@Override
public void onSuccess() {
//成功回调
}
}, new Realm.Transaction.OnError() {
@Override
public void onError(Throwable error) {
//失败回调
}
});
注意：如果当Acitivity或Fragment被销毁时，在OnSuccess或OnError中执行UI操作，将导致程序奔溃 。用RealmAsyncTask .cancel();可以取消事务**
在onStop中调用，避免crash
public void onStop () {
if (transaction != null && !transaction.isCancelled()) {
transaction.cancel();
}
}
- JSON
Realm还是个很nice的功能就是将Json字符串转化为对象，厉害了我的Realm
（直接借用官方的例子）
// 一个city model
public class City extends RealmObject {
private String city;
private int id;
// getters and setters left out ...
}
// 使用Json字符串插入数据
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();
}
}
});
Realm 解析 JSON 时遵循如下规则：
- 使用包含空值（null）的 JSON 创建对象;
- 对于非必须（可为空值的属性），设置其值为 null;
- 对于必须（不可为空值的属性），抛出异常;
- 使用包含空值（null）的 JSON 更新对;
- 对于非必须（可为空值的属性），设置其值为 nul;
- 对于必须（不可为空值的属性），抛出异常;
- 使用不包含对应属性的 JSON： * 该属性保持不变
查询
查找操作就比插入方便多了，并不需在事务中操作，直接查询即可。
- findAll ——查询
例：查询所有的User
RealmResults<User> userList = mRealm.where(User.class).findAll();
这里使用RealmResults来接受查询到的结果，突然出现的RealmResults可能会让人懵逼。看看他的源码，发现RealmResults继承了AbstractList，而AbstractList又实现了List接口。好吧，原来实现了我们熟悉的List接口。
public final class RealmResults<E extends RealmModel> extends AbstractList<E>
public abstract class AbstractList<E> extends AbstractCollection<E> implements List<E>
注意：RealmResults虽然实现了List接口，不过有很多方法是不能用的。比如add、addAll、remove、clear等，调用后会直接抛异常。不过也不用当心误用这些方法，因为它们都被标记为@Deprecated了。
findAllAsync——异步查询
当数据量较大，可能会引起ANR的时候，就可以使用findAllAsync
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.findAllAsync();
值得注意的是，这里并不会马上查到数据，是有一定延时的。也就是说，你马上使用userList的时候，里面是没有数据的。可以注册RealmChangeListener监听器，或者使用isLoaded()方法，判断是否查询完成
if (result.isLoaded()) {
// 完成查询
}
findFirst ——查询第一条数据
例：查询User表中的第一条数据
User user2 = mRealm.where(User.class).findFirst();
equalTo ——根据条件查询
例：得到name为Gavin的用户列表。
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin").findAll();
如果User中还有Dog属性，希望根据Dog的条件来获取用户：
例：查询dogs.name为二哈的User
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("dogs.name", "二哈").findAll();
得到有养有dogs.name为"二哈"的用户列表（这里的dogs是User表中的属性名）
equalTo ——多条件查询
当然，我们还经常要用到多条件的查询的功能。
例：找到用户名为“Gavin”，且dogs.name为“二哈”的User
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin").findAll();
RealmResults<User> userList = user5.where()
.equalTo("dogs.name", "二哈").findAll();
上面先找到name为“Gavin”的User列表，然后再得到的结果中查询dogs.name为“二哈”
觉得这样写太麻烦？我也是这样想的，所以还可以这样写
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.equalTo("dogs.name", "二哈")
.findAll();
是不是很清爽~~~
更多查询条件
上面就展示了equalTo的用法。当然，查询还有更多的用法，我就不一一示例了。已知的方法如下：
sum()：对指定字段求和。
average()：对指定字段求平均值。
min(): 对指定字段求最小值。
max() : 对指定字段求最大值。count : 求结果集的记录数量。
findAll(): 返回结果集所有字段，返回值为RealmResults队列
findAllSorted() : 排序返回结果集所有字段，返回值为RealmResults队列
between(), greaterThan(),lessThan(), greaterThanOrEqualTo() & lessThanOrEqualTo()
equalTo() & notEqualTo()
contains(), beginsWith() & endsWith()
isNull() & isNotNull()
isEmpty()& isNotEmpty()
RealmQuery以及or的使用
在使用where()方法时，能得到一个RealmQuery对象，使用方法如下：
例：查询name为“Gavin”和“Eric”的用户
RealmQuery<User> query = mRealm.where(User.class);
query.equalTo("name", "Gavin");
query.or().equalTo("name", "Eric");
RealmResults<User> userList = query.findAll();
这种情况下就要用到or()方法
这么一大串，你又觉得麻烦了？没事，继续简化。
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.or().equalTo("name", "Eric")
.findAll();
Tip：查询的时候你不用当心得到的RealmResults为null。如果查询的结果为空，那么RealmResults的size为0
排序
查询结束后，还可以进行排序，就像这样：
RealmResults<User> userList = mRealm.where(User.class) .findAll();
result = result.sort("age"); //根据age，正序排列
result = result.sort("age", Sort.DESCENDING);//逆序排列
聚合
RealmResult自带一些聚合方法：
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();
改
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
//先查找后得到User对象
User user = mRealm.where(User.class).findFirst();
user.setAge(26);
}
});
修改也是需要在事务中操作。
使用查询语句得到数据，然后将内容改了即可。
删除
使用deleteFromRealm()
//先查找到数据
final RealmResults<User> userList = mRealm.where(User.class).findAll();
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
userList.get(0).deleteFromRealm();
}
});
使用deleteFromRealm(int index)
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
userList.deleteFromRealm(0);
}
});
更多方法：
userList.deleteFirstFromRealm(); //删除user表的第一条数据
userList.deleteLastFromRealm();//删除user表的最后一条数据
results.deleteAllFromRealm();//删除user表的全部数据
版本升级
当数据结构发生变化是，需要升级数据库。对于Realm来说，数据库升级就是迁移操作，把原来的数据库迁移到新结构的数据库。（体验：略麻烦）
例1：User类发生变化，移除age，新增个@Required的id字段。
User版本：version 0
String name;
int age;
User版本：version 1
@Required
String id;
String name;
创建迁移类CustomMigration，需要实现RealmMigration接口。执行版本升级时的处理：
/**
* 升级数据库
*/
class CustomMigration implements RealmMigration {
@Override
public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
RealmSchema schema = realm.getSchema();
if (oldVersion == 0 && newVersion == 1) {
RealmObjectSchema personSchema = schema.get("User");
//新增@Required的id
personSchema
.addField("id", String.class, FieldAttribute.REQUIRED)
.transform(new RealmObjectSchema.Function() {
@Override
public void apply(DynamicReal
mObject obj) {
obj.set("id", "1");//为id设置值
}
})
.removeField("age");//移除age属性
oldVersion++;
}
}
}
使用Builder.migration升级数据库，将版本号改为1（原版本号：0）。当Realm发现新旧版本号不一致时，会自动使用该迁移类完成迁移操作。
RealmConfiguration config = new RealmConfiguration.Builder()
.name("myrealm.realm") //文件名
.schemaVersion(1)
.migration(new CustomMigration())//升级数据库
.build();
RxJava
对于这么火的RxJava，Realm又怎么会放过他。
Realm 包含了对 RxJava 的原生支持。如下类可以被暴露为一个 Observable：Realm, RealmResults, RealmObject, DynamicRealm 和 DynamicRealmObject。
（直接用一个官方的例子）
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));
这里使用asObservable轻松转换成RxJava中的Observable，使用.filter(persons.isLoaded)来判断是否已查询完成。到这里，熟悉RxJava的同学应该已经看明白了~~。可能还有人会一脸懵逼，->? 这是什么鬼？哈哈，这叫Lambda，有时间可以去看看。
