<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/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/Basic+Routing+Service+Design">Basic Routing Service Design</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~khunt">Ken Hunt</a>
</h4>
<br/>
<h4>Changes (10)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-unchanged" >h3. Overview <br></td></tr>
<tr><td class="diff-changed-lines" >The <span class="diff-added-words"style="background-color: #dfd;">Basic</span> Routing Service provides a central facility for looking up Endpoint interfaces. The <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channel Services</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateways</span> dynamically register and deregister their own EndpointLocator interface with the Routing Service, along with one or more regular expressions which describe which destinations are managed by a given EndpointLocator interface. The Routing Service acts as an aggregator for all of the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channel-specific</span> EndpointLocators, so any component in the system which needs to lookup an endpoint need only refer to the Routing Service. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >The <span class="diff-added-words"style="background-color: #dfd;">Basic</span> Routing Service also provides the capability to route Session objects, by looking up a requested destination endpoint, creating a new session for the destination, and causing a Bridge to be created to connect the two sessions. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >This page describes the design of a Basic Routing Service which incorporates a script engine. Various users / deployments are expected to require very specific Routing needs, so custom implementations of Routing Service implementations <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">could become</span> <span class="diff-added-words"style="background-color: #dfd;">are expected to be</span> common. The Script Engine acts as a simple example of a means to support custom extensions <span class="diff-changed-words">within<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">g</span></span> a component, and is an alternative to the Extension Point mechanisms described on [Extension Points and Hooks]. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h3. Class Structure <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" ># The administrative interfaces are separate to allow controlled access to the administrative functionality. <br># The Administrative interfaces are implemented by a totally distinct object, so that a reference to the LocatorRegistry interface can't be simply cast to a RoutingServiceAdmin interface. <br></td></tr>
<tr><td class="diff-changed-lines" ># The <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">lookup operation (of EndpointLocator interface) and the</span> setPolicy operation (of the RoutingServiceAdmin interface) will be forwarded to a Lua Script Processor. The administrative operation setPolicy will have a no-op default operation, but could be altered (via scripting) to deny lookups for a variety of reasons, such as time of day, etc. <span class="diff-added-words"style="background-color: #dfd;">The lookup() operation calls the Lua Script Processor for each invocation to determine if the lookup() is allowed based on whatever script is active.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br> <br>|!BasicRoutingService.png|border=1!| <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words">|<span class="diff-added-chars"style="background-color: #dfd;"> </span>{center}<span class="diff-added-chars"style="background-color: #dfd;"> </span>*Figure</span> 1. Routing Component Class <span class="diff-changed-words">Structure*<span class="diff-added-chars"style="background-color: #dfd;"> </span>{center}<span class="diff-added-chars"style="background-color: #dfd;"> </span>|</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h3. Operation <br> <br></td></tr>
<tr><td class="diff-changed-lines" >EndpointLocator implementations are registered with the Routing Service <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">via their respective Channel Service.</span> <span class="diff-added-words"style="background-color: #dfd;">by the Session Gateway that manages them.</span> The <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channel Service</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> locates the Routing Service via the system Service Locator, as shown in Figure 2. The Service Locator's location is set via configuration / deployment for most all Asterisk SCF components. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >At some point during the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channel Service</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> startup, the ChannelService acquires a reference to the RoutingService in order to provide the RoutingService with its EndpointLocator interface. When it does, the ChannelService provides a sequence of regular expressions that define the ranges (or other patterns) of destination ids that are managed by the channel. <br></td></tr>
<tr><td class="diff-unchanged" > <br>When devices outside of the Asterisk SCF system register with the ChannelService after the ChannelService has initialized, the ChannelService can (if needed) update the device IDs associated with it's EndpointLocator by calling SetEndpointLocatorDeviceIds with a new set of regular expressions. <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|!RegistrationSequence.jpg|border=1!| <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">|!BasicRoutingService Locator Registration.jpg|border=1!| <br></td></tr>
<tr><td class="diff-unchanged" >|{center}*Figure 2. Registering Endpoints with the Routing Service*{center}| <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Figure 3 shows the Routing Service routing a Session. A client <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Channel Service</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> calls routeSession() of the SessionRouter interface published by the Basic Routing Service. The Routing Service calls lookup() on itself, which identifies the applicable ChannelService. It then uses the EndpointLocator registered by the destination's ChannelService to get a reference to the Endpoint. If this succeeds, the Routing Service creates a new Session via the destination endpoint's interface. <br></td></tr>
<tr><td class="diff-unchanged" > <br>The Bridge Service is accessed (via the Service Locator - not shown), and a Bridge object is created to bridge the calling and destination Session objects. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h3><a name="BasicRoutingServiceDesign-Overview"></a>Overview</h3>
<p>The Basic Routing Service provides a central facility for looking up Endpoint interfaces. The Session Gateways dynamically register and deregister their own EndpointLocator interface with the Routing Service, along with one or more regular expressions which describe which destinations are managed by a given EndpointLocator interface. The Routing Service acts as an aggregator for all of the EndpointLocators, so any component in the system which needs to lookup an endpoint need only refer to the Routing Service. </p>
<p>The Basic Routing Service also provides the capability to route Session objects, by looking up a requested destination endpoint, creating a new session for the destination, and causing a Bridge to be created to connect the two sessions. </p>
<p>This page describes the design of a Basic Routing Service which incorporates a script engine. Various users / deployments are expected to require very specific Routing needs, so custom implementations of Routing Service implementations are expected to be common. The Script Engine acts as a simple example of a means to support custom extensions within a component, and is an alternative to the Extension Point mechanisms described on <a href="/wiki/display/TOP/Extension+Points+and+Hooks" title="Extension Points and Hooks">Extension Points and Hooks</a>.</p>
<h3><a name="BasicRoutingServiceDesign-ClassStructure"></a>Class Structure</h3>
<p>The basic structure of the Routing Service component is shown in Figure 1 below. Notes on the class structure:</p>
<ol>
<li>The administrative interfaces are separate to allow controlled access to the administrative functionality.</li>
<li>The Administrative interfaces are implemented by a totally distinct object, so that a reference to the LocatorRegistry interface can't be simply cast to a RoutingServiceAdmin interface.</li>
<li>The setPolicy operation (of the RoutingServiceAdmin interface) will be forwarded to a Lua Script Processor. The administrative operation setPolicy will have a no-op default operation, but could be altered (via scripting) to deny lookups for a variety of reasons, such as time of day, etc. The lookup() operation calls the Lua Script Processor for each invocation to determine if the lookup() is allowed based on whatever script is active.</li>
</ol>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="image-wrap" style=""><img src="/wiki/download/attachments/2129977/BasicRoutingService.png?version=2&modificationDate=1337202732698" style="border: 1px solid black" /></span></td>
</tr>
<tr>
<td class='confluenceTd'> </td>
</tr>
</tbody></table>
</div>
<h3><a name="BasicRoutingServiceDesign-Operation"></a>Operation</h3>
<p>EndpointLocator implementations are registered with the Routing Service by the Session Gateway that manages them. The Session Gateway locates the Routing Service via the system Service Locator, as shown in Figure 2. The Service Locator's location is set via configuration / deployment for most all Asterisk SCF components. </p>
<p>At some point during the Session Gateway startup, the ChannelService acquires a reference to the RoutingService in order to provide the RoutingService with its EndpointLocator interface. When it does, the ChannelService provides a sequence of regular expressions that define the ranges (or other patterns) of destination ids that are managed by the channel. </p>
<p>When devices outside of the Asterisk SCF system register with the ChannelService after the ChannelService has initialized, the ChannelService can (if needed) update the device IDs associated with it's EndpointLocator by calling SetEndpointLocatorDeviceIds with a new set of regular expressions. </p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="error">Unable to render embedded object: File (BasicRoutingService Locator Registration.jpg) not found.</span></td>
</tr>
<tr>
<td class='confluenceTd'> </td>
</tr>
</tbody></table>
</div>
<p>Figure 3 shows the Routing Service routing a Session. A client Session Gateway calls routeSession() of the SessionRouter interface published by the Basic Routing Service. The Routing Service calls lookup() on itself, which identifies the applicable ChannelService. It then uses the EndpointLocator registered by the destination's ChannelService to get a reference to the Endpoint. If this succeeds, the Routing Service creates a new Session via the destination endpoint's interface. </p>
<p>The Bridge Service is accessed (via the Service Locator - not shown), and a Bridge object is created to bridge the calling and destination Session objects. </p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <span class="image-wrap" style=""><img src="/wiki/download/attachments/2129977/Routing+Service+Session+Routing+Sequence.png?version=3&modificationDate=1337202704126" style="border: 1px solid black" /></span> </td>
</tr>
<tr>
<td class='confluenceTd'> </td>
</tr>
</tbody></table>
</div>
<h3><a name="BasicRoutingServiceDesign-PublishedEvents"></a>Published Events</h3>
<p>As seen in RoutingServiceIf.ice, the following events are published by the Routing Service component.</p>
<div class="code panel" style="border-style: solid;border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><b>From RoutingServiceIf.ice</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">module Hydra
{
module RoutingService
{
...
module Event
{
enum OperationResult
{
SUCCCESS,
FAILED
};
/**
* Interface for monitoring the basic routing service events.
*/
interface RoutingEvents
{
/**
* Notification that a lookup was attempted.
*
* @param operationContext Provides unique context for each call to this operation.
* @param destinationId The destination being looked up.
* @param result Indicates whether or not the attempt was successful.
*/
idempotent void lookupEvent(
AsteriskSCF::System::V1::OperationContext operationContext,
string destinationId, OperationResult result);
/**
* Notification that an attempt to add an EndpointLocator was made.
*
* @param operationContext Provides unique context for each call to this operation.
* @param id The identifier of the EndpointLocator being added.
* @param destinationIdRangeList A set of regular expressions that define the endpoints available.
* @param result Indicates whether or not the attempt was successful.
*/
idempotent void addEndpointLocatorEvent(
AsteriskSCF::System::V1::OperationContext operationContext,
string id, RegExSeq destinationIdRangeList, EndpointLocator *locator, OperationResult result);
/**
* Notification that an attempt was made to remove an EndpointLocator.
*
* @param operationContext Provides unique context for each call to this operation.
* @param id The identifier of the EndpointLocator being removed.
* @param result Indicates whether or not the attempt was successful.
*/
idempotent void removeEndpointLocatorEvent(
AsteriskSCF::System::V1::OperationContext operationContext,
string id, OperationResult result);
/**
* Notification that an attempt was made to modify the range of destinationIds
* accessible from a given EndpointLocator.
*
* @param operationContext Provides unique context for each call to this operation.
* @param id The destination being looked up.
* @param destinationIdRangeList A list of regular expressions to be representative of the new valid ids.
* @param result Indicates whether or not the attempt was successful.
*/
idempotent void setEndpointLocatorDestinationIdsEvent(
AsteriskSCF::System::V1::OperationContext operationContext,
string id, RegExSeq destinationIdRangeList, OperationResult result);
/**
* Called when the EndpointLocator cache has been cleared by an administrative action.
*
* @param operationContext Provides unique context for each call to this operation.
*/
void clearEndpointLocatorsEvent(AsteriskSCF::System::V1::OperationContext operationContext);
/**
* Called when an administration operation has set the routing service policy.
*
* @param operationContext Provides unique context for each call to this operation.
* @param policy The new policy.
*/
idempotent void setPolicyEvent(
AsteriskSCF::System::V1::OperationContext operationContext,
string policy);
};
};
};</pre>
</div></div>
<h3><a name="BasicRoutingServiceDesign-Itemstoberesolved"></a>Items to be resolved</h3>
<ul>
<li>Failover - The failover design needs to be incorporated into this component.</li>
<li>I haven't put much thought into how we protect access to the Administrative interface.</li>
</ul>
</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/Basic+Routing+Service+Design">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=2129977&revisedVersion=41&originalVersion=40">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Basic+Routing+Service+Design?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>