From MemberWiki

Contents 1 OpenAjax Communication API Proposal 1.1 Overview 1.2 Roadmap 2 Proposed Client API 2.1 Roles 2.1.1 Communication User 2.1.2 Communication Provider 2.1.3 Page Composer 2.2 General Operation 2.3 Connection Factories 2.3.1 Obtaining Connections 2.3.2 Using Connections 3 Providers 3.1 The Default Provider 3.1.1 payload mapping 3.2 The Cometd Provider 4 Proposed Server API 5 Proposed Protocol

OpenAjax Communication API Proposal

This page presents a proposal for an API Ajax Bidirectional Communications, to address some(all?) the issues under consideration by the communication task force.

Overview

The intent of this API is address the issues identified in Problem_Defintion_-_CommunicationTF by:

• abstract away from direct usage of XHR for both request/response and publish/subscribe communications. All Ajax communication users should be able to use this API regardless of their actual protocol or message payload. By encouraging use of this API for almost all Ajax communication, alternative protocols and innovative solutions may retrospectively be applied to existing frameworks and applications.
• provide a pluggable SPI architecture, where implementations of the protocol may be selected and configured independently of usage of the API
• decompose the communications API into aspects for page composers, communication user and communication provider, so that configuration and protocol specific API calls are isolated.

Roadmap

It is envisioned that the open ajax hub communications will evolve over time as experience is gained with the hub and as Ajax communication transports continue to evolve in libraries and in browsers. Thus a three phased approach will be taken to developing communication standards:

1. The establishment of a Client API is the main aim of the initial phase of effort, as this will allow all (or most) Ajax communications to be captured and serviced by future implementations. The providers of client API should be able to be used standalone with existing server-side components, or together with OpenAjax server side components.
2. The development of a Server API should take place in parallel with the client API, but standardization of it will be the main focus of a second phase.
3. Once the APIs and their semantics are finalized, work can proceed on Protocol standardization, as the availability of a default transport should greatly assist uptake. However, it's specification and implementation are deferred to the a third phase so that more experience and feedback can be applied.

Proposed Client API

Roles

The following roles are defined for the purposed of the client side API.

Communication User

The Communication User role is that of the component that uses the communication facilities for application semantics of sending and receiving messages, either in a request/response or in a publish/subscribe mode. The messages sent and received are application level messages and unrelated transport and to the HTTP requests and responses that may (or may not) be sent to deliver the messages. The API used by the Communication User should be abstracted away from all transport concerns and configuration.

Communication Provider

The communication Provider role is that of a component that implements the API used by the Communication User. The API used by the Communication Provider should allow for the registration, discovery and configuration of the available implementations. A communication provider may or may not have a server side component.

Page Composer

A page composer is the developer or system that is responsible for selecting and configuring the communications providers to be used to satisfy the communication User(s) within a page. For example, a developer that knowingly combines two different Ajax frameworks on the same page may act as the Page Composer as they configure the communication providers that will interoperably meet the needs of both frameworks. Alternately a portlet server may fill the role of page composer and would be responsible for initializing and configuring a communications provider that is suitable for all components on the page.

General Operation

The operation of the client API generally follows the steps:

1. The page composer configures connection factories to provide the known communication needs for all components on the current page.
2. The Communication User accesses the communications facilities by requesting a connection instance and using it to send and receive messages.
3. The Communication Provider is passed polymorphically to the Communication User by the connection factories and delivers and receives the the messages on behalf of the Communication User.

Connection Factories

The page compositor may configure the communication system by defining connection factories. If this is not done, then a default configuration factory will be used that will provide a thin veneer over XHR.

openajax.addConnectionFactoryForURL(urlPattern,connectionFactory);
openajax.addConnectionFactoryForId(idOfConsumer,connectionFactory);

eg.

openajax.addConnectionFactory("/",new cometdConnectionFactory("/cometd"));

The factories themselves may be configured with details specific to the particular transport, such as polling intervals, payload types etc. Error handlers should be also be configured on the factories, perhaps with a mapping of destination to handler?

Some thought needs to be given of how to separate this communication configuration into code that is only executed once per page and is specified by the page compositor rather than individual frameworks and components.

Obtaining Connections

Each application, framework and/or UI component will need to obtain a messaging connection object in order to use communication services. The intent is that they are simply accessing the preconfigured connections or connection factories created by the page compositors. A URL may be used to identify a specific host and context. An optional ID is provided to identify the user of the connection (eg framework name or application name). The ID may be used by a factory to access specific configuration.

var connection = openajax.getConnection(id);           // the default connection
var connection = openajax.getConnection(id,init_uri);  // a specific connection

Using Connections

The API below will be provided on all connections, but the exact behaviour of the call will depend on the provider.

connection.request(destination,payload,callback);    // request/response
connection.subscribe(destination,payload,callback);  // messaging subscription
connection.unsubscribe(destination);                 // messaging unsubscription
connection.publish(destination,payload);             // messaging publish
connection.startBatch();                             // start a batch of message sends
connection.endBatch();                               // end a batch of message sends

The destination is a URI style path to identify the scope of the message within the context of the connection. Typically it may be appended to the init_url to form a specific URL or used as an identifier to pass to the service at the init_uri.

Providers

The Default Provider

The default communication provider will simply map the connection API to XHR as follows:

• A request call will be implemented as a GET or POST method on the URL obtained by init_uri+destination. If no payload is provided a GET method will be used. If a payload is provided, then either a POST or GET will be used depending on the configuration of the connection obtained from the factory.
• A subscribe call will start a regular poll with a GET to the URL obtained by init_url+destination. the poll interval will be configured in the connection factory or on the connection.
• A publish call will be implemented as a POST to the URL obtained by init_url+destination
• batching should be ignored (optionally multi-part mime encoding could be used for batching).

The default provider should be sufficient to allow most XHR based applications and frameworks to be simply ported to the ABC API with any or significant changes to their server side components. However, once ported to the ABC API, these applications and frameworks may have alternative providers configured that take advantage of more advanced communication layers and/or resource mediation.

payload mapping

• String to text/plain
• Element to text/xml
• Object to application/form-url-encoded

The Cometd Provider

• destination = channel
• need request/response mapping
• A request call will be implemented as a cometd publish. The current cometd protocol will need to be extended to support transitive subscriptions so that a response may be received.
• A subscribe call will directly map to a cometd subscription.
• A publish call will directly map to a cometd publish.
• batching will be implemented using the current capability in cometd to send/receive JSON arrays of messages.

Proposed Server API

Proposed Protocol