<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2160/1/7/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/Support+for+subscriptions+to+and+from+external+entities">Support for subscriptions to and from external entities</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~kpfleming">Kevin P. Fleming</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
remove unsupported 'language=slice' tags<br />
</div>
<br/>
<h4>Changes (7)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >At the basis of all of this is the subscription itself. There are certain attributes present in all subscription types, and they are represented in a {{SubscriptionData}} class. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{newcode:language=slice}</span> <span class="diff-added-words"style="background-color: #dfd;">{code}</span> <br></td></tr>
<tr><td class="diff-unchanged" >class SubscriptionData <br>{ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > string sender; <br>}; <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">new</span>code}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>Note that a subscription type is not a member of the class. This is because specific types of subscriptions should be defined as subclasses of the {{SubscriptionData}} class. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >We'll examine subscriptions from two different viewpoints: inbound and outbound. First, we'll inspect the {{SubscriptionBroker}} interface. This is used by a communications protocol that has received an inbound subscription request. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">:language=slice</span>}</span> <br></td></tr>
<tr><td class="diff-unchanged" >interface SubscriptionBroker <br>{ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >When an inbound subscription is requested, the SubscriptionBroker is told of the request. The SubscriptionBroker is then responsible for finding an appropriate Asterisk SCF component to be able to handle the subscription request. Once the broker has determined which, if any, component is going to handle the subscription, then the SubscriptionBroker should create a SubscriptionResponse to return to the subscriber. The SubscriptionResponse class is defined as such: <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">:language=slice</span>}</span> <br></td></tr>
<tr><td class="diff-unchanged" >class SubscriptionResponse <br>{ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{{result}} can be used by the subscriber to determine if a component accepted the subscription request. If a component has not accepted the request, then {{result}} can also be used to determine why the subscription request was not accepted. The {{handler}} is a proxy that will be used by the subscriber to send any further information regarding the subscription. Specific subscription types may define subclasses of {{SubscriptionResponse}} that contain more detailed reasons for rejection beyond those defined in {{SubscriptionResultCode}}. The {{Subscription}} interface is defined as follows: <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">:language=slice</span>}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>/** <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >One detail that has been glossed over is how the {{SubscriptionBroker}} gets a {{Subscription}} object to hand back to the subscriber. Any component capable of creating a {{Subscription}} will have a {{SubscriptionFactory}} interface exposed so that new {{Subscriptions}} may be requested. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">:language=slice</span>}</span> <br></td></tr>
<tr><td class="diff-unchanged" >interface SubscriptionFactory <br>{ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The listener must also be able to communicate with the subscriber. The means of doing this will be using the {{Subscriber}} interface. Recall that a proxy to a {{Subscriber}} was passed to the {{SubscriptionBroker}} in {{SubscriptionBroker::subscribe}}. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">{code<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">:language=slice</span>}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>/** <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="Supportforsubscriptionstoandfromexternalentities-Concept"></a>Concept</h1>
<p>Subscriptions in AsteriskSCF may come in many flavors. One obvious one would be SIP subscriptions as defined in <a href="http://www.ietf.org/rfc/rfc3265.txt" class="external-link" rel="nofollow">RFC 3265</a>. However, subscriptions may be started via other protocols or via administration. Therefore, subscription support needs to be written in such a way that it is protocol-agnostic. While Asterisk SCF needs to be able to understand protocol-specific methods of subscribing to resources, it is not within the scope of Asterisk SCF to make decisions regarding such matters. With this in mind, the majority of protocols that support subscriptions of some sort will make use of a <tt>SubscriptionBroker</tt> in order to make it known what is happening. The <tt>SubscriptionBroker</tt> is alerted whenever a subscription request arrives. It is up to the <tt>SubscriptionBroker</tt> to make the decision about how to handle such a request.</p>
<p>At the basis of all of this is the subscription itself. There are certain attributes present in all subscription types, and they are represented in a <tt>SubscriptionData</tt> class.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">class SubscriptionData
{
int expirationSeconds;
string recipient;
string sender;
};</pre>
</div></div>
<p>Note that a subscription type is not a member of the class. This is because specific types of subscriptions should be defined as subclasses of the <tt>SubscriptionData</tt> class. </p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-InboundSubscriptions"></a>Inbound Subscriptions</h1>
<p>We'll examine subscriptions from two different viewpoints: inbound and outbound. First, we'll inspect the <tt>SubscriptionBroker</tt> interface. This is used by a communications protocol that has received an inbound subscription request.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">interface SubscriptionBroker
{
SubscriptionResponse subscribe(SubscriptionData data, Subscriber *sub);
};</pre>
</div></div>
<p>When an inbound subscription is requested, the SubscriptionBroker is told of the request. The SubscriptionBroker is then responsible for finding an appropriate Asterisk SCF component to be able to handle the subscription request. Once the broker has determined which, if any, component is going to handle the subscription, then the SubscriptionBroker should create a SubscriptionResponse to return to the subscriber. The SubscriptionResponse class is defined as such:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">class SubscriptionResponse
{
SubscriptionResultCode result;
Subscription *handler;
};
enum SubscriptionResultCode
{
//XXX More reasons may need to be added here.
//This is primarily for illustrative purposes.
Success,
NotPermitted,
RecipientUnknown,
NotSupported
};</pre>
</div></div>
<p><tt>result</tt> can be used by the subscriber to determine if a component accepted the subscription request. If a component has not accepted the request, then <tt>result</tt> can also be used to determine why the subscription request was not accepted. The <tt>handler</tt> is a proxy that will be used by the subscriber to send any further information regarding the subscription. Specific subscription types may define subclasses of <tt>SubscriptionResponse</tt> that contain more detailed reasons for rejection beyond those defined in <tt>SubscriptionResultCode</tt>. The <tt>Subscription</tt> interface is defined as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">/**
* Thrown when an operation is invoked on a subscription
* that has already had its terminate() method
* called
*/
exception SubscriptionTerminated {};
interface Subscription
{
void renew(SubscriptionData data) throws SubscriptionTerminated;
void expire() throws SubscriptionTerminated;
void terminate() throws SubscriptionTerminated;
};</pre>
</div></div>
<p>Each of these methods notifies the subscription handler of changes to the subscription state. <tt>renew</tt> is mostly informational and alerts the subscription handler that the subscriber has extended his subscription beyond the initial expiration period. <tt>expire</tt> indicates that the subscription has been ended due to a failure to re-subscribe in time. The <tt>terminated</tt> method indicates that the subscriber has ended his subscription manually. Each method takes a <tt>SubscriptionData</tt> member so that the listener can identify which subscription the method call pertains to as well as to see potential differences made to the data.</p>
<p>One detail that has been glossed over is how the <tt>SubscriptionBroker</tt> gets a <tt>Subscription</tt> object to hand back to the subscriber. Any component capable of creating a <tt>Subscription</tt> will have a <tt>SubscriptionFactory</tt> interface exposed so that new <tt>Subscriptions</tt> may be requested.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">interface SubscriptionFactory
{
Subscription *createSubscription(SubscriptionData data);
};</pre>
</div></div>
<p>The listener must also be able to communicate with the subscriber. The means of doing this will be using the <tt>Subscriber</tt> interface. Recall that a proxy to a <tt>Subscriber</tt> was passed to the <tt>SubscriptionBroker</tt> in <tt>SubscriptionBroker::subscribe</tt>. </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">/**
* Thrown when invoking an operation on a Subscriber
* after it has already had its terminate() method
* called
*/
exception SubscriberTerminated{};
interface Subscriber
{
void terminate() throws SubscriberTerminated;
void notify(SubscriptionState state) throws SubscriberTerminated;
};</pre>
</div></div>
<p>The <tt>terminate</tt> method is a method for a subscription handler to end a subscription. The <tt>notify</tt> method is used to indicate to the subscriber that the subscription state has been updated. The <tt>SubscriptionState</tt> object is a subscription package-specific set of information that describes the current state of the subscription. For a presence subscription, for instance, this would convey the current presence state, like "available" or "busy."</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-OutboundSubscriptions"></a>Outbound Subscriptions</h1>
<p>Outbound subscriptions mostly work the same way as inbound ones, except for a few key differences. First off, the role of subscriber and subscription handler is reversed. In other words, a custom-written user component will be the subscriber and the subscription handler will be a protocol component such as SIP. Furthermore, there is no need to use a <tt>SubscriptionBroker</tt> since a <tt>SubscriptionFactory</tt> may be used directly.</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-SimpleExamples"></a>Simple Examples</h1>
<p>So let's consider a typical sequence of events. Lifelines in the sequence diagrams are color-coded to indicate the owning component. Lifelines with the same color are owned by the same component.</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/InboundSubscription.png?version=1&modificationDate=1294435432214" style="border: 0px solid black" /></span></p>
<p>This is a one-legged inbound subscription scenario. Whatever resource Bob wishes to subscribe to is handled entirely by a component within Asterisk SCF. Notifications of state change originate in the <tt>UserComponent</tt> in such a situation. Another common scenario will be that Asterisk SCF sets up a bridge between two external entities. Below are two methods a user might use in order to accomplish the task.</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/SubscriptionBridge.png?version=1&modificationDate=1294435432273" style="border: 0px solid black" /></span></p>
<p>This is the stateless version, where the <tt>UserComponent</tt> is only involved in the setup. Once the subscription is established, The <tt>UserComponent</tt> never sees any more of the messages. The <tt>UserComponent</tt> is able to make initial decisions regarding how to route the subscription, as well as whether to permit the subscription's acceptance.</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/SubscriptionBridge2.png?version=1&modificationDate=1294435432315" style="border: 0px solid black" /></span></p>
<p>This is the stateful version, where the <tt>UserComponent</tt> intercepts all messages passed during the lifetime of the subscription. The way it does this is to create a <tt>Subscription</tt> and a <tt>Subscriber</tt> that the respective SIP components communicate with.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=TOP">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Support+for+subscriptions+to+and+from+external+entities">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=9568785&revisedVersion=21&originalVersion=20">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Support+for+subscriptions+to+and+from+external+entities?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>