Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Draft Specification

This specification is currently a draft under development.

Subscription Event Protocol

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.

Subscribe

The system:subscribe event is used to create a channel between two Personal Clouds.

cloudos:subscribe(channelName, namespace, relationship, targetChannel)

  • The 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.
  • The 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.
  • The 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.
  • The targetChannel attribute is the event channel identifier for the target cloud to which the subscription is to be made.
The ruleset wishing to create the subscription signals the CloudOS to do so by raising the system:subscribeevent. 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";
}

The CloudOS service raises the cloudos:subscriptionRequestAdded event within the originating cloud so that other rulesets can take action, if needed:

  • domain: cloudos
  • type: subscriptionRequestAdded
  • attributes: targetChannel, backChannel, namespace, relationship, channelName

The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:

rule receive_subscriptionRequestAdded
  select when cloudos subscriptionRequestAdded
    namespace re/MyFriends/"
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/

The CloudOS services in the target cloud raises the cloudos:subscriptionRequestPending to signal the receipt of a pending subscription request:

  • domain: cloudos
  • type: subscriptionRequestPending
  • attributes: eventChannel, namespace, relationship, channelName

Subscription Approval or Rejection

With the subscription request pending approval, the Personal Cloud which received the request can either approve or reject the request. To approve the subscription request the following event should be raised:
  • domain: cloudos
  • type: subscriptionRequestApproved
  • attributes: eventChannel

 

fired {
  raise cloudos event subscriptionRequestApproved
    with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
    and  _api = "sky";
}

 

Once the subscription request is approved both Personal Clouds will receive a callback events raised within each respective Personal Cloud. These events are raised to enable the developer to take additional actions when the Personal Channels are actually created.
  • domain: cloudos
  • type: CloudOS_subscriptionAdded
  • attributes: eventChannel, backChannel, namespace, relationship, channelName

 

rule receive_subscriptionRequestAdded
  select when cloudos subscriptionRequestAdded
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/

 

To reject the subscription request the following event should be raised:
  • domain: cloudos
  • type: subscriptionRequestRejected
  • attributes: eventChannel

 

fired {
  raise cloudos event subscriptionRequestRejected
    with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa"
    and  _api = "sky";
}

 

When the subscription request is rejected the following event will be raised with the Personal Cloud:
  • domain: cloudos
  • type: subscriptionRejected
  • attributes: eventChannel, namespace, relationship, channelName

 

rule receive_subscriptionRejected
  select when cloudos subscriptionRejected
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/

 

And the following event will be raised in the Personal Cloud which made the subscription request:
  • domain: cloudos
  • type: subscriptionRejected
  • attributes: backChannel, namespace, relationship, channelName
rule receive_subscriptionRejected
  select when cloudos subscriptionRejected
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/

 

Unsubscribe

The system:unsubscribe event is used to remove the Personal Channels between two Personal Clouds.

  • domain: cloudos
  • type: unsubscribe
  • attribute: backChannel

 

fired {
  raise cloudos event unsubscribe
    with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcfddfd"
    and  _api = "sky";
}

 

The backChannel attribute uniquely identifies the Personal Channel within the Personal Cloud, and provided to the target Personal Cloud for raising events into the current Personal Cloud. The backChannel is one of the attributes provided by the subscriptionList() function.
During the processing of removing the Personal Channels bewteen the two Personal Clouds callback events are raised within each respective Personal Cloud. These events are raised to enable the developer to take additional actions when the Personal Channels are actually being removed.
  • domain: cloudos
  • type: CloudOS_subscriptionRemoved
  • attributes: eventChannel, backChannel, namespace, relationship, channelName

 

rule receive_CloudOS_subscriptionRemoved
  select when cloudos CloudOS_subscriptionRemoved
    namespace re/MyFriends/
    channelName re/Coworkers Bob+Ted/
    relationship re/friend-friend/

 

Functions

subscriptionList(namespace, relationship)

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

 

  • No labels

Copyright Picolabs | Licensed under Creative Commons.