Communications Events Proposal

From MemberWiki

Contents 1 Communication events proposal 1.1 Objectives 1.2 Exclusions 2 Comms Event API 3 Example 3.1 Chat Room: chat.js 3.2 Provider Configuration: index.html

Communication events proposal

This proposal addresses the Problem_Defintion_-_CommunicationTF with an extension to the existing hub event mechanism.

The event hub mechanism provides publish/subscribe semantics to an abstract name space. This proposal is for an API and provider mechanism to bridge the hub events to one of:

• other frames on the same client
• the server
• other clients

The bridging effectively sets a scope or a domain (need to select a non-overloaded noun) for an event topic.

Objectives

• KISS
• The core should be extremely lightweight and potentially able to be included in the hub
• Address the comms issues and not provide a one-size-fits-all API... that is for frameworks
• Separation of communication semantics from communication configuration, so that page aggregators may configure comms for all components on the page.

Exclusions

• RPC style communications are not explicitly supported by this proposal. However the SERVER scoped bridge could easily be used to implement RPC, or multi-response style communications.

Comms Event API

OpenAjax.comms =
{
    BRIDGE_NONE:0,   // Do not bridge the events
    BRIDGE_CLIENT:1, // Bridge the events to all hubs within this client (cross frame)
    BRIDGE_SERVER:2, // Bridge the events to the server, but not other clients
    BRIDGE_WEB:3,    // Bridge the events to all clients connected to the server

    provider: null,  // The comms provider

    // Bridge and event name  
    bridge : function(name,bridgeTo)
    {
       if (OpenAjax.comms.provider==null)
           alert("No OpenAjax.comms.provider");
       else
           OpenAjax.comms.provider.bridge(name,bridgeTo);
    }

    // Start batch (to SERVER and WEB destinations only
    startBatch: function()
    {
       if (OpenAjax.comms.provider==null)
           alert("No OpenAjax.comms.provider");
       else
           OpenAjax.comms.provider.startBatch();
    }

    // End batch (to SERVER and WEB destinations only
    endBatch: function()
    {
       if (OpenAjax.comms.provider==null)
           alert("No OpenAjax.comms.provider");
       else
           OpenAjax.comms.provider.endBatch();
    }
}

The API simply allows a call to OpenAjax.comms.bridge(name,bridgeTo) to define how an event should be bridged into the communications domain. Options include:

NONE: Events are handled normally

CLIENT: Events are bridged to other frames on the same client/browser. This will allow events to be exchanged between tabs and windows that are also running the hub.

SERVER: Events are bridge to the server side and made available via a (yet to be specified) server side API. They will not be available to other clients.

WEB: Events are bridged to the server side and forwarded to all clients that have subscribed to the event.

Example

An example of a chat room with a dojo provider is checked into at the sandpit.

Chat Room: chat.js

The chat room itself is written to the oaa hub event API. A user joins the room with:

room._subscription=OpenAjax.hub.subscribe("chat.room",room._chat,room);
OpenAjax.hub.publish("chat.room",{from:room._username,text:"has joined the room"});

Chat is published to the room with:

OpenAjax.hub.publish("chat.room",{from:room._username,text:text});

The communications aspect of the chat room is a single call that semantically defines that chat should be shared with all clients on the web:

OpenAjax.comms.bridge("chat.room",OpenAjax.comms.BRIDGE_WEB);

Provider Configuration: index.html

The communication provider is specified and configured for the page in index.html

<script language="JavaScript" type="text/javascript" src="dojo/dojo.js"></script>
<script language="JavaScript" type="text/javascript" src="OpenAjaxCommsDojoProvider.js"></script>
<script language="JavaScript" type="text/javascript">
  OpenAjax.comms.provider.init({},"/cometd");
</script>