Tutorial: Subscribing to changes

In JavaScript, subscribing relies on the subscribe(...) method. The first parameter expects the subscribed event type, while the second one expects a notification callback. An optional third parameter makes it possible to specify a query constraint (see Querying data subsets).

The notified events passed to the callback are instances of the DataSnapshot class: among the methods common to all subscribed types of events, the acked property indicates whether the data update represented by the event is acknowledged by the back end or local to the client cache, and the event property returns the type of the actually raised event (it is useful when the callback is subscribed to several types of event at a time).

By default, revocation events are always notified, but you can explicitly exclude them with by calling excludeRevocations() on the passed event descriptor:

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");

let eventDescriptor = Webcom.Event.Child.Addition.Removal // subscribe to both child added and child removed events
        .excludeRevocations()    // explicitly ask NOT to be notified of revocation events

node.subscribe(
    eventDescriptor, 
    Webcom.Callback(dataSnapshot => { // the callback to call when an event is raised (except revocation events)
        if (dataSnapshot.event.isChildAddition) {
            console.log(`The contact ${dataSnapshot.node.key} is added, with value ${JSON.stringify(dataSnapshot.val())}`);
            console.log("The data ", dataSnapshot.acked ? "are" : "are not yet", "acknowledged")
        } else {
            console.log(`The contact ${dataSnapshot.node.key} is removed`);
        }
    })
);

The Callback objects may be customized using:

• the onCanceled() method to specify a dedicated callback to be called either when the subscription is revoked by the Webcom back end or explicitly canceled by the client application.
• the includeAcknowledgements() method to call the callback function also when the subscribed data is acknowledged by the Webcom back end without change.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");

// build a callback
const callback = Webcom.Callback(dataSnapshot => { // the callback to call when an event is raised
    if (dataSnapshot.event.isChildAddition) {
        console.log(`The contact ${dataSnapshot.node.key} is added, with value ${JSON.stringify(dataSnapshot.val())}`);
        console.log("The data ", dataSnapshot.acked ? "are" : "are not yet", "acknowledged")
    } else {
        console.log(`The contact ${dataSnapshot.node.key} is removed`);
    }
});
callback.includeAcknowledgements();  // notify also acknowledgements
callback.onCanceled(
    (error) => {  // defines a 'revocation' callback
        if (error === null) {console.log("Subscription explicitly canceled by client app");}
        else {console.log("Subscription revoked by Webcom back end, with cause: ", error.message);} 
    }
);

// then subscribe to events
node.subscribe(Webcom.Event.Child.Addition.Removal, callback);

Examples of valid event descriptors:

Webcom.Event.ValueChange
Webcom.Event.ValueChange.WithoutData
Webcom.Event.ValueChange.excludeRevocations()
Webcom.Event.Child.Change.Addition.Removal

Unsubscribing may be done using either the unsubscribe(...) method on a data node, or the cancel() method on a given subscription:

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");

// first subscribe
let myCallback = Webcom.Callback(/*...*/); // please see code sample above
let mySubscription;
node.subscribe(Webcom.Event.ValueChange, myCallback)  
    .then((subscription) => mySubscription = subscription)  // get the returned subscription when the promise is resolved
// ... do some stuff
// then unsubscribe to one callback (other callbacks may remain for this node)
node.unsubscribe(myCallback) // from the node
// or
mySubscription.cancel()      // another way do do the same, from the received subscription

In Kotlin, a subscription is registered using the subscribe() method of DatasyncNode objects, and is managed by the DatasyncManager object that has created this DatasyncNode instance:

• The first argument of this method represents the subscribed types of event, excluding “Value Acknowledgement” and “Child Acknowledgement”, which are separately requested using the boolean property includesAcknowledgements of the options parameter. The subscribed types of event are given as their common Kotlin type inheriting the SubscribableEvent interface: Value.Changed::class for the “Value Change” event type, Child.Added::class for the “Child Addition” event type, Child.Changed::class for the “Child Change” event type, etc...
• The last argument of the subscribe() method is a callback function, which is called for each raised event, including cancelation and revocation events.

The notifications received by the callback may be either:

• A cancelation or revocation notification (passed as instances of Notification.ControlNotification subclasses). In this case, it is the last notification to be received by the callback.
• A notification of one of the subscribed events (which are all subclasses of both Notification.DataNotification and SubscribableEvent). Among the properties common to all of these subclasses, isAcknowledgement indicates whether the event is one of the “Value Acknowledgement” or “Child Acknowledgement” events, and value gives the DatasyncValue associated to the event (including its acknowledgement status).

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val node = manager / "contacts"
val options = SubscriptionOptions(includesAcknowledgements = true)
val subscription = node.subscribe(Value.Changed::class, options = options) { // it: Notification<Value.Changed>
  when (it) {
    is Notification.DataNotification -> { // it.data: Value.Changed
      if (!it.data.isAcknowledgement) println("The data at CONTACTS has changed: ${it.data.value}")
      println("The data at CONTACTS ${if (it.data.value.acknowledged) "is" else "is not"} acknowledged")
    }
    is Notification.ControlNotification ->
      println("The subscription on CONTACTS has been canceled or revoked! ${it.error?.message}")
  }
}

Unsubscribing is done using the cancel() method of the Subscription object returned by the previous subscribe() method:

subscription.cancel()

Note that subscriptions are managed by DatasyncManager objects so that each manager automatically cancels its registered subscription when released (ie garbage-collected). A typical use-case is to create a dedicated manager for each Activity or Fragment of your Android app and bind their life-cycles. Thus, this avoids managing explicitly the cancelation of subscriptions, which is generally a tedious task.

In Swift, a subscription is registered using the subscribe() method of DatasyncNode objects and is managed by the DatasyncManager object that has created this DatasyncNode instance. A subscription is specified by a callback function that will be called each time the corresponding event is raised. The subscribed type of event is represented by a value of the dedicated DatasyncEventType enum.

The subscription callback receives as parameter a DatasyncEvent value that provides convenient methods to retrieve the kind of the just raised event, the value of the associated data node, as well as the corresponding DatasyncSubscription object (which makes it possible to individually revoke the subscription without waiting for the manager to do it).

let manager = Webcom.defaultApplication.datasyncService.createManager()
let contactsNode = manager / "contacts"
contactsNode?.subscribe(to: .valueChange) { event in
    guard let allContacts: [Contact] = event.value.decoded() else {
        return
    }
    print("The 'contacts' node has \(allContacts.count) child nodes")
}

Subscriptions are managed by DatasyncManager objects so that each manager automatically cancels its registered subscription when released. The idea is to create a manager for each view controller and bind their life-cycles, in order to avoid explicitly managing the cancelation of subscriptions, which is generally a tedious task.

Not available in REST API

In JavaScript, the “Value Change” event type is represented by the Webcom.Event.ValueChange constant. The val() method of the DataSnapshot object passed to the callback gets the subscriber node value.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let contactsNode = database.rootNode.relativeNode("contacts");
// Display the count of contacts in real time
contactsNode.subscribe(Webcom.Event.ValueChange,
    Webcom.Callback(dataSnapshot => {
        console.log("There are now", Object.keys(dataSnapshot.val()).length, "contacts");
    })
);

In Kotlin, there are 2 variants of the “Value Change” event type:

• Value.Changed, which conveys the value of the subscriber node when raised,
• Value.ChangedHidingData, which doesn't convey the value of the subscriber node when raised.

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Display the count of contacts in real time
val subscription = contactsNode.subscribe(Value.Changed::class) { // it: Notification<Value.Changed>
  when (it) {
    is Notification.DataNotification -> // it.data: Value.Changed
      println("There are now ${it.data.value.asMap.size} contacts")
    is Notification.ControlNotification -> println("Contact watching revoked: ${it.error?.message}")
  }
}

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Display the count of contacts in real time
contactsNode?.subscribe(to: .valueChange) { event in
    print("There are now \(event.value.decoded(as: [String: Contact].self)?.count ?? 0) contacts")
} onCompletion: { completion in
    if case let .revocation(reason: reason) = completion {
        print("Contact watching revoked: \(reason)")
    }
}

In JavaScript, you ask receiving acknowledgement events by calling the includeAcknowledgements() method of the Callback object passed to the subscribe() method.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let contactsNode = database.rootNode.relativeNode("contacts");

let callback = Webcom.Callback(/*...*/) // define a callback
        .includeAcknowledgements()  // ask notifications on acknowledgements

// Display a message each time the contact list is acknowledged by the back end
contactsNode.subscribe(
    Webcom.Event.ValueChange,
    Webcom.Callback(dataSnapshot => {
        if (dataSnapshot.event.isAck) { console.log("The contact list has just been acknowledged"); } 
        /* else the contact list has just been updated (in the acknowledged state or not) */
    })
);

In Kotlin, you ask receiving acknowledgement events by passing a SubscriptionOptions object with the includesAcknowledgement property set to true to the subscribe() method.

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Display a message each time the contact list is acknowledged by the back end
val options = SubscriptionOptions(includesAcknowledgements = true)
contactsNode.subscribe(Value.Changed::class, options = options) { // it: Notification<Value.Changed>
  if (it is Notification.DataNotification && it.data.isAcknowledgement)
      println("The contact list has just been acknowledged")
  /* else the contact list has just been updated (in the acknowledged state or not) */
}

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Display a message each time the contact list is acknowledged by the back end
contactsNode?.subscribe(to: .valueEvent) {
    if $0.value.isAcknowledged {
        print("The contact list is acknowledged")
    }
}

In JavaScript, the “Child Addition” event type is represented by the Webcom.Event.Child.Addition constant.

The first argument passed to the callback is a DataSnapshot object, whose node.key property gives the key of the added child, and whose val() method gets its value. The second argument passed to the callback is a string representing the key of the child that precedes the added child or null if it is the first child of the subscriber node.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");
// Update a GUI in real-time each time a new contact is added
node.subscribe(Webcom.Event.Child.Addition,
    Webcom.Callback((dataSnapshot, previousChildKey)  => {
        myView.addItem({name: dataSnapshot.node.key, value: dataSnapshot.val(), after: previousChildKey});
    })
);

In Kotlin, the “Child Addition” event type is represented by the Child.Added interface:

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is added
val subscription = contactsNode.subscribe(Child.Added::class) { // it: Notification<Child.Added>
  when (it) {
    is Notification.DataNotification -> // it.data: Child.Added
      myView.addItem(name = it.data.node.key, value = it.data.value.asA(Contact::class))
    is Notification.ControlNotification -> println("Contact watching revoked: ${it.error?.message}")
  }
}

If needed, the previousKey property gives the key of the preceding child node or null if the subscriber node is in first position.

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is added
contactsNode?.subscribe(to: .childAddition) { event in
    myView.addItem(name: event.key, value: event.value.decoded())
} onCompletion: { completion in
    if case let .revocation(reason: reason) = completion {
        print("Contact watching revoked: \(reason)")
    }
}

In JavaScript, the “Child Change” event type to is represented by the Webcom.Event.Child.Change constant.

The first argument passed to the callback is a DataSnapshot object, whose node.key property gives the key of the changed child, and whose val() method gets its new value. The second argument passed to the callback is a string representing the key of the child that precedes the changed child or null if it is the first child of the subscriber node.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");
// Update a GUI in real-time each time a new contact is updated
node.subscribe(Webcom.Event.Child.Change,
    Webcom.Callback((dataSnapshot, previousChildKey) => {
        myView.updateItem({name: dataSnapshot.node.key, value: dataSnapshot.val(), after: previousChildKey});
    })
);

In Kotlin, the “Child Change” event type is represented by the Child.Changed interface:

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is updated
val subscription = contactsNode.subscribe(Child.Changed::class) { // it: Notification<Child.Changed>
  when (it) {
    is Notification.DataNotification -> // it.data: Child.Changed
      myView.updateItem(name = it.data.node.key, value = it.data.value.asA(Contact::class), after = it.data.previousKey)
    is Notification.ControlNotification -> println("Contact watching revoked: ${it.error?.message}")
  }
}

As with Child.Added, the previousKey property gives the key of the preceding child node or null if the subscriber node is in first position.

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is added
contactsNode?.subscribe(to: .childChange) { event in
    myView.updateItem(name: event.key, value: event.value.decoded())
} onCompletion: { completion in
    if case let .revocation(reason: reason) = completion {
        print("Contact watching revoked: \(reason)")
    }
}

In JavaScript, the “Child Removal” event type is represented by the Webcom.Event.Child.Removal constant. The argument passed to the callback is a DataSnapshot object, whose node.key method gives the key of the removed child, and whose val() method gets its deleted value.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");
// Update a GUI in real-time each time a new contact is deleted
node.subscribe(Webcom.Event.Child.Removal,
    Webcom.Callback(dataSnapshot => {
        myView.deleteItem({name: dataSnapshot.node.key});
    })
);

In Kotlin, the “Child Removal” event type is represented by the Child.Removed interface:

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is deleted
val subscription = contactsNode.subscribe(Child.Removed::class) { // it: Notification<Child.Removed>
  when (it) {
    is Notification.DataNotification -> // it.data: Child.Removed
      myView.deleteItem(name = it.data.node.key)
    is Notification.ControlNotification -> println("Contact watching revoked: ${it.error?.message}")
  }
}

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is added
contactsNode?.subscribe(to: .childRemoval) { event in
    myView.deleteItem(name: event.key)
} onCompletion: { completion in
    if case let .revocation(reason: reason) = completion {
        print("Contact watching revoked: \(reason)")
    }
}

As with “Value Acknowledgement” events, you ask receiving acknowledgements by calling the includeAcknowledgements() method of the Callback object passed to the subscribe() method.
In addition, note how the various child events can be combined:

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
const database = app.serverlessDb;
let node = database.rootNode.relativeNode("contacts");

// Update a GUI in real-time each time the list of contacts is updated
node.subscribe(
    Webcom.Event.Child.Removal.Addition.Change, // subscribe to all child events at the same time
    Webcom.Callback((dataSnapshot, previousChildKey) => {
        if (dataSnapshot.event.isChildAddition) {
            myView.addItem({name: dataSnapshot.node.key, value: dataSnapshot.val(), after: previousChildKey});
        } else if (dataSnapshot.event.isChildChange) {
            myView.updateItem({name: dataSnapshot.node.key, value: dataSnapshot.val()});
        } else if (dataSnapshot.event.isChildRemoval) {
            myView.deleteItem({name: dataSnapshot.node.key}); // mark the item removed without deleting it
        } else if (dataSnapshot.event.isAck) {
            // child acknowledgement events do nothing here
        }
        // darken, lighten or delete the item depending on its acknowledged and removed statuses
        myView.ackItem({name: dataSnapshot.node.key, acknowledged: dataSnapshot.acked});
    }).includeAcknowledgements() // ask also notifications on acknowledgements
);

As with “Value Acknowledgement” events, you ask receiving acknowledgements by passing a SubscriptionOptions object with the includesAcknowledgement property set to true to the subscribe() method.

import com.orange.webcom.sdk.datasync.subscription.SubscribableEvent.*

val app = WebcomApplication.default
val manager = app.datasyncService.createManager()
val contactsNode = manager / "contacts"
// Update a GUI in real-time each time a new contact is added
val options = SubscriptionOptions(includesAcknowledgements = true)
val subscription = contactsNode.subscribe(Child.AddedChangedRemoved::class, options = options) { // it: Notification<Child.AddedChangedRemoved>
  when (it) {
    is Notification.DataNotification -> with(it.data) { // this: Child.AddedChangedRemoved
      // this is an instance of either Child.Added, Child.Changed, Child.Removed or Child.Acknowledged
      if (!isAcknowledgement) when (this) { // Child.Acknowledged inherits all Child.* interfaces, so it must be checked first
        is Child.Added -> myView.addItem(name = node.key, value = value.asA(Contact::class))
        is Child.Changed -> myView.updateItem(name = node.key, value = value.asA(Contact::class), after = previousKey)
        is Child.Removed -> myView.deleteItem(name = node.key) // mark the item removed without deleting it
      }
      // darken, lighten or delete the item depending on its acknowledged and removed statuses
      myView.markItem(name = node.key, acknowledged = value.acknowledged)
    }
    is Notification.ControlNotification -> println("Contact watching revoked: ${it.error?.message}")
  }
}

The Child.Acknowledged interface inherits all Child.Added, Child.Changed and Child.Removed ones. Consequently, you have to check whether an event is Child.Acknowledged BEFORE performing any pattern matching against one of these interfaces.
To do so, simply test the isAcknowledgement property.

Note also how you can subscribe to several child events: there is one interface available for each possible combination: Child.AddedChanged for subscribing to both “Child Addition” and “Child Change” events, Child.AddedRemoved for both “Child Addition” and “Child Removal”, etc...

let app = Webcom.defaultApplication
let manager = app.datasyncService.createManager()
let contactsNode = manager / "contacts"
// Update a GUI in real-time each time the list of contacts is updated
contactsNode?.subscribe(to: .childEvent) { event in
    switch event.eventType {
    case .childAddition:
        myView.addItem(name: event.key, value: event.value.decoded())
    case .childChange:
        myView.updateItem(name: event.key, value: event.value.decoded())
    case .childRemoval:
        myView.deleteItem(name: event.key) // mark the item removed without deleting it
    case .childAcknowledgement:
        break // childAcknowledgement vents do nothing here
    default:
        break // other events are not subscribed
    }
    // darken, lighten or delete the item depending on its acknowledged and removed statuses
    myView.markItem(name: event.key, isAcknowledged: event.value.isAcknowledged) 
} onCompletion: { completion in
    if case let .revocation(reason: reason) = completion {
        print("Contact watching revoked: \(reason)")
    }
}