- title: SyncReference
- 方法
- setValue(value)
- setValue(value, listener)
- setValue(value, priority, listener)
- push()
- updateChildren(value)
- updateChildren(value, listener)
- setPriority(priority)
- setPriority(object, listener)
- removeValue()
- removeValue(listener)
- runTransaction(handler)
- onDisconnect()
- getSync()
- getKey()
- getParent()
- getRoot()
- goOffline()
- goOnline()
title: SyncReference
SyncReference
实例表示要操作的特定数据节点,可以通过 SyncReference
实例操作和读取数据。
SyncReference
是 Query 的子类。
方法
child()
定义
SyncReference child(String path)
说明
获得一个在当前节点下指定路径节点处的 SyncReference
实例。
根据相对路径 path,来获取当前节点下 path 子节点的引用。
相对路径可以是一个简单的节点路径(例如: fred
),或者是一个更深的路径(例如: fred/name/first
)。
参数
参数名 | 说明 |
---|---|
path | String path 为相对路径,深层路径多层级间需要使用 “/“ 分隔,例如:”a/b” 。如果 path 为空字符串或 null 则返回当前引用。如果定位的 path 不存在,依然可以定位,将在后续数据操作时创建不存在的路径节点引用。 |
返回值
SyncReference
子节点引用。
示例
WilddogOptions options = new WilddogOptions.Builder().setSyncUrl("https://<SyncAppID>.wilddogio.com").build();
WilddogApp.initializeApp(this, options);
//ref 表示 `https://<SyncAppID>.wilddogio.com/test` 节点
SyncReference ref = WilddogSync.getInstance().getReference("test");
// 定位到 '/test/a'
SyncReference ref2 = ref.child("a");
// 定位到 '/test/a/b'
SyncReference ref3 = ref.child("a/b");
SyncReference ref4 = ref.child("a").child("b");
setValue(value)
定义
void setValue(Object value)
说明
向指定节点写入数据。此方法会先清空指定节点,再写入数据。详细使用请参考:setValue() 完整指南。
支持的数据类型:
- String、 Number、 Boolean 等基本数据类型;
- 数组 ArrayList;
Wliddog Sync 没有对数组的原生支持,但是支持以数组下标作为 key ,数组元素作为 value 的方式进行存储。
例如:
在数据监听中获取数据时,如果满足条件:当 0 到最大的 key(比如 n ) 之间,n+1 个元素中超过一半以上有值,数据将被转换为 ArrayList 类型; 如果不满足条件,Wilddog Sync 处理数据时会将其转换为 Map 类型。String[] strList = new String[6];
strList[0] = "a";
strList[2] = "b";
strList[3] = "c";
strList[5] = "d";
//在数据库中存储为DataSnapshot { key = list, value = {0=a, 2=b, 3=c, 5=d} }
ref.child("list").setValue(strList);
- 自定义数据类型,满足 JavaBean 规范的实体;
- null,当 value 为 null 时,等价于当前节点的
removeValue()
操作,会删除当前节点。
参数
参数名 | 说明 |
---|---|
value | value 的类型可以为 null、String、Number、Boolean、List、Map 或满足 JavaBean 规范的实体。 |
示例
SyncReference ref = WilddogSync.getInstance().getReference("test");
// 等价 update(100);
ref.child("a/b").setValue(100);
// 等价 remove();
ref.child("a/b").setValue(null);
// 设置子树
Map<String, String> children = new HashMap<String, String>();
children.put("c", "cval");
ref.child("a/b").setValue(children);
// 自定义Entity
DOTAHero hero = new DOTAHero();
hero.setName("Nevermore");
hero.setHp(435);
hero.setMp(234);
ref.child("dota/heros/SF").setValue(hero);
setValue(value, listener)
定义
void setValue(Object value, SyncReference.CompletionListener listener)
说明
向指定节点写入数据并设置操作完成监听。此方法会先清空指定节点,再写入数据。详细使用请参考:setValue() 完整指南。
setValue()
操作执行完成后将触发操作完成监听 listener 的 onComplete()
方法。
支持写入的数据类型:
- String、 Number、 Boolean 等基本数据类型;
- 数组 ArrayList;
Wliddog Sync 没有对数组的原生支持,但是支持以数组下标作为 key ,数组元素作为 value 的方式进行存储。
例如:
在数据监听中获取数据时,如果满足条件:当 0 到最大的 key(比如 n ) 之间,n+1 个元素中超过一半以上有值,数据将被转换为 ArrayList 类型; 如果不满足条件,Wilddog Sync 处理数据时会将其转换为 Map 类型。String[] strList = new String[6];
strList[0] = "a";
strList[2] = "b";
strList[3] = "c";
strList[5] = "d";
//在数据库中存储为DataSnapshot { key = list, value = {0=a, 2=b, 3=c, 5=d} }
ref.child("list").setValue(strList);
- 自定义数据类型,满足 JavaBean 规范的实体;
- null,当 value 为 null 时,等价于当前节点的
removeValue()
操作,会删除当前节点。
参数
参数名 | 说明 |
---|---|
value | value 的类型可以为 null、String、Number、Boolean、List、Map 或满足 JavaBean 规范的实体。 |
listener | CompletionListener 类型。setValue() 操作完成回调。setValue(value, null) 等价于 setValue(value) 。 |
示例
自定义CompletionListener
class MyHandler implements SyncReference.CompletionListener {
void onComplete(SyncError error, SyncReference ref) {
if(error != null){
System.out.println(error.getCode());
}
}
}
SyncReference ref = WilddogSync.getInstance().getReference("test");
CompletionListener listener = new MyHandler();
// 等价 update(100);
ref.child("a/b").setValue(100, listener);
// 等价 remove();
ref.child("a/b").setValue(null, listener);
// 设置子树
Map<String, String> children = new HashMap<String, String>();
children.put("c", "cval");
ref.child("a/b").setValue(children, listener);
// 自定义Entity
DOTAHero hero = new DOTAHero();
hero.setName("Nevermore");
hero.setHp(435);
hero.setMp(234);
ref.child("dota/heros/SF").setValue(hero, new SyncReference.CompletionListener() {
void onComplete(SyncError error, SyncReference ref) {
if(error != null) {
System.out.println(error.getCode());
return;
}
System.out.println("Good!");
}
});
setValue(value, priority, listener)
定义
void setValue(Object value, Object priority, SyncReference.CompletionListener listener)
说明
向指定节点写入数据和 数据优先级,并设置操作完成监听。此方法会先清空指定节点,再写入数据。详细使用请参考:setValue() 完整指南。
setValue()
操作执行完成后将触发 listener 的 onComplete()
方法。
支持写入的数据类型:
- String、 Number、 Boolean 等基本数据类型;
- 数组 ArrayList;
Wliddog Sync 没有对数组的原生支持,但是支持以数组下标作为 key ,数组元素作为 value 的方式进行存储。
例如:
在数据监听中获取数据时,如果满足条件:当 0 到最大的 key(比如 n ) 之间,n+1 个元素中超过一半以上有值,数据将被转换为 ArrayList 类型; 如果不满足条件,Wilddog Sync 处理数据时会将其转换为 Map 类型。String[] strList = new String[6];
strList[0] = "a";
strList[2] = "b";
strList[3] = "c";
strList[5] = "d";
//在数据库中存储为DataSnapshot { key = list, value = {0=a, 2=b, 3=c, 5=d} }
ref.child("list").setValue(strList);
- 自定义数据类型,满足 JavaBean 规范的实体;
- null,当 value 为 null 时,等价于当前节点的
removeValue()
操作,会删除当前节点。
参数
参数名 | 说明 |
---|---|
value | value 的类型可以为 null、String、Number、Boolean、List、Map 或满足 JavaBean 规范的实体。 |
priority | Object 指定节点的优先级,类型可以为 Boolean、Number 或 String。 |
listener | CompletionListener 类型。setValue() 操作完成回调。setValue(value, null) 等价于 setValue(value) 。 |
示例
自定义CompletionListener
class MyHandler implements SyncReference.CompletionListener {
void onComplete(SyncError error, SyncReference ref) {
if(error != null){
System.out.println(error.getCode());
}
}
}
SyncReference ref = WilddogSync.getInstance().getReference("test");
CompletionListener listener = new MyHandler();
// 等价 update(100);
ref.child("a/b").setValue(100, listener);
// 等价 remove();
ref.child("a/b").setValue(null, listener);
// 设置子树
Map<String, String> children = new HashMap<String, String>();
children.put("c", "cval");
ref.child("a/b").setValue(children, listener);
// 自定义Entity
DOTAHero hero = new DOTAHero();
hero.setName("Nevermore");
hero.setHp(435);
hero.setMp(234);
ref.child("dota/heros/SF").setValue(hero, new SyncReference.CompletionListener() {
void onComplete(SyncError error, SyncReference ref) {
if(error != null) {
System.out.println(error.getCode());
return;
}
System.out.println("Good!");
}
});
push()
定义
SyncReference push()
说明
向当前节点添加子节点。新增子节点的 key 自动生成并保证唯一(例如:”-KdzI7I-AsBST9NlasJM”)。 key 值基于时间戳和随机算法生成,并可以按照时间先后进行排序。详细使用请参考:push() 完整指南。
返回值
SyncReference
新增子节点的引用。
示例
SyncReference ref = WilddogSync.getInstance().getReference("push");
// 添加一个数值,将生成一个新 ID,返回的 path 为“/push/-KdzI7I-AsBST9NlasJM”
SyncReference newRef = ref.push();
//操作结果为在 'push' 节点下写入 {"-KdzI7I-AsBST9NlasJM":100}
newRef.setValue(100);
// 添加一个实体
DOTAHero hero = new DOTAHero();
hero.setName("Nevermore");
hero.setHp(435);
hero.setMp(234);
ref.child("heros").push().setValue(hero);
updateChildren(value)
定义
void updateChildren(Map value)
说明
对当前节点进行数据合并操作,更新当前节点下的数据。详细使用请参考:updateChildren() 完整指南。
与 setValue()
方法覆盖当前节点下所有数据的方式不同,使用 updateChildren()
方法,不存在的子节点将会被新增,存在的子节点将会被更新。
使用此方法可以对同一节点的子节点同时进行更新和删除操作。
参数
参数名 | 说明 |
---|---|
value | Map<String, Object> 当 value 为 null 时,等价于 removeValue() 操作。 |
示例
SyncReference ref = WilddogSync.getInstance().getReference("test");
// 更新子树
Map<String, String> children = new HashMap<String, String>();
children.put("c", "cval");
ref.child("a/b").updateChildren(children);
updateChildren(value, listener)
定义
void updateChildren(Map<String, Object> value, SyncReference.CompletionListener listener)
说明
对当前节点进行数据合并操作,更新当前节点下的数据,并设置数据完成监听。详细使用请参考:updateChildren() 完整指南。
与 setValue()
方法覆盖当前节点下所有数据的方式不同,使用 updateChildren()
方法,不存在的子节点将会被新增,存在的子节点将会被更新。
使用此方法可以对同一节点的子节点同时进行更新和删除操作。
参数
参数名 | 说明 |
---|---|
value | Map<String, Object> 当 value 为 null 时,等价于 removeValue 操作。 |
listener | CompletionListener 类型。setValue() 操作完成回调。setValue(value, null) 等价于 setValue(value) 。 |
示例
自定义CompletionListener
class MyHandler implements SyncReference.CompletionListener {
void onComplete(SyncError error, SyncReference ref){
if(error != null){
System.out.println(error.getCode());
}
}
}
SyncReference ref = WilddogSync.getInstance().getReference("test");
CompletionListener handler = new MyHandler();
// 更新子树
Map<String, Object> children = new HashMap<String, Object>();
children.put("c", "cval");
ref.child("a/b").updateChildren(children, handler);
setPriority(priority)
定义
void setPriority(Object priority)
说明
设置当前节点的优先级,支持为每个节点设置优先级 (priority),用于实现节点按优先级排序。优先级是节点的隐藏属性,默认为 null。详细使用请参考:setPriority() 完整指南。
不能为不存在的节点设置优先级。因此,新增数据需要设置优先级时,请使用 setValue(data, priority)
;为已存在的数据设置优先级的时,使用 setPriority(priority)
。
节点按照如下优先级规则升序排列:null < Number < String。
- priority 为 null 的排最先;
- priority 为数值的次之,按照数值从小到大排序;
- priority 为字符串的排最后,按照字典序排列。
- 当两个子节点有相同的 priority(包括没有 priority),它们按照 key 进行排列,数字优先(按数值从小到大排序),其余以字典序排序。
注意:
数值优先级被作为 IEEE 754 双精度浮点型数字进行解析和排序,key 以 String 类型进行存储,只有当它能被解析成 32 位整型数字时被当作数字来处理。
参数
参数名 | 说明 |
---|---|
priority | Object 指定节点的优先级。 |
setPriority(object, listener)
定义
void setPriority(Object object, SyncReference.CompletionListener listener)
说明
设置当前节点的优先级并设置优先级操作完成监听。支持为每个节点设置优先级 (priority),用于实现节点按优先级排序。优先级是节点的隐藏属性,默认为 null。详细使用请参考:setPriority() 完整指南。
不能为不存在的节点设置优先级。因此,新增数据需要设置优先级时,请使用 setValue(data, priority)
;为已存在的数据设置优先级的时,使用 setPriority(priority)
。
节点按照如下优先级规则升序排列:null < Number < String。
- priority 为 null 的排最先;
- priority 为数值的次之,按照数值从小到大排序;
- priority 为字符串的排最后,按照字典序排列。
- 当两个子节点有相同的 priority(包括没有 priority),它们按照 key 进行排列,数字优先(按数值从小到大排序),其余以字典序排序。
注意:
数值优先级被作为 IEEE 754 双精度浮点型数字进行解析和排序,key 以 String 类型进行存储,只有当它能被解析成 32 位整型数字时被当作数字来处理。
参数
参数名 | 说明 |
---|---|
priority | Object 指定节点的优先级。 |
listener | CompletionListener 类型。 |
removeValue()
定义
void removeValue()
说明
删除当前节点,等价于在当前节点下调用 setValue(null)
方法。详细使用请参考:removeValue() 完整指南。
示例
SyncReference ref = WilddogSync.getInstance().getReference("test");
//将删除路径 '/test/a/b' 下的所有数据,如果 'test/a' 节点下只有 '/b' 一个节点,则会连带删除 '/b' 节点
ref.child("a/b").removeValue();
removeValue(listener)
定义
void removeValue(SyncReference.CompletionListener listener)
说明
删除当前节点,并设置数据移除完成监听。等价于在当前节点下调用 setValue(null, listener)
方法。详细使用请参考:removeValue() 完整指南。
参数
参数名 | 说明 |
---|---|
listener | CompletionListener 类型。removeValue() 操作完成回调。 |
示例
SyncReference ref = WilddogSync.getInstance().getReference("test");
ref.child("a/b").removeValue(new SyncReference.CompletionListener() {
@Override
void onComplete(SyncError syncError, SyncReference syncReference) {
if (syncError != null) {
// 移除数据失败
} else {
// 移除数据成功
}
}
});
runTransaction(handler)
定义
void runTransaction(Transaction.Handler handler)
说明
用于多客户端并发写入操作时保证数据一致性,可以避免并发修改当前节点时的数据冲突。详细使用请参考:runTransaction() 完整指南。
与 setValue()
直接覆盖以前的数据不同,在不同客户端并发修改时,runTransaction()
不会单纯覆盖节点数据。
客户端提交事务至服务器,如果数据已被其他客户端修改,那么服务器会拒绝当前操作,并将新值返回到客户端,客户端使用新值再次运行事务处理。
在 runTransaction()
的执行过程中客户端可能会重复写入直到成功,也可以在执行过程中调用 Transaction.abort()
手动中止事务。
参数
参数名 | 说明 |
---|---|
handler | Transaction.Handler 类型。 |
示例
SyncReference ref = WilddogSync.getInstance().getReference("/android/saving-data/wildblog/posts/-JRHTHaIs-jNPLXOQivY/upvotes");
upvotesRef.runTransaction(new Transaction.Handler() {
Transaction.Result doTransaction(MutableData currentData) {
if(currentData.getValue() == null) {
currentData.setValue(1);
} else {
currentData.setValue((Long) currentData.getValue() + 1);
}
return Transaction.success(currentData); // 向云端提交数据。也可以调用 Transaction.abort() 中止事务
}
void onComplete(SyncError wilddogError, boolean committed, DataSnapshot currentData) {
// 事务完成后调用一次,获取事务完成的结果
}
});
onDisconnect()
定义
OnDisconnect onDisconnect()
说明
获取一个 OnDisconnect 的实例。详细使用请参考:onDisconnect() 完整指南。 云端与客户端断开连接后,将在当前 OnDisconnect 实例上自动触发离线事件。 断开连接包括客户端主动断开连接,或者意外的网络中断。离线事件即执行特定的数据操作,支持离线写入、更新和删除数据。
返回值
OnDisconnect 实例。
示例
SyncReference ref = WilddogSync.getInstance().getReference("onDisconnect");
// 断开连接后清除 ref 引用下的所有数据
ref.onDisconnect().removeValue();;
// 断开连接后将 ref 引用下的数据设置为 "onDisconnected."
ref.onDisconnect().setValue("onDisconnected.");
getSync()
定义
WilddogSync getSync()
说明
通过当前 SyncReference
实例获取相关的 WilddogSync 实例。
返回值
WilddogSync 实例。
getKey()
定义
String getKey()
说明
获取当前节点的 key 值。
返回值
String
节点 key 值。
示例
SyncReference ref = WilddogSync.getInstance().getReference("test");
//当前节点为 '/test/a/b'
SyncReference refChild = ref.child("a").child("b");
//获取当前节点的 key 值,key = "b";
String key = refChild.getKey();
getParent()
定义
SyncReference getParent()
说明
获取当前节点的父节点引用。
注意:
如果当前节点是根节点,返回的依然是根节点的引用。
返回值
SyncReference
父节点的引用。
示例
SyncReference ref = WilddogSync.getInstance().getReference("test/a");
// 获得 '/test' 路径的引用
SyncReference ref2 = ref.getParent();
// 到达 root
SyncReference ref3 = ref.getParent().getParent();
getRoot()
定义
SyncReference getRoot()
说明
获取根节点的引用。使用此方法可以直接获取到当前子节点的根节点引用,等价于多次调用 getParent()
方法获取根节点。
返回值
SyncReference
根节点的引用。
goOffline()
定义
static void goOffline()
说明
手动断开与云端的连接。详细使用请参考:goOffline() 完整指南。
执行 goOffline()
操作后,会关闭自动重连机制,所有数据操作都在本地执行,不会影响到网络数据。
同时不会接收任何网络数据变化,直到恢复连接。
注意:
调用此方法会影响到所有 WilddogApp 的 WilddogSync 连接。
goOnline()
定义
static void goOnline()
说明
手动恢复与云端的连接,开启自动重连机制。详细使用请参考:goOnline() 完整指南。 在关闭连接期间发生的所有本地数据变化,都将在网络连接恢复后与网络数据比对,进行数据合并。
注意:
调用此方法会影响到所有 WilddogApp 的 WilddogSync 连接。