realm-android-library简单使用（笔记）

介绍：
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上还不清楚）
条件

官方入门介绍：https://realm.io/docs/java/latest/

先决条件
Android Studio版本1.5.1或更高版本
JDK 7.0或更高版本
最新版本的Android SDK
Android API等级9或更高（Android 2.3及更高版本）
注意：领域目前不支持Android以外的Java。我们不再支持Eclipse作为IDE; 请迁移到Android Studio

安装：
领域被安装为Gradle插件。
步骤1：将类路径依赖项添加到项目级build.gradle文件。

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

项目级别build.gradle文件位于此处：

步骤2：将realm-android插件应用到应用程序级别build.gradle文件的顶部。

apply plugin: ‘realm-android’

应用程序级别build.gradle位于此处：

一旦做出这两个更改，只需刷新您的毕业生依赖关系。如果您从版本升级，v0.88您可能还需要清理您的gradle项目（./gradlew clean）以删除任何前所未有的安装。

这两个修改的build.gradle文件的示例可以在这里找到：

项目级build.gradle
应用级build.gradle

其他构建系统
不支持Maven＆Ant构建系统。如果您希望看到对这些构建系统的支持，请对以下问题表达您的兴趣：

Maven支持
蚂蚁支持
ProGuard配置作为Realm库的一部分提供。这意味着您不需要在ProGuard配置中添加任何领域特定的规则。

创建model

创建一个User类，需要继承RealmObject。支持public, protected和 private
public class User extends 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 和 DoubleTip：整数类型 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修饰会导致编译失败。
Tip：基本数据类型不需要使用注解 @Required，因为他们本身就不可为空。
@Required
private String name;

@Ignore——表示忽略该字段

被添加@Ignore标签后，存储数据时会忽略该字段。
@Ignore
private String na@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，一下初始化可以放在自己的Application中去完成.

/** * Created by lixby on 2017/8/14. */public class RealmApplication extends Application {    @Override    public void onCreate() {        super.onCreate();        inItRealm();    }    private void inItRealm(){        Realm.init(this);        RealmConfiguration configuration=new RealmConfiguration.Builder()                 /*指定数据库的名称，如果不指定就用默认的名称,可以自定义名称,例如:myrealm.realm*/                .name(RealmConfiguration.DEFAULT_REALM_NAME)                /*设置数据库的版本号*/                .schemaVersion(0)                /*设置版本冲突时自动删除原版本数据库*/                .deleteRealmIfMigrationNeeded()                .build();        Realm.setDefaultConfiguration(configuration);    }   }

创建非持久化的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

记得使用完后，在Activity的onDestroy()或者onStop()中关闭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);          }      });

如果你用的是这样的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还有其他属性是，比如养了只Dog：

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

对应的User属性中加入Dog类

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

如果你养了不止一只，你养了二哈、阿拉撕家…那你就要用到RealmList了。在User中加入该属性

private RealmList 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 modelpublic 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 更新对象：
对于非必须（可为空值的属性），设置其值为 null；
对于必须（不可为空值的属性），抛出异常；
使用不包含对应属性的 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源码
注意：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();userList = result.sort("age"); //根据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对象        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(DynamicRealmObject 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();

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

@Required
String id;
String name;
User版本：version 2

@Required
private String id;
private String name;
private RealmList dogs;
Dog类

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

在迁移类CustomMigration中，继续添加处理方法。

    if (oldVersion == 1 && newVersion == 2) {             //创建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) {                             //为已存在的数据设置dogs数据                             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”);
更多用法——DynamicRealmObject
例：获取id
String id = obj.getString(“id”);
例：为字段设置值
obj.setString(“name”, “Gavin”);
obj.setInt(“id”, 1);
obj.setLong(“id”, 1);

加密

（官方原文）
Realm 文件可以通过传递一个512位（64字节）的密钥参数给 Realm.getInstance().encryptionKey() 来加密存储在磁盘上。

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

保证了所有永久性存储在磁盘上的数据都是通过标准 AES-256 加密的。每次创建新的 Realm 实例的时候，都需要提供相同的密钥。
参考 examples/encryptionExample。这个例子演示了如何通过 Android KeyStore 来安全地存储密钥。

适配器（Adapter）

（官方原文）
Realm提供了一些抽象的工具类来方便地将 OrderedRealmCollection
（RealmResults和 RealmList 都实现了这个借口）展示到UI控件上。

RealmBaseAdapter 可以与ListView配合使用。参见示例.
RealmRecyclerViewAdapter可以与 RecyclerView配合使用。参见示例.
你需要在 app 的 build.gradle中添加额外的依赖以使用这些适配器。

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

Intents

（官方原文）
你不可以直接通过 intent传递 RealmObject，建议你只传递RealmObject的标识符。举个常用例子，假如你的对象拥有一个主键，请通过intent 的 bundle 来传递这个主键的值。

// Assuming we had a person class with a @PrimaryKey on the 'id' field ...Intent intent = new Intent(getActivity(), ReceivingService.class);intent.putExtra("person_id", person.getId());getActivity().startService(intent);

在接受方（Activity、Service、IntentService、BroadcastReceiver及其它）从 bundle中解析出这个主键然后打开Realm 查询得到这个 RealmObject。

// in onCreate(), onHandleIntent(), etc.String personId = intent.getStringExtra("person_id");Realm realm = Realm.getDefaultInstance();Person person = realm.where(Person.class).equalTo("id", personId).findFirst();// do something with the person ...realm.close();

可以参考 threading example 中的 Object Passing部分。该示例展示了在安卓开发中常用的如何传递 id 并且得到对应的 RealmObject。

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的同学应该已经看明白了。

Over！

官方Demo源码地址
GitHub
官方源码地址
GitHub