<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 (9)</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" >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. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >At some point during the Session Gateway startup, <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">the ChannelService</span> <span class="diff-added-words"style="background-color: #dfd;">a Session Gateway</span> acquires a reference to the RoutingService in order to provide the RoutingService with its EndpointLocator interface. When it does, the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ChannelService</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> provides a sequence of regular expressions that define the ranges (or other patterns) of destination ids that are managed by the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">channel.</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >When devices outside of the Asterisk SCF system register with the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ChannelService after</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway,</span> the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ChannelService has initialized, the ChannelService</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> can (if needed) update the device IDs associated with it's EndpointLocator by calling <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SetEndpointLocatorDeviceIds</span> <span class="diff-added-words"style="background-color: #dfd;">setEndpointLocatorDestinationIds()</span> with a new set of regular expressions. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >|!BasicRoutingService Locator <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Registration.jpg|border=1!|</span> <span class="diff-added-words"style="background-color: #dfd;">Registration.png|border=1!|</span> <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 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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ChannelService.</span> <span class="diff-added-words"style="background-color: #dfd;">EndpointLocator.</span> It then uses the EndpointLocator registered by the destination's <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ChannelService</span> <span class="diff-added-words"style="background-color: #dfd;">Session Gateway</span> to get a reference to the Endpoint. If this succeeds, the Routing Service creates a new Session via the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">destination</span> endpoint's interface. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >The Bridge Service is accessed (via <span class="diff-added-words"style="background-color: #dfd;">a reference obtained from</span> the Service Locator <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">-</span> <span class="diff-added-words"style="background-color: #dfd;">during component startup-</span> not shown), and a Bridge object is created to bridge the calling and destination Session objects. <br></td></tr>
<tr><td class="diff-unchanged" > <br>| !Routing Service Session Routing Sequence.png|border=1! | <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. Items to be resolved <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Failover <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* Failover - The failover design needs to be incorporated into this component. <br>* I haven't put much thought into how we protect access to the Administrative interface. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The Basic Routing Service follows the [Command pattern#http://en.wikipedia.org/wiki/Command_pattern] by encapsulating the routing requests into objects. Each of these Operation objects execute a state machine internally. These state machines transition as remote procedure calls on the various objects in the routing process are completed, and each state transition causes a replication of the Operation's current state. Upon failover, the complimentary objects in the standby component are "fast-forwarded" (a process that applies each state transition's replicated state results), and then these Operation object continue the state machine execution from that point to complete the work that was being processed in the failed component. <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, a Session Gateway acquires a reference to the RoutingService in order to provide the RoutingService with its EndpointLocator interface. When it does, the Session Gateway provides a sequence of regular expressions that define the ranges (or other patterns) of destination ids that are managed by the Session Gateway. </p>
<p>When devices outside of the Asterisk SCF system register with the Session Gateway, the Session Gateway can (if needed) update the device IDs associated with it's EndpointLocator by calling setEndpointLocatorDestinationIds() with a new set of regular expressions. </p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="image-wrap" style=""><img src="/wiki/download/attachments/2129977/BasicRoutingService+Locator+Registration.png?version=1&modificationDate=1337202721822" style="border: 1px solid black" /></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 EndpointLocator. It then uses the EndpointLocator registered by the destination's Session Gateway to get a reference to the Endpoint. If this succeeds, the Routing Service creates a new Session via the endpoint's interface. </p>
<p>The Bridge Service is accessed (via a reference obtained from the Service Locator during component startup- 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-Failover"></a>Failover</h3>
<p>The Basic Routing Service follows the <span class="error">[Command pattern#http://en.wikipedia.org/wiki/Command_pattern]</span> by encapsulating the routing requests into objects. Each of these Operation objects execute a state machine internally. These state machines transition as remote procedure calls on the various objects in the routing process are completed, and each state transition causes a replication of the Operation's current state. Upon failover, the complimentary objects in the standby component are "fast-forwarded" (a process that applies each state transition's replicated state results), and then these Operation object continue the state machine execution from that point to complete the work that was being processed in the failed component. </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/Basic+Routing+Service+Design">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=2129977&revisedVersion=42&originalVersion=41">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>