介紹

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 操作更快 。

優(yōu)勢(shì)

• 易用
  Ream 不是在SQLite基礎(chǔ)上的ORM，它有自己的數(shù)據(jù)查詢引擎。并且十分容易使用。
• 快速
  由于它是完全重新開(kāi)始開(kāi)發(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è)工具，開(kāi)發(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-plugin: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 Favorites extends RealmObject {
    private String pic;
    private String name;
    private String price;
    private String title;

    public String getPic() {
        return pic;
    }

    public void setPic(String pic) {
        this.pic = pic;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPrice() {
        return price;
    }

    public void setPrice(String price) {
        this.price = price;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}

除了直接繼承于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
  Tip：整數(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)致編譯失敗。
  Tip：基本數(shù)據(jù)類型不需要使用注解 @Required，因?yàn)樗麄儽旧砭筒豢蔀榭铡?/li>

@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)配置
```java
        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(); 
}

在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);
            }
        });

• 如果你用的是這樣的modle

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 Dog extends RealmObject {
      private String name;
      private int age;
      //getters and setters
}

對(duì)應(yīng)的User屬性中加入Dog類

public class User extends RealmObject {
      private String name;
      private int age;
      private Dog dog;
      //getters and setters
}

如果你養(yǎng)了不止一只，你養(yǎng)了二哈、阿拉撕家...那你就要用到RealmList了。在User中加入該屬性

private RealmList<Dog> dogs;

插入數(shù)據(jù)

    Realms.getRealm(CarActivity.this).executeTransaction(new Realm.Transaction() {
                    @Override
                    public void execute(Realm realm) {
                        Favorites favorites = realm.createObject(Favorites.class);
                        favorites.setName(info.getName());
                        favorites.setPic(info.getList_pic_url());
                        favorites.setPrice(info.getRetail_price());
                        favorites.setTitle(info.getGoods_brief());

                        Log.e("TAG", "execute: "+info.getName()+info.getList_pic_url() );
                    }
                });

• 上面都是用可executeTransaction方法插入數(shù)據(jù)，還有另一種方法可以用于插入數(shù)據(jù)——beginTransaction和commitTransaction

mRealm.beginTransaction();//開(kāi)啟事務(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í)開(kāi)啟創(chuàng)建write的事務(wù)，可能會(huì)導(dǎo)致ANR錯(cuò)誤。為了避免該問(wèn)題，可以使用executeTransactionAsync來(lái)實(shí)現(xiàn)。

• 使用executeTransactionAsync
  該方法會(huì)開(kāi)啟一個(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)聽(tīng)

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ì)象

// 一個(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è)置其值為 null；
• 對(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>

@Override
@Deprecated
public boolen add(E element){
           throw new UnsupportedoperationException(NOT_SUPPORTED_MESSAGE);
}

注意：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)聽(tīng)器，或者使用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();
userList = result.sort("age"); //根據(jù)age，正序排列
userList = 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;

創(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();

例2：加入Dog類，User中加入Dog集合。
User版本：version 1

@Required
String    id;
String name;

User版本：version 2

@Required
private String id;
private String name;
private RealmList<Dog> dogs;

Dog類

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

在遷移類CustomMigration中，繼續(xù)添加處理方法。

  if (oldVersion == 1 && newVersion == 2) {
                //創(chuàng)建Dog表
                RealmObjectSchema dogSchema = schema.create("Dog");
                dogSchema.addField("name", String.class);
                dogSchema.addField("age", int.class);

                //User中添加dogs屬性
                schema.get("User")
                        .addRealmListField("dogs", dogSchema)
                        .transform(new RealmObjectSchema.Function() {
                            @Override
                            public void apply(DynamicRealmObject obj) {
                                //為已存在的數(shù)據(jù)設(shè)置dogs數(shù)據(jù)
                                DynamicRealmObject dog = realm.createObject("Dog");
                                dog.set("name", "二哈");
                                dog.set("age", 2);
                                obj.getList("dogs").add(dog);
                            }
                        });
                oldVersion++;
            }

更多用法——RealmObjectSchema
例：取消id必填：

personSchema.setNullable("id", true):

例：移除id字段

personSchema.removeField("id");

例：重命名

personSchema..renameField("id", "userId");

personSchema..renameField("id", "userId");
更多用法——DynamicRealmObject
例：獲取id

String id = obj.getString("id");

例：為字段設(shè)置值

obj.setString("name", "Gavin");
obj.setInt("id", 1);
obj.setLong("id", 1);