Watches

Overview

Watches are a mechanism used to subscribe to real-time changes made to a set of records in the Folio database. Watches are patterned on oBIX/Haystack watches which are designed around polling-for-changes. Polling provides the foundation for simple but robust networking. And by only polling for values which have changed, we can keep payloads very small. This in turn allows us to efficiently poll several times a second.

Adding records to a watch is also a mechanism used to subscribe to external data by the connector framework.

HTTP APIs

If using watches over the network, then use the following HTTP API ops:

• op:watchSub
• op:watchUnsub
• op:watchPoll

Axon APIs

The following Axon functions are used to work with watches:

• watchOpen()
• watchPoll()
• watchAdd()
• watchRemove()
• watchClose()

Example code:

// read all points under specific connector and put into watch,
// the second parameter to watchOpen is debug string to
// indicate who is opening the watch
grid: readAll(point and fooConnRef==xxxx).watchOpen("My Custom App")

// grid is now the result of my readAll operation, plus it
// contains my watch id to use for polling
watchId: grid.meta->watchId

// now enter a loop to poll for any changes to my original points
changes: watchPoll(watchId)

// when done we should gracefully close the watch, or it will
// close automatically if we fail to poll and its lease expires
watchClose(watchId)

Fantom APIs

The following HxWatchService and HxWatch APIs are used to work with watches in Fantom. The Fantom APIs for working with watches provide more flexiblity and performance than Axon since they operate at a lower level of abstraction.

Here is a simple snippet of Fantom code using watches:

// open new, empty watch
watch := rt.watch.open("My Custom App")

// add some points to the watch
points := rt.db.readAll("point and fooConnRef==xxxx")
watch.addGrid(points)

// poll for changes
while (isAlive)
{
  dicts := watch.poll
}

// re-poll to get current state of all recs in watch
refresh := watch.poll(Duration.defVal)

// close the watch
watch.close