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 的方式进行存储。例如：

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

在数据监听中获取数据时，如果满足条件：当 0 到最大的 key（比如 n ）之间，n+1 个元素中超过一半以上有值，数据将被转换为 ArrayList 类型; 如果不满足条件，Wilddog Sync 处理数据时会将其转换为 Map 类型。

自定义数据类型，满足 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 的方式进行存储。例如：

        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 的方式进行存储。例如：

        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。

注意：
数值优先级被作为 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](/sync/android/api/wilddogapp/) 的 [WilddogSync](/sync/android/api/wilddogsync/) 连接。

goOnline()

定义

static void goOnline()

说明

手动恢复与云端的连接，开启自动重连机制。详细使用请参考：goOnline() 完整指南。在关闭连接期间发生的所有本地数据变化，都将在网络连接恢复后与网络数据比对，进行数据合并。

注意：
调用此方法会影响到所有 [WilddogApp](/sync/android/api/wilddogapp/) 的 [WilddogSync](/sync/android/api/wilddogsync/) 连接。