Realm 是我见过的说明文档写得比较齐全的第三方数据库框架，早期的版本中，还有对应的中文版说明文档,截止当前，realm的java版本Latest版本为:1.2.0.
官网传送门:https://realm.io
Getting Started
一、project level的build.gradle添加如下内容
buildscript {
repositories { jcenter()
}
dependencies {
classpath "io.realm:realm-gradle-plugin:1.2.0"
}
}
二、在application level#build.gradle中添加以下内容
apply plugin: 'realm-android'
你可以在以下地方看到这两个例子
Project level build.gradle
Application level build.gradle
以上，刷新你的gradle依赖，realm就简单的被集成成功了.
Models的创建
要自定义创建Models,必须继承RealmObject类
public class User extends RealmObject {
/**public或protected 也可以*/
private String name;
private int age;
// Standard getters & setters generated by your IDE…
}
属性支持
Realm 支持以下属性类型
- boolean
- byte
- short
- int
- long
- float
- double
- String
- Date
- byte[]
------------------------其中---------------------------
byte/short/int/long在Realm中是以long的形式保存的，而包装类型 - Boolean
- Byte
- Short
- Integer
- Long
- Float
- Double
亦可在Realm中使用，只不过使用封装类型,属性值可能被设置成空.
@Required注解
在某些应用场合，空值时不被允许的，这时候可以使用@Required注解告诉Realm去检查，禁止空值的出现，当然主键以及RealmList默认自带@Required注解(隐必需)
@Ignore注解
@Ignore可以告诉Realm 对特定的参数取消系列化，持有该注解的参数不会被持久化到数据库中.
自动更新持久化对象
RealmObject对象数据发生改变时无需用户去刷新,Realm会自动更新对象的值
realm.executeTransaction(new Realm.Transaction() {
@Override public void execute(Realm realm) {
Dog myDog = realm.createObject(Dog.class);
myDog.setName("Fido"); myDog.setAge(1);
}
});
Dog myDog = realm.where(Dog.class).equalTo("age",1).findFirst();
realm.executeTransaction(new Realm.Transaction() {
@Override public void execute(Realm realm) {
Dog myPuppy=realm.where(Dog.class).equalTo("age",1).findFirst();
myPuppy.setAge(2);
}
});
myDog.getAge(); // => 2
@Index注解 为表添加索引
使用@Index可以为表中的属性添加索引，使用@Index注解的后果是:
- 它会使Insert操作更耗时，并且数据文件更大
- 查询更快
所以在适当的情况下，为了优化读取性能，建议使用@Index索引，当然使用索引的属性类型最好是String/byte/short/int/long/boolean/Date中的一种。
数据库升级(数据库迁移)
当我们使用数据库时，无时不刻要应对数据库模型的变化，Realm的数据库模型用标准的java对象来定义，改变数据模型只需要改变JAVA数据对象定义。
如果不存在旧的数据库，那么代码的改变会立即反应到数据库上，但是如果已经有旧版本数据库文件存在，Realm会抛出异常提示数据库需要升级，此时请在 RealmConfiguration 设置 schema 版本和 migration 代码来正确处理并避免该异常抛出。
RealmConfiguration config = newRealmConfiguration.Builder(context)
.schemaVersion(2) // 当数据库发生改变时，Version必须增加
.migration(new MyMigration()) // 执行数据库升级、而不是抛异常
.build()
MyMigration 数据库升级操作 例子
RealmMigration migration = new RealmMigration() {
@Override
public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
// DynamicRealm exposes an editable schema
RealmSchema schema = realm.getSchema();
// Migrate to version 1: Add a new class
// Example:
// public Person extends RealmObject {
// private String name;
// private int age;
// // getters and setters left out for brevity
// }
if (oldVersion == 0) {
schema.create("Person")
.addField("name", String.class)
.addField("age", int.class);
oldVersion++;
}
// Migrate to version 2: Add a primary key + object references
// Example:
// public Person extends RealmObject {
// private String name;
// @PrimaryKey
// private int age;
// private Dog favoriteDog;
// private RealmList<Dog> dogs;
// // getters and setters left out for brevity
// }
if (oldVersion == 1) {
schema.get("Person") .addField("id",
long.class,FieldAttribute.PRIMARY_KEY)
.addRealmObjectField("favoriteDog", schema.get("Dog"))
.addRealmListField("dogs", schema.get("Dog"));
oldVersion++;
}
}
}
如果以上的例子看得不过瘾，你也可以直接参考官方提供的
数据迁移例子
当然，如果旧数据库不存在的情况下，数据库迁移(我更喜欢叫它数据库更新)就没必要了，而数据库存在的情况下，如果你不关心旧数据库的数据丢失，那么也可以这样做
RealmConfiguration config = new RealmConfiguration.Builder(context)
.deleteRealmIfMigrationNeeded() .build()
以上的配置，当发现数据库需要更新的时候，Realm会自动把原来的数据库(.realm文件)删除并重新创建,不过这种方式比较适合开发初期.
数据写入
数据库的访问及查询可以在任何时间进行操作(读取事务是隐式的，无需用户进行声明)，但是数据库的写入（比如增删改）则需要用户声明一个Write事务，并将所有操作包含在Write事务中，事务可以被提交也可以被取消，当事务提交时，只有所有的更改都成功持久化后，事务提交才会成功，当事务被取消时，所有的更改将被丢弃.使用写入事务，可以保证数据的一致性.
事务是线程安全的.
// Obtain a Realm instance
Realm realm = Realm.getDefaultInstance();
realm.beginTransaction();
//... add or update objects here ...
realm.commitTransaction();
当在你的业务逻辑过程中，需要取消更改，你可以使用:
realm.beginTransaction();
User user = realm.createObject(User.class);
// ...
realm.cancelTransaction();
需要说明的是，写入事务之间会相互阻塞，如果一个写入事务正在执行，那么其他线程的写入事务就会阻塞它所在的线程,(同时在UI线程及后台线程开启事务有可能导致ANR的问题产生)【TODO 写入事务是否最好都移动到后台线程上去执行?】官方提供建议使用 异步事务（async transactions）方法以避免阻塞 UI 线程.
创建数据库对象的方法
一、通过Realm实例化对象
realm.beginTransaction();
User user = realm.createObject(User.class); // Create a new object
user.setName("John");
user.setEmail("john@corporation.com");
realm.commitTransaction();
二、 realm.copyToRealm() 添加
User user = new User("John");
user.setEmail("john@corporation.com");
// Copy the object to Realm. Any further changes must happen on realmUser
realm.beginTransaction();
User realmUser = realm.copyToRealm(user);
realm.commitTransaction();
事务执行
除了手动调用realm.beginTransaction()、realm.commitTransaction()和
realm.cancelTransaction()方法之外，只用 [realm.executeTransaction()](https://realm.io/cn/docs/java/latest/api/io/realm/Realm.html#executeTransaction(io.realm.Realm Transaction)) 会自动处理事务的开始于提交，并在错误的时候，取消事务.
realm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
User user = realm.createObject(User.class);
user.setName("John");
user.setEmail("john@corporation.com");
}
});
异步事务（Asynchronous Transactions）
使用事务的时候，因为事务的处理是不定时的，在UI线程上，很容易造成应用ANR，在此官方文档建议我们使用异步事务，耗时的操作放到后台线程去处理，处理结果通过回调返回给UI线程
realm.executeTransactionAsync(new Realm.Transaction() {
@Override
public void execute(Realm bgRealm) {
User user = bgRealm.createObject(User.class);
user.setName("John");
user.setEmail("john@corporation.com");
}}, new Realm.Transaction.OnSuccess() {
@Override
public void onSuccess() {
// Transaction was a success.
}}, new Realm.Transaction.OnError() {
@Override
public void onError(Throwable error) {
// Transaction failed and was automatically canceled.
}
});
更新字符串及byte数组
Realm的写操作针对是的整个属性，而非属性中的某一个字符，如果你有这样的需求，请操作一下的例子:
realm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
bytes[] bytes = realmObject.binary; bytes[4] = 'a'; realm.binary =bytes;
}
});
查询
查询条件
Realm 支持以下查询条件：
between()、greaterThan()、lessThan()、greaterThanOrEqualTo()
和 lessThanOrEqualTo()
equalTo()和 notEqualTo()
contains()、beginsWith()和 endsWith()
isNull() 和 isNotNull()
isEmpty()和 isNotEmpty()
并非所有条件都适用于所有数据类型，具体请参考 RealmQuery
API。
Notifications
Listener只工作于 Looper 线程。对于非 Looper 线程请使用
Realm.watitForChange().
当后台线程向 Realm 添加数据，你的 UI 线程或者其它线程可以添加一个监听器来获取数据改变的通知。监听器在 Realm 数据改变的时候会被触发。
public class MyActivity extends Activity {
private Realm realm; private RealmChangeListener realmListener;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
realm = Realm.getDefaultInstance();
reamlListener = new RealmChangeListener<Realm>() {
@Override
public void onChange(Realm realm) {
// ... do something with the updates (UI, etc.) ...
}};
realm.addChangeListener(realmListener);
}
@Override
protected void onDestroy() {
super.onDestroy();
// Remove the listener.
realm.removeChangeListener(realmListener);
// Close the Realm instance.
realm.close();
}}
除了在 Realm实例上添加监听器以外，你还可以在 RealmObject和 RealmResults实例上添加监听器。你可以通过这样的方式来监视对象和查询结果的改变。另外，当监听回调函数被调用时，相应的数据已经被更新，你不需要去做刷新操作。
public class MyActivity extends Activity {
private Realm realm;
private RealmChangeListener puppiesListener;
private RealmChangeListener dogListener;
private RealmResults<Dog> puppies;
private Dog dog;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
realm = Realm.getDefaultInstance();
puppiesListener = new
RealmChangeListener<RealmResults<Dog>>() {
@Override
public void onChange(RealmResults<Dog> puppies) {
// ... do something with the updated puppies instance
}};
// Find all the puppies
puppies = realm.where(Dog.class).lessThanOrEqualTo("age", 2).findAll();
puppies.addChangeListener(puppiesListener);
dogListener = new RealmChangeListener<Dog>() {
@Override
public void onChange(Dog dog) {
// ... do something with the updated Dog instance
}};
dog = realm.where(Dog.class).equals("name", "Fido").findFirst();
dog.addChangeListener(dogListener);
}
@Override
protected void onDestroy() {
super.onDestroy();
// Remove the listeners
puppies.removeChangeListener(puppiesListener);
dog.removeChangeListener(dogListener);
// Close the Realm instance.
realm.close();
}}
最后，这些监听器同样会在监听对象的引用对象改变时被触发，请见示例：
Person person = realm.where(Person.class).findFirst();person.getDogs();
// => 2 - Assume there are 2 dogs in the list
person.addChangeListener(new RealmChangeListener<Person>() {
@Override
public void onChange(Person person) {
// React to the change in the Person instance.
// This will also get called when any referenced dogs are updated.
} });
Dog dog = person.getDogs().get(0);
realm.beginTransaction();
dog.setAge(5);realm.commitTransaction();
// Person change listener is called on the next iteration of the run loop because
// a referenced dog object changed.
NEXT 等待补充中....
