From MemberWiki

NOTE: This wiki page holds part of the early draft specification for OpenAjax Hub 1.1. It contains all of the finalized and approved content from the OpenAjax Hub 1.0 Specification, plus draft text for the new features in OpenAjax Hub 1.1. Text repeated from the Hub 1.0 spec isidentified by the string [HUB10]. The draft text for the features that are new to Hub 1.1 is identified by the string [HUB11]. At this point, the new features are very early in development and have received little or no review by the Interoperability Working Group. All of the new features should be treated by the community as a work in progress that is not yet ready for use by the community.

[HUB11]: Everything in this chapter describes new features found in OpenAjax Hub 1.1.

Contents 1 Overview 2 Hub API 2.1 List of Functions 2.2 Details 2.2.1 OpenAjax.hub.createManagedHub({[pubCallback:function], [subCallback:function]}) 2.2.1.1 Parameters 2.2.1.2 Return value 2.2.2 OpenAjax.hub.connect({[host:string], clientName:string, callback:function, providerName:string, [connectionConfig:object]}) 2.2.2.1 Parameters 2.2.2.2 Return value 2.2.3 OpenAjax.hub.configureProvider(providerName:string, providerConfig:object) 2.2.3.1 Parameters 2.2.3.2 Return value 2.2.4 connHandle.subscribe(topic:string, callback:function, eventCallback:function) 2.2.4.1 Parameters 2.2.4.2 Return value 2.2.5 subHandle.unsubscribe(callback:function) 2.2.5.1 Parameters 2.2.5.2 Return value 2.2.6 connHandle.publish(topic:string, data:JSON|string) 2.2.6.1 Parameters 2.2.6.2 Return value 2.2.7 connHandle.disconnect(callback:function) 2.2.7.1 Parameters 2.2.7.2 Note 2.2.8 connHandle.bind(clientName:string) 2.2.8.1 Parameters 2.2.8.2 Note 2.2.8.3 Return value 2.2.9 connHandle.getManagerDomain() 2.2.9.1 Return value 3 Other Requirements 3.1 Topic namespace management 3.2 Limited history (last event) 3.3 Topic Payload Typing

Overview

Some general points to aid in understanding the API/SPI:

• Generality of API/SPI: The API/SPI is meant to be general enough to meet the needs of the following scenarios, however is has been written while working out the details of the former scenario only:
  • Mashups with content (like gadgets) sharing the same browser window (inline), or sandboxed in iframes.
  • Client-server messaging, say using Bayeux and Comet.

• Hub 1.1 Overview:
  • New features: The two new features that were not part of Hub 1.0 are:
    • Multiple hub-instances: In Hub 1.0 an OpenAjax.hub object corresponded to one instance of a hub. In Hub 1.1, an OpenAjax.hub object can contain multiple hub-instances. These hub-instances were created in that OpenAjax.hub object, and the creator of a hub-instace also serves as its manager. Others can connect to a hub-instance in a client role, and both the manager and clients can publish and subscribe to the hub-instance using identical APIs (this makes the manager a special kind of client). There are 2 scenarios that directly motivated multiple hub-instances:
      • Composite inline gadgets: These share the same window as the mashup application and are themselves composed of smaller gadgets. All these gadgets and the mashup application share the same OpenAjax.hub object, but for purposes of encapsulation there may be a need to maintain a separate hub-instance for each parent that has child gadgets. Whether there is a separate hub-instance at each level of the hierarchy, or there is only one hub-instance maintained a the top-level (the mashup application) is not specified by OpenAjax and is application (and communication service provider) dependent.
      • Continued support for Hub 1.0: The Hub 1.0 APIs access a different hub-instance than the Hub 1.1 APIs, since the purpose of the former is mainly interoperability between Ajax toolkits.
    • Communication Service Providers: Hub 1.1 supports multiple communication service providers for clients connecting to a hub-instance. For instance, there will be providers for (1) inline clients (that share the same window object as the manager of the hub-instance), (2) iframe clients (that are in a separate iframe than the manager of the hub-instance), (3) clients that are connecting to a hub-instance managed by a server.
  • Support for Gadgets (in mashups): Hub 1.1 offers support for inter-gadget communication in mashups but leaves the details of gadget loading, gadget meta-data, and gadget naming to a higher layer that sits on top of the OpenAjax.hub layer. This higher layer may implement the gadget specification being defined by OpenAjax but that is not a requirement. To the hub, different gadgets are manifested as different clients.
  • Fine-grained policy hooks: Hub 1.1 recognizes the need for control on inter-client communiction for many applications, either due to security requirements, or to mediate between clients that were written independently. However it does not mandate any particular access control or other policy model. It takes the approach of providing fine-grained callbacks to the manager that can be used to layer an arbitrary policy model on top of Hub 1.1.

• Comparison with Hub 1.0: In addition to the differences described above, the current API differs from Hub 1.0 in the following respects:
  • The API is asynchronous, to accomodate the asynchrony of cross-frame and client-server messaging.
  • The data passed on publish is a pure data Object (no functions). Client-server communication and many cross-frame communication mechanisms will serialize and deserialize the data (as JSON) and cannot be expected to handle functions. Furthermore, even mechanisms which allow function passing face a number of subtle security issues around getter and setter functions.
  • The data passed on publish is pass-by-value, not pass-by-reference. Again this is due to the serialization/deserialization performed by many communication mechanisms. It also prevents any concurrency issues given the asynchronous nature of the transfer.
  • Absence of some syntactic features of Hub 1.0 in Hub 1.1: To avoid making the API too complex, we have not included the following syntactic features of Hub 1.0 in the Hub 1.1 API:
    • scope, subscriberData: Closures in JavaScript make these redundant.
    • filter: It is a JavaScript function that the subscriber could call by itself in the callback method. Other publish/subscribe interfaces, like the Java Message Service (JMS), allow specification of a declarative (subset of SQL) filter, which the system can optimize the evaluation of (by aggregating multiple filters, or in a network setting move the filter closer to the source of the events/messages). Since the filter in Hub 1.0 is not a declarative specification, its usefulness may be limited (even for client-server messaging).

• Comparison with OAA Hub 1.1 roadmap document: The API was inspired by the roadmap [1], and therefore has some similarity with it. Some differences are noted below:
  • The roadmap defines a hierarchy using host, room and topic, where a host contains multiple rooms, and a room contains multiple topics. The host is null for browser-side messaging, and room is the abstraction on which an administrative policy can be applied (using manageRoom). We have replaced the explicitly named room abstraction, with a hub-instance abstraction, such that the clients do not need to know about multiple hub-instances managed by a host. This reduces the number of concepts exposed to a client.
  • The roadmap uses secret numbers returned in the connect and join methods to do some level of authentication. They have been dropped, and authentication is handled internally by the communication providers.

Hub API

List of Functions

The OpenAjax Hub 1.1 provides the following APIs for its event management services.

• OpenAjax.hub.createManagedHub()
• OpenAjax.hub.connect()
• OpenAjax.hub.configureProvider()

The connection handle object corresponding to a connection provides the following APIs.

• subscribe()
• unsubscribe()
• publish()
• disconnect()
• bind()

Details

OpenAjax.hub.createManagedHub({[pubCallback:function], [subCallback:function]})

This method creates a new hub-instance, with the creator in the role of a manager. The optional parameters, pubCallback, subCallback are for the fine-grained callbacks to impose some policy.

Parameters

pubCallback (optional)

A callback to invoke on each publish call, for each matching subscription from a client. The default is a callback that always returns true.

subCallback (optional)

A callback to invoke on each subscribe call. The default is a callback that always returns true.

The function signatures for these callbacks are:

• subCallback is defined as boolean function(topic:string, subClientName:string).
  • The topic can contain wildcards (see Hub 1.0 spec).
  • The subClientName is the name of the subscribing client. The assignment of names to clients is described later. The manager of a hub-instance always has the name "manager".
  • A return value of true represents that the subscribe operation is permitted, else it is not permitted.
• pubCallback is defined as boolean function(topic:string, data:JSON|string, pubClientName:string, subClientName:string)
  • The topic does not contain any wild-cards (see Hub 1.0 spec).
  • The data represents the event payload. This allows for the policy to be dependent on the content of the event. The type JSON is used to represent a JavaScript object that is purely data.
  • The pubClientName is the name of the client that published this event.
  • The subClientName is the name of a client whose subscription matched the topic of the event.
  • A return value of true represents that the published event should be sent to the subscribing client, else it is not permitted.

Return value

The return value is a connHandle object, or null if it fails to create a new hub-instance. The connHandle object implements the functions subscribe, unsubscribe, publish ,disconnect and bind described later, as well as the following auxiliary functions:

• The connHandle.isConnected() returns true iff the connection is established and active.
• The connHandle.equals(anotherConnHandle) function returns true if two connection handles represent the same connection, else false.
• The connHandle.getClientName() function returns the client name associated with this connection (in this case, "manager").

OpenAjax.hub.connect({[host:string], clientName:string, callback:function, providerName:string, [connectionConfig:object]})

This method connects a client to an existing hub-instance.

Parameters

host (optional)

It is a URI string representing the manager. It is not used for browser-side messaging.

clientName

The name of the client. This name will typically be chosen for the client by the entity that loaded the client. For scenarios with security requirements (such as clients sandboxed in iframes), a malicious client should not be able to pretend to be a different client.

callback

To accomodate asynchronous connects, in addition to the return value the callback function will be called with success or failure. The callback is defined as function(success:boolean, connHandle:object), where success is a boolean and connHandle is the object returned by the connect method. The callback may be invoked synchronously, just before returning from connect. The callback can be invoked up to two times, once to indicate a successful connection, and once to indicate a later failure of an existing connection.

providerName

Specifies the communication service provider to be used for this connection. Providers will be named using URLs, for instance, there may be providers named http://providers.openajax.org/smash (for a provider based on SMash, when the client is in a different iframe than the hub-instance) and http://providers.openajax.org/inline (for an inline provider, when the client shares the window with the hub-instance).

connectionConfig (optional)

Configures the provider for this connection.

Return value

The return value is a connHandle object, or null if it fails immediately. It implements the same methods as described above.

[rationale] We use an opaque connHandle instead of a connId (used in the current Hub 1.1 roadmap) since it (1) makes the implementation easier as it can dispatch method calls that specify a connHandle, but do not specify a host, without maintaining a mapping from connId to host, (2) handles can contain other handles, like the subHandle described later, so it makes the function signatures simpler. [/rationale]

OpenAjax.hub.configureProvider(providerName:string, providerConfig:object)

This method is used to give configuration parameters to a specific communication service provider. It is not necessary to call this method if default configuration settings will be used for this provider.

Parameters

providerName

The providerName uniquely identifies the provider.

providerConfig

The providerConfig is a data object to configure the provider.

Return value

The return value is a boolean that is true if the provider was found and configured, else false.

connHandle.subscribe(topic:string, callback:function, eventCallback:function)

Parameters

connHandle

The connHandle is the object provided in a previous connect.

topic

The topic can contain wildcards (see Hub 1.0 spec).

callback

The callback is defined as function(success:boolean, subHandle:object). The callback may be invoked synchronously, just before returning from subscribe.

eventCallback

The eventCallback is called for each event on the subscribed topic. It is defined as function(subHandle:object, topic:string, data:JSON|string)

• subHandle is a subscription handle returned by the subscribe method.
• topic is the topic of the event.
• data contains the event payload.

Return value

The method returns a subHandle object, or null if it fails immediately.

The subHandle object implements unsubscribe described in more detail below as well as following auxiliary methods:

• subHandle.isSubscribed() returns true if subscription is active.
• subHandle.getConnHandle() returns the corresponding connHandle.
• subHandle.getTopic() returns the subscription topic.
• subHandle.equals(anotherSubHandle) returns true if two subHandles represent the same subscription, else false.

subHandle.unsubscribe(callback:function)

Parameters

The subHandle, callback are defined the same as in the subscribe method.

Return value

The return value is defined the same as in the subscribe method.

connHandle.publish(topic:string, data:JSON|string)

Parameters

connHandle

The connHandle is the object provided in a previous connect.

topic

The topic does not contain wildcards (see Hub 1.0 spec).

data

The event payload

Return value

The return value is a boolean indicating success or failure. The return value will be false if connHandle.isConnected() !== true.

connHandle.disconnect(callback:function)

This method is used to disconnect from a hub-instance. When called by the manager of the hub-instance, it deletes the hub-instance.

Parameters

connHandle

The connHandle is the object provided in a previous connect.

callback

The callback is defined as function(success:boolean, connHandle:object). The connHandle object is equal to the one on which the disconnect method is invoked. The callback may be invoked synchronously, just before returning from disconnect.

Note

This function can also be used to abort an ongoing connection request.

connHandle.bind(clientName:string)

This method is used by the manager of a hub-instance to bind the given clientName to the particular hub-instance (represented by the connHandle) among the many hub-instances managed by the local OpenAjax.hub object. The method should be called by the manager prior to the client calling OpenAjax.hub.connect.

[rationale] The bind method simplifies the API by avoiding the need for explicit names for hub-instances. Clients do not need to name a particular hub-instance among the many ones potentially implemented by the same OpenAjax.hub object. The effect of this method is local: it updates some tables in the OpenAjax.hub object so that incoming events or requests from a client can be demultiplexed to the appropriate hub-instance. [/rationale]

Parameters

clientName

The client that is being bound to a particular hub-instance by the manager.

Note

All clients of hub-instances managed by the same OpenAjax.hub object should have unique names.

Return value

The return value is a boolean indicating success or failure. The return value is false if the caller is not the manager. The return value is false if the clientName has already been bound to a different hub-instance managed by the same OpenAjax.hub object.

connHandle.getManagerDomain()

This method returns the domain of the manager. It exposes the result of authenticating the manager at connection setup, and can subsequently be used for access control by the client. If called by the manager, the method returns the manager's own domain.

Return value

The return value is a String representing the domain of the manger. The return value will be null if connHandle.isConnected() !== true.

Other Requirements

The following are potential requirements that we need to decide whether Hub 1.1 will address, and if so, how.

Topic namespace management

Certain conventions may need to be adopted for the topic namespace, for various purposes such as (1) interoperability of different AJAX libraries , (2) concurrent non-interfering use of different AJAX libraries (such as in [2]), (3) development of reusable widgets and mashups. These conventions could be documented in the OpenAjax Registry.

For (3), this may include conventions about what parts of the topic namespace are public, are for point-to-point communication etc.

Limited history (last event)

A requirement has been raised for a simplified data persistence feature, where a new subscriber to a topic will get the last event published on that topic prior to the subscription. This is intended to simplify application state initialization of new subscribers.

Topic Payload Typing

For a particular topic, the knowledge of the type of the event payloads could be useful. The type could be a JSON schema, or a string name that is known to have some meaning, like "vcard".