This specification is currently a draft under development. |
The CloudOS Subscription Event Protocol provides an event based model for managing subscriptions between Personal Clouds. The current implementation of the protocol will create a symmetric relationship between both Personal Clouds. In order to use the Subscription Event Protocol the CloudOS ruleset must be installed in the Personal Cloud for both the originator and target.
The system:subscribe
event is used to create a channel between two Personal Clouds.
cloudos
subscribe
channelName
namespace
relationship
targetChannel
channelName
attribute is a label associated with the subscription that should convey meaning to developer. The channelName
is only used as a component in the creation of the event channel identifier. If no channelName
is specified the value of "orphan" will be used.namespace
attribute is provided as a means for the developer to group subscriptions within a single, or group, or applications. The namespace
is used to filter the list of subscriptions returned by the subscriptionList()
function. If no namespace
is specified the value of "shared" will be used.relationship
attribute allows the developer to characterize the relationship between the originator and target clouds. The relationship
attribute should be specified as a pair of values separated by a dash (e.g. parent-child
, peer-peer
, master-slave
). The first value of the relationship attribute will be stored with the originating Personal Cloud subscription, the second value will be stored with the target Personal Cloud subscription. The relationship
attribute values are used to filter the list of subscriptions returned by the subscriptionList()
function. If no relationship is specified the value of "peer-peer" will be used.targetChannel
attribute is the event channel identifier for the target cloud to which the subscription is to be made.system:subscribe
event. This is most often done in a rule postlude as shown in the following example:fired { raise cloudos event subscribe with channelName = "Coworkers Bob+Ted" and namespace = "MyFriends" and relationship = "friend-friend" and targetChannel = "3f15b820-af7f-012f-4c6e-00163ebczzzz" and _api = "sky"; } |
Upon receiving the subscription request, the target cloud raises the following event to the originating cloud:
cloudos
subscriptionRequestAdded
targetChannel
, backChannel
, namespace
, relationship
, channelName
rule receive_subscriptionRequestAdded select when cloudos subscriptionRequestAdded namespace re/MyFriends/" channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ |
fired { raise cloudos event subscriptionRequestApproved with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and _api = "sky"; } |
rule receive_subscriptionRequestAdded select when cloudos subscriptionRequestAdded namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ |
fired { raise cloudos event subscriptionRequestRejected with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and _api = "sky"; } |
rule receive_subscriptionRejected select when cloudos subscriptionRejected namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ |
rule receive_subscriptionRejected select when cloudos subscriptionRejected namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ |
The system:unsubscribe event is used to remove the Personal Channels between two Personal Clouds.
fired { raise cloudos event unsubscribe with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcfddfd" and _api = "sky"; } |
rule receive_CloudOS_subscriptionRemoved select when cloudos CloudOS_subscriptionRemoved namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ |
The subscriptionList() function will return a map of the subscriptions within the specified namespace and relationship. In order to use the function you must include the CloudOS module as a pragma in the meta section of your ruleset:
use module a169x625 alias CloudOS