Piper Push Cache Documentation Download Samples Contact  

Subscriptions

Subscription are made through a WeSocket connection using the SUBSCRIBE command. Subscriptions are removed with the UNSUBSCRIBE command. A subscription is a means of expressing an interest in changes in the cache or in a cached record. When a change occurs the JSON record is pushed to the browser over the WebSocket.

The basic form of a subscription command is

SUBSCRIBE <filter>
SUBSCRIBE <rec-id>

This command will return the JSON for the record identified or a not-found error. Changes in the record will be pushed if there are changes in the record content or if the record is deleted. If deleted a special admin remove JSON record will be sent.

The filter can be either a record identifier, the wildcard character '*', or a filter expression. Filter expression are describe under the 'filter' help topic.

If subscribed to a single record identifier then only changes in that record are pushed.

If the wildcard is used then all records are pushed when changes occur.

By far the most interesting subscriptions are the filtered subscriptions. A filter expression is used to identify the records to subscribe to. A filter expression must start with an open paren and finish with a closed paren. More details of in the 'filter' help topic.

Subscriptions can also be named. This allows an unsubscribe command to identify the subscrition by name instead of by the original filter. As with specific record subscriptions, notification of records removed or that no longer match the filter is done using an admin message.

SUBSCRIBE <filter> <name>

Sort keys can be included in square brackets to indicate a sort order. If a sort order is specified then all matching records are sent as a batch or a JSON array that contains all the matching records in sorted order. An empty set of brackets will send all records unsorted in a batch. No more than 4 sort keys will be used.

SUBSCRIBE <filter> [<key1> <key2>] <name>

If initial values are desired then the SUBSCRIBE verb is changed to SUBSCRIBE! instead. The '!' indicates the current values that match the pattern or record identifier should be send as initial values. This only applies to non-batch subscriptions.