作者:郭霖
原文作者:帶心情去旅行
原文地址:http://www.reibang.com/u/769d3d3a9d4b
介紹
Realm 是一個(gè) MVCC (多版本并發(fā)控制)數(shù)據(jù)庫(kù)晾嘶,由 Y Combinator 公司在2014年7月發(fā)布一款支持運(yùn)行在手機(jī)一喘、平板和可穿戴設(shè)備上的嵌入式數(shù)據(jù)庫(kù),目標(biāo)是取代SQLite朴爬。
Realm 本質(zhì)上是一個(gè)嵌入式數(shù)據(jù)庫(kù)扣癣,他并不是基于 SQLite 所構(gòu)建的惰帽。它擁有自己的數(shù)據(jù)庫(kù)存儲(chǔ)引擎,可以高效且快速地完成數(shù)據(jù)庫(kù)的構(gòu)建操作父虑。和 SQLite 不同该酗,它允許你在持久層直接和數(shù)據(jù)對(duì)象工作。在它之上是一個(gè)函數(shù)式風(fēng)格的查詢api,眾多的努力讓它比傳統(tǒng)的SQLite 操作更快 呜魄。詳細(xì)介紹(如果進(jìn)不去悔叽,可看第二個(gè)鏈接):
優(yōu)勢(shì)
如果在在使用它時(shí)候,連它的優(yōu)勢(shì)在哪都不知道的話就有點(diǎn)說(shuō)不過(guò)去了爵嗅。
易用:Ream 不是在SQLite基礎(chǔ)上的ORM娇澎,它有自己的數(shù)據(jù)查詢引擎。并且十分容易使用操骡。
快速:由于它是完全重新開始開發(fā)的數(shù)據(jù)庫(kù)實(shí)現(xiàn)九火,所以它比任何的ORM速度都快很多赚窃,甚至比SLite速度都要快册招。
跨平臺(tái):Realm 支持 iOS & OS X (Objective?C & Swift) & Android。我們可以在這些平臺(tái)上共享Realm數(shù)據(jù)庫(kù)文件勒极,并且上層邏輯可以不用任何改動(dòng)的情況下實(shí)現(xiàn)移植是掰。
高級(jí):Ream支持加密,格式化查詢辱匿,易于移植键痛,支持JSON,流式api匾七,數(shù)據(jù)變更通知等高級(jí)特性
可視化:Realm 還提供了一個(gè)輕量級(jí)的數(shù)據(jù)庫(kù)查看工具絮短,在Mac Appstore 可以下載“Realm Browser”這個(gè)工具,開發(fā)者可以查看數(shù)據(jù)庫(kù)當(dāng)中的內(nèi)容翠订,執(zhí)行簡(jiǎn)單的插入和刪除數(shù)據(jù)的操作抒痒。(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
創(chuàng)建model
創(chuàng)建一個(gè) 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 來(lái)聲明 Realm 數(shù)據(jù)模型之外拢驾,還可以通過(guò)實(shí)現(xiàn) RealmModel接口 并添加 @RealmClass 修飾符來(lái)聲明奖磁。
@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
整數(shù)類型 short、int 和 long 都被映射到 Realm 內(nèi)的相同類型(實(shí)際上為 long )
@PrimaryKey——表示該字段是主鍵
使用過(guò)數(shù)據(jù)庫(kù)的同學(xué)應(yīng)該看出來(lái)了繁疤,PrimaryKey 就是主鍵咖为。使用 @PrimaryKey 來(lái)標(biāo)注,字段類型必須是字符串(String)或整數(shù)(byte稠腊,short躁染,int或long)以及它們的包裝類型(Byte,Short, Integer, 或 Long)。不可以存在多個(gè)主鍵麻养,使用字符串字段作為主鍵意味著字段被索引(注釋 @PrimaryKey 隱式地設(shè)置注釋 @Index)褐啡。
@PrimaryKey
private String id;
@Required——表示該字段非空
在某些情況下,有一些屬性是不能為null的鳖昌。使用@Required可用于用于強(qiáng)行要求其屬性不能為空备畦,只能用于Boolean, Byte, Short, Integer, Long, Float, Double, String, byte[] 和 Date低飒。在其它類型屬性上使用 @Required修飾會(huì)導(dǎo)致編譯失敗。
非基本數(shù)據(jù)類型不需要使用注解 @Required懂盐,因?yàn)樗麄儽旧砭筒豢蔀榭?/strong>
@Required
private String name;
@Ignore——表示忽略該字段
被添加 @Ignore 標(biāo)簽后褥赊,存儲(chǔ)數(shù)據(jù)時(shí)會(huì)忽略該字段。
@Ignore
private String name;
@Index——添加搜索索引
為字段添加搜索索引莉恼,這樣會(huì)使得插入的速度變慢拌喉,數(shù)據(jù)量也變得更大。不過(guò)在查詢速度將變得更快俐银,建議只在優(yōu)化讀取性能的特定情況時(shí)添加索引尿背。支持索引:String,byte捶惜,short田藐,int,long吱七,boolean和Date字段汽久。
==注意:如果你創(chuàng)建Model并運(yùn)行過(guò),然后修改了Model踊餐。那么就需要升級(jí)數(shù)據(jù)庫(kù)景醇,否則會(huì)拋異常。升級(jí)方式后面會(huì)提到吝岭。==
初始化
使用默認(rèn)配置
Realm.init(this);
Realm mRealm = Realm.getDefaultInstance();
這時(shí)候會(huì)創(chuàng)建一個(gè)叫做 default.realm 的Realm文件三痰,一般來(lái)說(shuō),這個(gè)文件位于/data/data/包名/files/苍碟。通過(guò) realm.getPath() 來(lái)獲得該Realm的絕對(duì)路徑
注意:模擬器上運(yùn)行時(shí)酒觅,Realm.getDefaultInstance()拋出異常,真機(jī)上沒(méi)問(wèn)題(不止何故)
當(dāng)然微峰,我們還可以使用==RealmConfiguration==來(lái)配置Realm
RealmConfiguration config = new RealmConfiguration.Builder()
.name("myrealm.realm") //文件名
.schemaVersion(0) //版本號(hào)
.build();
Realm realm = Realm.getInstance(config);
創(chuàng)建非持久化的Realm舷丹,也就是保持在內(nèi)存中,應(yīng)用關(guān)閉后就清除了蜓肆。
RealmConfiguration myConfig = new RealmConfiguration.Builder(context)
.name("myrealm.realm")//保存在內(nèi)存中
.inMemory() .build();
RealmConfiguration支持的方法:
- Builder.name : 指定數(shù)據(jù)庫(kù)的名稱颜凯。如不指定默認(rèn)名為default。
- Builder.schemaVersion : 指定數(shù)據(jù)庫(kù)的版本號(hào)仗扬。
- Builder.encryptionKey : 指定數(shù)據(jù)庫(kù)的密鑰症概。
- Builder.migration : 指定遷移操作的遷移類。
- Builder.deleteRealmIfMigrationNeeded : 聲明版本沖突時(shí)自動(dòng)刪除原數(shù)據(jù)庫(kù)早芭。
- Builder.inMemory : 聲明數(shù)據(jù)庫(kù)只在內(nèi)存中持久化彼城。
- build : 完成配置構(gòu)建。
關(guān)閉Realm
記得使用完后,在onDestroy中關(guān)閉Realm
@Override
protected void onDestroy() {
super.onDestroy();
// Close the Realm instance.
realm.close();
}
新增
寫入操作需要在事務(wù)中進(jìn)行募壕,可以使用executeTransaction方法來(lái)開啟事務(wù)调炬。
- 使用executeTransaction方法插入數(shù)據(jù)
mRealm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("Gavin");
user.setAge(23);
}
});
在execute方法中執(zhí)行插入操作
注意:如果在UI線程中插入過(guò)多的數(shù)據(jù),可能會(huì)導(dǎo)致主線程擁塞舱馅。
- 使用copyToRealmOrUpdate或copyToRealm方法插入數(shù)據(jù)
當(dāng)Model中存在主鍵的時(shí)候缰泡,推薦使用copyToRealmOrUpdate方法插入數(shù)據(jù)。如果對(duì)象存在代嗤,就更新該對(duì)象棘钞;反之,它會(huì)創(chuàng)建一個(gè)新的對(duì)象干毅。若該Model沒(méi)有主鍵宜猜,使用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還有其他屬性是宝恶,比如養(yǎng)了只Dog:
public class User extends RealmObject {
private String name;
private int age;
private Dog dog;
//getters and setters
}
需要在User中加入該屬性
private RealmList<Dog> dogs;
插入數(shù)據(jù)
@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方法插入數(shù)據(jù)符隙,還有另一種方法可以用于插入數(shù)據(jù)——beginTransaction和commitTransaction
mRealm.beginTransaction();//開啟事務(wù)
User user = mRealm.createObject(User.class);
user.setName("Gavin");
user.setId("3");
mRealm.commitTransaction();//提交事務(wù)
在插入前趴捅,先調(diào)用beginTransaction(),完成后調(diào)用commitTransaction()即可霹疫。
注意:在UI和后臺(tái)線程同時(shí)開啟創(chuàng)建write的事務(wù)拱绑,可能會(huì)導(dǎo)致ANR錯(cuò)誤。為了避免該問(wèn)題丽蝎,可以使用executeTransactionAsync來(lái)實(shí)現(xiàn)猎拨。
- 使用executeTransactionAsync
該方法會(huì)開啟一個(gè)子線程來(lái)執(zhí)行事務(wù),并且在執(zhí)行完成后進(jìn)行結(jié)果通知屠阻。
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");
}
});
還可以加入監(jiān)聽
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() {
//成功回調(diào)
}
}, new Realm.Transaction.OnError() {
@Override
public void onError(Throwable error) {
//失敗回調(diào)
}
});
注意:如果當(dāng)Acitivity或Fragment被銷毀時(shí)红省,在OnSuccess或OnError中執(zhí)行UI操作,將導(dǎo)致程序奔潰 国觉。用RealmAsyncTask .cancel();可以取消事務(wù)**
在onStop中調(diào)用吧恃,避免crash
public void onStop () {
if (transaction != null && !transaction.isCancelled()) {
transaction.cancel();
}
}
- JSON
Realm還是個(gè)很nice的功能就是將Json字符串轉(zhuǎn)化為對(duì)象,厲害了我的Realm
(直接借用官方的例子)
// 一個(gè)city model
public class City extends RealmObject {
private String city;
private int id;
// getters and setters left out ...
}
// 使用Json字符串插入數(shù)據(jù)
realm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
realm.createObjectFromJson(City.class, "{ city: \"Copenhagen\", id: 1 }");
}
});
// 使用InputStream插入數(shù)據(jù)
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 時(shí)遵循如下規(guī)則:
- 使用包含空值(null)的 JSON 創(chuàng)建對(duì)象;
- 對(duì)于非必須(可為空值的屬性)麻诀,設(shè)置其值為 null;
- 對(duì)于必須(不可為空值的屬性)痕寓,拋出異常;
- 使用包含空值(null)的 JSON 更新對(duì);
- 對(duì)于非必須(可為空值的屬性),設(shè)置其值為 nul;
- 對(duì)于必須(不可為空值的屬性)蝇闭,拋出異常;
- 使用不包含對(duì)應(yīng)屬性的 JSON: * 該屬性保持不變
查詢
查找操作就比插入方便多了呻率,并不需在事務(wù)中操作,直接查詢即可呻引。
- findAll ——查詢
例:查詢所有的User
RealmResults<User> userList = mRealm.where(User.class).findAll();
這里使用RealmResults來(lái)接受查詢到的結(jié)果礼仗,突然出現(xiàn)的RealmResults可能會(huì)讓人懵逼。看看他的源碼元践,發(fā)現(xiàn)RealmResults繼承了AbstractList挪丢,而AbstractList又實(shí)現(xiàn)了List接口。好吧卢厂,原來(lái)實(shí)現(xiàn)了我們熟悉的List接口乾蓬。
public final class RealmResults<E extends RealmModel> extends AbstractList<E>
public abstract class AbstractList<E> extends AbstractCollection<E> implements List<E>
注意:RealmResults雖然實(shí)現(xiàn)了List接口,不過(guò)有很多方法是不能用的慎恒。比如add任内、addAll、remove融柬、clear等死嗦,調(diào)用后會(huì)直接拋異常。不過(guò)也不用當(dāng)心誤用這些方法粒氧,因?yàn)樗鼈兌急粯?biāo)記為@Deprecated了越除。
findAllAsync——異步查詢
當(dāng)數(shù)據(jù)量較大,可能會(huì)引起ANR的時(shí)候外盯,就可以使用findAllAsync
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.findAllAsync();
值得注意的是摘盆,這里并不會(huì)馬上查到數(shù)據(jù),是有一定延時(shí)的饱苟。也就是說(shuō)孩擂,你馬上使用userList的時(shí)候,里面是沒(méi)有數(shù)據(jù)的箱熬±嗫眩可以注冊(cè)RealmChangeListener監(jiān)聽器,或者使用isLoaded()方法城须,判斷是否查詢完成
if (result.isLoaded()) {
// 完成查詢
}
findFirst ——查詢第一條數(shù)據(jù)
例:查詢User表中的第一條數(shù)據(jù)
User user2 = mRealm.where(User.class).findFirst();
equalTo ——根據(jù)條件查詢
例:得到name為Gavin的用戶列表蚤认。
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin").findAll();
如果User中還有Dog屬性,希望根據(jù)Dog的條件來(lái)獲取用戶:
例:查詢dogs.name為二哈的User
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("dogs.name", "二哈").findAll();
得到有養(yǎng)有dogs.name為"二哈"的用戶列表(這里的dogs是User表中的屬性名)
equalTo ——多條件查詢
當(dāng)然糕伐,我們還經(jīng)常要用到多條件的查詢的功能砰琢。
例:找到用戶名為“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列表赤炒,然后再得到的結(jié)果中查詢dogs.name為“二哈”
覺(jué)得這樣寫太麻煩氯析?我也是這樣想的,所以還可以這樣寫
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.equalTo("dogs.name", "二哈")
.findAll();
是不是很清爽~~~
更多查詢條件
上面就展示了equalTo的用法莺褒。當(dāng)然掩缓,查詢還有更多的用法,我就不一一示例了遵岩。已知的方法如下:
sum():對(duì)指定字段求和你辣。
average():對(duì)指定字段求平均值巡通。
min(): 對(duì)指定字段求最小值。
max() : 對(duì)指定字段求最大值舍哄。count : 求結(jié)果集的記錄數(shù)量宴凉。
findAll(): 返回結(jié)果集所有字段,返回值為RealmResults隊(duì)列
findAllSorted() : 排序返回結(jié)果集所有字段表悬,返回值為RealmResults隊(duì)列
between(), greaterThan(),lessThan(), greaterThanOrEqualTo() & lessThanOrEqualTo()
equalTo() & notEqualTo()
contains(), beginsWith() & endsWith()
isNull() & isNotNull()
isEmpty()& isNotEmpty()
RealmQuery以及or的使用
在使用where()方法時(shí)弥锄,能得到一個(gè)RealmQuery對(duì)象,使用方法如下:
例:查詢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()方法
這么一大串蟆沫,你又覺(jué)得麻煩了籽暇?沒(méi)事,繼續(xù)簡(jiǎn)化饭庞。
RealmResults<User> userList = mRealm.where(User.class)
.equalTo("name", "Gavin")
.or().equalTo("name", "Eric")
.findAll();
Tip:查詢的時(shí)候你不用當(dāng)心得到的RealmResults為null戒悠。如果查詢的結(jié)果為空,那么RealmResults的size為0
排序
查詢結(jié)束后舟山,還可以進(jìn)行排序绸狐,就像這樣:
RealmResults<User> userList = mRealm.where(User.class) .findAll();
result = result.sort("age"); //根據(jù)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對(duì)象
User user = mRealm.where(User.class).findFirst();
user.setAge(26);
}
});
修改也是需要在事務(wù)中操作累盗。
使用查詢語(yǔ)句得到數(shù)據(jù)寒矿,然后將內(nèi)容改了即可。
刪除
使用deleteFromRealm()
//先查找到數(shù)據(jù)
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表的第一條數(shù)據(jù)
userList.deleteLastFromRealm();//刪除user表的最后一條數(shù)據(jù)
results.deleteAllFromRealm();//刪除user表的全部數(shù)據(jù)
版本升級(jí)
當(dāng)數(shù)據(jù)結(jié)構(gòu)發(fā)生變化是幅骄,需要升級(jí)數(shù)據(jù)庫(kù)劫窒。對(duì)于Realm來(lái)說(shuō),數(shù)據(jù)庫(kù)升級(jí)就是遷移操作拆座,把原來(lái)的數(shù)據(jù)庫(kù)遷移到新結(jié)構(gòu)的數(shù)據(jù)庫(kù)。(體驗(yàn):略麻煩)
例1:User類發(fā)生變化冠息,移除age挪凑,新增個(gè)@Required的id字段。
User版本:version 0
String name;
int age;
User版本:version 1
@Required
String id;
String name;
創(chuàng)建遷移類CustomMigration逛艰,需要實(shí)現(xiàn)RealmMigration接口躏碳。執(zhí)行版本升級(jí)時(shí)的處理:
/**
* 升級(jí)數(shù)據(jù)庫(kù)
*/
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設(shè)置值
}
})
.removeField("age");//移除age屬性
oldVersion++;
}
}
}
使用Builder.migration升級(jí)數(shù)據(jù)庫(kù),將版本號(hào)改為1(原版本號(hào):0)散怖。當(dāng)Realm發(fā)現(xiàn)新舊版本號(hào)不一致時(shí)菇绵,會(huì)自動(dòng)使用該遷移類完成遷移操作。
RealmConfiguration config = new RealmConfiguration.Builder()
.name("myrealm.realm") //文件名
.schemaVersion(1)
.migration(new CustomMigration())//升級(jí)數(shù)據(jù)庫(kù)
.build();
RxJava
對(duì)于這么火的RxJava镇眷,Realm又怎么會(huì)放過(guò)他咬最。
Realm 包含了對(duì) RxJava 的原生支持。如下類可以被暴露為一個(gè) Observable:Realm, RealmResults, RealmObject, DynamicRealm 和 DynamicRealmObject欠动。
(直接用一個(gè)官方的例子)
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輕松轉(zhuǎn)換成RxJava中的Observable永乌,使用.filter(persons.isLoaded)來(lái)判斷是否已查詢完成惑申。到這里,熟悉RxJava的同學(xué)應(yīng)該已經(jīng)看明白了~~翅雏∪ν眨可能還有人會(huì)一臉懵逼,->? 這是什么鬼望几?哈哈绩脆,這叫Lambda,有時(shí)間可以去看看橄抹。