Managing Subscriptions

The LinkSmart Event Manager provides publish/subscribe functionality, i.e., the ability for publishers to send a notification to multiple subscribers while being decoupled from them (in terms of, e.g., not holding direct references to subscribers). The Event Manager is used in any place where there is a potential many-to-many relationship between senders and receivers and where asynchronous communication is desirable. The Event Manager routes events to subscribed clients and a <a href="https://fogbugz.cnet.se/default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=425&amp;sFileName=EventSubscriber.zip" data-cke-saved-href="https://fogbugz.cnet.se/default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=425&amp;sFileName=EventSubscriber.zip"><span style="color: #21759b;">EventSubscriber.zip</span></a> assists in interfacing to the Network Manager (e.g., broadcast-, multicast-, or gossiping-based dissemination). It manages persistent subscriptions and publication to subscription matching etc. The Event Manager allows sending and receiving events through the LinkSmart P2P network. An event message consists of a standardized header section including metadata for routing and management of event messages without requirements for reading the actual content, the payload, of the message. It includes topic definitions, identification etc. The payload of the message can now include any content.  See <a href="https://fogbugz.cnet.se/default.asp?W89" data-cke-saved-href="default.asp?W89"><span style="color: #21759b;">Events – Content Model</span></a> for a full description of the event information model. For set up a subscription, the <strong><span style="font-family: Thread-0000983c-Id-00000951;">receiver </span></strong>of events needs to: <ol> <li>Add web service wsdl to Event Manager either by file or direct from the Event Manager.</li> <li>Implement the call back notification methods and,</li> <li>Register the subscription with the Event Manager providing the call back address.</li> </ol> For publication of events, the <strong><span style="font-family: Thread-0000983c-Id-00000951;">publisher </span></strong>needs to <ol> <li>Add web service WSDL to the Event Manager either by file or direct from the Event Manager.</li> <li>call the publication methods of the Event Manager.</li> </ol> <h2>Add web service WSDL to Event Manager</h2> In ordet to communicate with the Event Manager a web service needs to be added. Either using local WSDL that can be downloaded here: <a href="https://fogbugz.cnet.se/default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=421&amp;sFileName=EventManagerWSDL.zip" data-cke-saved-href="default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=421&amp;sFileName=EventManagerWSDL.zip"><span style="color: #21759b;">EventManagerWSDL.zip</span></a> or direct from the Event Manager: http://127.0.0.1:8124/Service/Meta?wsdl, were url and port is set in the Event Manager configuration file. <h2>Setting up Event Subscriptions</h2> Three subscribe methods are available for setting up event subscriptions using XPath based selection mechanisms. They differ in how they express the call-back address of its notification method, it is either a local address (i.e. an endpoint) when a LinkSmart Network Manager is not used, or a persistent (the PID) or dynamic (the HID) address within a LinkSmart virtual network. <code><span style="color: #c7254e; font-family: Consolas; font-size: small;">public bool subscribeXPath(string xpath, string endpoint, int priority)</span></code> public bool subscribeXPathWithHID(string xpath, string HID, int priority) public bool subscribeXPathWithPID(string xpath, string PID, int priority) The ‘<strong><span style="font-family: Thread-0000983c-Id-00000951;">xpath</span></strong>’ parameter is used to define a filter on which events that will be included in the subscription based on the content of the event, both in terms of event metadata and payload. Examples: <ul> <li>.* wildcard subscription – result in a subscription of all events.</li> <li>//[local-name()='IoTEntity' and @about='000D6F0000D36116']  – result in a subscription of all events including an IoTEntity element with an @about attribute taking the value ‘000D6F0000D36116′</li> <li>//[local-name()='IoTProperty' and @typeof='TEMPERATURE'])   – result in a subscription of all events including an IoTProperty element with a @typeof attribute taking the value ‘TEMPERATURE’</li> </ul> Note that namespaces are not currently supported in the XPath expression which requires somewhat clumsy XPath expressions using local-name() functions. The ‘<strong><span style="font-family: Thread-0000983c-Id-00000951;">priority</span></strong>’ parameter is used to request higher priority in delivery of event messages where a higher number sets an higher priority. Normally, it can be set to ‘1’. See <a href="https://fogbugz.cnet.se/default.asp?W98" data-cke-saved-href="default.asp?W98"><span style="color: #21759b;">Use case – Setting up an Event Subscription using the Network Manager and Event Manager</span></a> for a detailed example of setting up a subscription in a LinkSmart network. <h2>Unsubscribing</h2> Subscriptions can be cancelled by calling unsubscribe() or clearSubscription() methods. Depending on how the subscription was set up, the corresponding unsubscribe() method should be used to cancel a particular subscription: <code><span style="color: #c7254e; font-family: Consolas; font-size: small;">public bool unsubscribe(string selection, string endpoint)</span></code> public bool unsubscribeWithHID(string selection, string HID) public bool unsubscribeWithPID(string selection, string PID) For cancelling all subscriptions by a particular receiver, call the appropriate clearSubscription() methods: <code><span style="color: #c7254e; font-family: Consolas; font-size: small;">public bool clearSubscriptions(string endpoint)</span></code> public bool clearSubscriptionsWithHID(string HID) public bool clearSubscriptionsWithPID(string PID) <h2>Call back notification method to be implemented by the subscriber</h2> An entity that wants to receive events from the Event Manager must implement a notification method as a Web Service on the provided endpoint or virtual address. The Web Service method that must be implemented is: <code><span style="color: #c7254e; font-family: Consolas; font-size: small;">public bool notifyXmlEvent(string eventXmlString)</span></code> It is defined in a WSDL that can be downloaded here: <a href="https://fogbugz.cnet.se/default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=403&amp;sFileName=EventSubscriber.zip" data-cke-saved-href="default.asp?pg=pgDownload&amp;pgType=pgWikiAttachment&amp;ixAttachment=403&amp;sFileName=EventSubscriber.zip"><span style="color: #21759b;">EventSubscriber.zip</span></a>. Note that it also include other legacy methods. <h2>Event publishing method to be called by the publisher</h2> The entity that wants to publish an event via the Event Manager must first create a Event Manager Port Client and call its publishXmlEvent() method. The port client can be found in the WSDL for the Event Manager. <code><span style="color: #c7254e; font-family: Consolas; font-size: small;">public bool publishXmlEvent(string eventXmlString)</span></code>